Valet Trash Guide API
A free, read-only JSON API with no key and no signup: search, pages, state rules and renter data, sourced statistics and the valet trash cost estimate.
Basics
- Base URL:
https://valettrashguide.com/api/v1/ - Authentication: none. No key, no account, no signup.
- Methods:
GET(plusHEADandOPTIONS). The API is read-only. - Format: JSON (
application/json). Errors areapplication/problem+json(error codes). - CORS:
Access-Control-Allow-Origin: *, so code on any website can call it. - Machine-readable description: OpenAPI 3.1. The same data is available as MCP tools at
https://valettrashguide.com/mcp(MCP server). - Cite the canonical page URL (
url) that comes with each result.
Operations
Search published pages by keyword
GET /api/v1/search, operationId searchGuides
Ranked keyword search across published state and metro guides, how-to guides, comparisons, blog posts and policy pages. Each result links the canonical page to cite and its Markdown version.
| Parameter | In | Required | Description |
|---|---|---|---|
q |
query | yes | Search keywords, 2-200 characters. |
type |
query | no | Restrict to one page type (one of states, metros, guides, compare, blog, pages). |
limit |
query | no | Items per page (1-50) (min 1, max 50, default 10). |
cursor |
query | no | Opaque cursor from pagination.next_cursor. Omit it for the first page. |
curl -sS 'https://valettrashguide.com/api/v1/search?q=fire+code&limit=5'
Returns SearchResultList. Errors: 400, 429, 500, 503.
List published pages
GET /api/v1/pages, operationId listPages
Every published page with its canonical URL, Markdown URL, one-line summary and dates, optionally filtered by page type.
| Parameter | In | Required | Description |
|---|---|---|---|
type |
query | no | Restrict to one page type (one of states, metros, guides, compare, blog, pages). |
limit |
query | no | Items per page (1-50) (min 1, max 50, default 10). |
cursor |
query | no | Opaque cursor from pagination.next_cursor. Omit it for the first page. |
curl -sS 'https://valettrashguide.com/api/v1/pages?type=pages&limit=10'
Returns PageList. Errors: 400, 429, 500, 503.
List the 50 states and DC
GET /api/v1/states, operationId listStates
Every state and DC with Census renter counts (households in buildings with 5+ units and their rank) and links to the state guide, where one is published, and to the full state record.
| Parameter | In | Required | Description |
|---|---|---|---|
limit |
query | no | Items per page (1-50) (min 1, max 50, default 10). |
cursor |
query | no | Opaque cursor from pagination.next_cursor. Omit it for the first page. |
curl -sS 'https://valettrashguide.com/api/v1/states?limit=50'
Returns StateList. Errors: 400, 429, 500, 503.
Get valet trash rules and data for one state
GET /api/v1/states/{state}, operationId getStateGuide
Valet trash rules and data for one US state or DC: fire code and enforcement, apartment recycling rule, fee disclosure law, Census renter counts and trash collector wages, each with a source, plus links to the state guide when one is published.
| Parameter | In | Required | Description |
|---|---|---|---|
state |
path | yes | State slug (new-york), name (New York) or two-letter code (NY). |
curl -sS https://valettrashguide.com/api/v1/states/texas
Returns StateGuide. Errors: 404, 429, 500, 503.
List or search sourced statistics
GET /api/v1/statistics, operationId listStatistics
The sourced statistics bank shown on /statistics/: valet trash prices, resident fees, apartments and renters, waste, recycling, labor and fire safety. With q, results are ranked by relevance; without it they come in bank order.
| Parameter | In | Required | Description |
|---|---|---|---|
q |
query | no | Keywords or a statistic id. |
topic |
query | no | Restrict to one topic (one of valet-pricing, resident-fees, market-players, service-norms, housing-stock, renter-preferences, construction, waste-generation, recycling, mandates, tipping-fees, labor, fire, pests, junk-fees). |
limit |
query | no | Items per page (1-50) (min 1, max 50, default 10). |
cursor |
query | no | Opaque cursor from pagination.next_cursor. Omit it for the first page. |
curl -sS 'https://valettrashguide.com/api/v1/statistics?q=renter+households&limit=5'
Returns StatisticList. Errors: 400, 429, 500, 503.
Get one statistic by id
GET /api/v1/statistics/{id}, operationId getStatistic
One statistic with its value, unit, scope, publisher, source URL, publication date and confidence. Find ids with listStatistics.
| Parameter | In | Required | Description |
|---|---|---|---|
id |
path | yes | Statistic id. |
curl -sS https://valettrashguide.com/api/v1/statistics/us-renter-households-2024
Returns Statistic. Errors: 404, 429, 500, 503.
Estimate valet trash cost for a property
GET /api/v1/estimate, operationId estimateValetTrashCost
Monthly and annual valet trash service cost for one apartment community from its unit count, pickup nights per week and optional doorstep recycling, using the per-door price ranges published on the site. Returns low-high ranges, per-door rates, labeled assumptions and the price sources.
| Parameter | In | Required | Description |
|---|---|---|---|
units |
query | yes | Apartment units (doors) served (min 1, max 5000). |
nights |
query | no | Pickup nights per week (one of 5, 6, 7). |
recycling |
query | no | Add doorstep recycling (default false). |
curl -sS 'https://valettrashguide.com/api/v1/estimate?units=250&nights=5&recycling=false'
Returns Estimate. Errors: 400, 429, 500, 503.
Get API status
GET /api/v1/status, operationId getApiStatus
Whether the API is up, its major version and where its documentation lives.
curl -sS https://valettrashguide.com/api/v1/status
Returns ApiStatus. Errors: 429, 500.
Example responses
GET /api/v1/estimate?units=250&nights=5 (sources shortened):
{
"units": 250,
"nights_per_week": 5,
"recycling": false,
"currency": "USD",
"monthly": {
"low": 2000,
"high": 4500
},
"annual": {
"low": 24000,
"high": 54000
},
"per_door": {
"low": 8,
"high": 18
},
"assumptions": [
"Real quotes depend on building layout, number of floors and stairs, distance to the compactor, contract length and local labor costs."
],
"sources": [
{
"name": "Property Manager Insider: about $8-$15 per unit per month (2018)",
"url": "https://propertymanagerinsider.com/how-much-does-valet-trash-service-cost/"
}
],
"method_url": "https://valettrashguide.com/tools/valet-trash-cost-calculator/",
"prices_updated": "2026-11-15"
}
GET /api/v1/statistics/us-renter-households-2024:
{
"id": "us-renter-households-2024",
"statistic": "The U.S. had 46.1 million renter households in 2024.",
"value": 46101640,
"unit": "renter-occupied housing units (households)",
"scope": "United States, 2024 (ACS 1-year)",
"topic": "housing-stock",
"publisher": "National Multifamily Housing Council (NMHC)",
"source_title": "What Type of Structure Do Renters Live In? (Quick Facts data download)",
"source_url": "https://www.nmhc.org/globalassets/research--insight/quick-facts/resident-demographics/what-type-of-structure-do-renters-live-in.xlsx",
"published": "2026-01 (table updated)",
"retrieved": "2026-11-15",
"confidence": "high",
"page_url": "https://valettrashguide.com/statistics/#housing-stock"
}
Every list operation wraps its items the same way:
{
"query": "fire code",
"type": null,
"data": [
"…items…"
],
"pagination": {
"limit": 10,
"has_more": true,
"next_cursor": "eyJvIjoxMH0",
"total": 23
}
}
Pagination
List operations (search, pages, states, statistics) take limit (1-50, default 10) and an opaque cursor. Each response has a pagination object: limit, has_more, next_cursor and total. To get the next page, pass next_cursor back as cursor with the same other parameters; it is null on the last page. The same URL is in the Link: <...>; rel="next" header. A cursor that was not issued by the API returns invalid_parameter.
Rate limits
The API allows 60 requests per 60 seconds per client IP address. Every API response carries the IETF headers RateLimit-Policy: "default";q=60;w=60 and RateLimit: "default";r=<remaining>;t=<seconds until reset> (draft-ietf-httpapi-ratelimit-headers-11). Over the limit you get 429 with Retry-After. Header values are counted per server instance, so treat them as a hint; Netlify enforces the limit itself. The MCP server allows 120 requests per 60 seconds. The bulk files are plain static files without these headers.
Errors
Errors are RFC 9457 problem details with a stable code: missing_parameter, invalid_parameter, not_found, method_not_allowed, rate_limited, prices_not_published, unavailable, internal_error. Missing or invalid parameters also list each problem in errors[]. Details and fixes are on API error codes.
Versioning
The major version is in the path: /api/v1/. Responses carry API-Version: 1.
- Additive changes ship without notice and without a new version: new operations, new optional parameters, new response fields. Ignore fields you do not know.
- Breaking changes (removing or renaming a field, changing a type or a default) ship only under a new path such as
/api/v2/. The old version keeps working for at least 6 months after the new one launches. - During that time, responses from deprecated operations carry
Deprecation(RFC 9745),Sunset(RFC 8594, the date it may stop working) andLink: <https://valettrashguide.com/developers/api/#changelog>; rel="deprecation". The changelog lists every deprecation. - No operation is deprecated today.
Bulk downloads
Static JSON files with everything in one request. They update with each deploy and are served from the CDN without rate-limit headers.
- /api/v1/pages.json: every published page with URL, Markdown URL, summary and dates.
- /api/v1/states.json: all 50 states and DC with Census renter data and the at-a-glance rules table.
- /api/v1/states/texas.json: one file per state (by slug), with the full research dossier behind the state record.
- /api/v1/statistics.json: the statistics bank shown on /statistics/.
- /api/v1/search-index.json: the compact index behind search.
Changelog
- 2026-11-15: Version 1. Operations for search, pages, states, statistics, the cost estimate and status; cursor pagination; RFC 9457 errors with stable codes; IETF RateLimit headers; OpenAPI 3.1 description.
More developer docs
- Valet Trash Guide for developers and AI agents: Free, read-only access to valet trash guides, state rules, sourced statistics and cost estimates: JSON API, MCP server, WebMCP and Markdown. No key.
- Valet Trash Guide MCP server: Connect an AI assistant to Valet Trash Guide over MCP (Streamable HTTP): search guides, read pages, get state rules, cite statistics, estimate costs.
- API error codes: Every error the Valet Trash Guide API returns, as RFC 9457 problem+json: what each code means and how to fix the request.