Developer resources API v1

Use deaf data in your own tools.

Query Census survey estimates, try requests in your browser, and copy the code into your project.

Try the API OpenAPI 3.1 specification

API playground

Try a request.

Choose an endpoint. Send a request.
See exactly what comes back.

GET

/api/v1/catalog

Find available metrics, dimensions, and supported query combinations for a selected release.

Returns Release and methodology versions, metric definitions, query capabilities, and limits.

Request

No authentication

release optionalChoose a release ID. Leave blank to use the default available release.

1curl --request GET \
2  --url 'https://deaf-data.vercel.app./api/v1/catalog' \
3  --header 'Accept: application/json'

Queries this site’s API

Response

Live API result

No request sent yet.

Run a request to see the response, headers, and timing.

Responses come directly from the API.

Queries run when you select Run request. Loading an example reads the metric, release, and geography catalogs.

Quick start

Make your first query.

Prefer a visual explorer?

01
Choose your data

Find a release, then use its catalog to discover metrics and supported query combinations.
Browse releases
02
Make your first query

Load an example, adjust the request, and run it. Copy the code into your project.
Try an aggregate query
03
Keep the context

Export results with their uncertainty, reliability labels, release version, and generated citation.
Explore exports

API reference

Working with the API

Access & request limits

V1 is public and anonymous. No API key or cookies are needed, and cross-origin requests are supported.

Query & export rate: 60 requests / minute
Burst allowance: 10 requests
Request body: 1 MiB (1,048,576 bytes) maximum

The query and export routes share a limit per client IP and server instance. A deployment-wide limit requires an edge firewall rule. On 429, wait for the Retry-After header before retrying. Cache catalog and definition responses according to their cache headers.

Pagination & exporting larger results

Query responses return at most 250 rows per page. Set page.limit to choose a smaller page. For the next page, send the same query with page.cursor set to the returned page.nextCursor. Stop when it is null.

Send exports as { "query": { … }, "format": "csv" }, using "csv" or "json" for the format. Each export includes up to 10,000 aggregate rows. Keep the exported title, source, period, reliability fields, and citation with your data.

Building a compatible query

Use a single complete entry in the catalog’s queryCapabilities. Its metric, geography types, populations, breakdowns, filters, and calculations describe a supported combination. Combining fields from unrelated entries can return 422.

Pin the release ID, its product, and methodology version. Select covered geography IDs from /api/v1/geographies?release=…. Availability varies by release.

Read metric definitions

Uncertainty, suppression & privacy

Each estimate includes uncertainty and a reliability status: stable, unstable, or suppressed. Preserve these fields when presenting results.

A suppressed estimate is null, with a suppression reason. Do not treat it as zero or try to reconstruct it. The API serves curated aggregates only; raw PUMS records, arbitrary SQL, and person-level queries are not available.

Read the methodology

Data and citations

Keep the source with the result.

Keep the release, full survey period, product, methodology and definition versions, source-manifest hash, query hash, and generated citation alongside your results. The active release can change; your analysis should remain traceable.

Release history Methods & reliability

Keep with every resultrelease + product + periodLabelmethodologyVersion + definitionVersionqueryHash + sourceManifestHashcitation