---
title: "Valet Trash Guide API: free read-only JSON API"
description: "Free, read-only JSON API for valet trash guides, state rules, statistics and cost estimates: operations, examples, pagination, rate limits and errors."
canonical: "https://valettrashguide.com/developers/api/"
last-updated: "2026-11-15"
author: "Valet Trash Guide Editorial Team"
publisher: "Valet Trash Guide"
license: "Quote with attribution and a link to the canonical URL."
---
# 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](https://valettrashguide.com/developers/errors/)).
- CORS: `Access-Control-Allow-Origin: *`, so code on any website can call it.
- Machine-readable description: [OpenAPI 3.1](https://valettrashguide.com/openapi.json). The same data is available as MCP tools at `https://valettrashguide.com/mcp` ([MCP server](https://valettrashguide.com/developers/mcp/)).
- 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. |

```bash
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. |

```bash
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. |

```bash
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). |

```bash
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. |

```bash
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. |

```bash
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). |

```bash
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.

```bash
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):

```json
{
  "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`:

```json
{
  "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:

```json
{
  "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`](https://valettrashguide.com/developers/errors/#missing_parameter), [`invalid_parameter`](https://valettrashguide.com/developers/errors/#invalid_parameter), [`not_found`](https://valettrashguide.com/developers/errors/#not_found), [`method_not_allowed`](https://valettrashguide.com/developers/errors/#method_not_allowed), [`rate_limited`](https://valettrashguide.com/developers/errors/#rate_limited), [`prices_not_published`](https://valettrashguide.com/developers/errors/#prices_not_published), [`unavailable`](https://valettrashguide.com/developers/errors/#unavailable), [`internal_error`](https://valettrashguide.com/developers/errors/#internal_error). Missing or invalid parameters also list each problem in `errors[]`. Details and fixes are on [API error codes](https://valettrashguide.com/developers/errors/).

## 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](#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](https://valettrashguide.com/api/v1/pages.json): every published page with URL, Markdown URL, summary and dates.
- [/api/v1/states.json](https://valettrashguide.com/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](https://valettrashguide.com/api/v1/states/texas.json): one file per state (by slug), with the full research dossier behind the state record.
- [/api/v1/statistics.json](https://valettrashguide.com/api/v1/statistics.json): the statistics bank shown on [/statistics/](https://valettrashguide.com/statistics/).
- [/api/v1/search-index.json](https://valettrashguide.com/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](https://valettrashguide.com/developers/): 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](https://valettrashguide.com/developers/mcp/): 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](https://valettrashguide.com/developers/errors/): Every error the Valet Trash Guide API returns, as RFC 9457 problem+json: what each code means and how to fix the request.
