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 (plus HEAD and OPTIONS). The API is read-only.
  • Format: JSON (application/json). Errors are application/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) and Link: <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.

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.