API reference

Facts about any place in the US, for exactly the area you care about.

Kadrin gives you facts about any place in the US: who lives there, what they earn, housing, jobs, businesses, health, schools, getting around, tax incentive zones, internet service, what households spend, how people spend their time, and environmental hazards and oil and gas wells.

Send a place in whatever form you have it: a single point, a radius (everywhere within a set distance), a drive-time area (everywhere you can reach by car in a set number of minutes; walking and biking work too), your own outline, or an official area such as a county or a census tract (a neighborhood-sized area of about 4,000 people). Kadrin returns the numbers for exactly that place.

When your shape only partly covers official areas, we estimate its numbers by looking at where people actually live inside each area it touches, using the 2020 Census. This is called apportionment.

Every number comes with:

• its source (where it comes from, such as the U.S. Census Bureau) and vintage (the years it describes, such as 2020-2024);
• how it was combined for your shape;
• its margin of error (how far the true number could reasonably be from our estimate). Many numbers come from surveys of some households rather than a count of everyone, so they are estimates.

Data is organized by topic: demographics, income, housing, labor (the labor market), businesses and environment (oil and gas wells, for now). IDs read as topic, group, measure, for example income.household.median.

You pay in credits. One credit covers one group of related measures for one place. Drawing a drive-time area costs 2 credits more, whether you want its numbers (/enrich) or its outline (/isochrones). Browsing the catalog, previewing a cost and failed requests are free.

Each API key can make 60 requests a minute to /enrich and /isochrones, and 600 a minute to everything else. Every answer says how many are left in its RateLimit headers; past the limit you get a 429 with Retry-After, the seconds to wait.

Drive-time areas are drawn on roads from OpenStreetMap. Wherever you show one, credit "© OpenStreetMap contributors".

Kadrin Batch, our app for spreadsheets of places, signs people in with an email and password and uses this same API for them, metered and limited like an API key. API keys are for your own code.

Base address

Every endpoint is under https://api.kadrindata.com/v1. Requests and answers are JSON, except /jobs files.

Keys

Your API key, sent in the Authorization header as "Bearer ". Keys starting kdr_live_ use real data and are billed. Keys starting kdr_test_ return made-up sample data for free, for testing.

Make keys on the Keys page in Kadrin Batch. See the API quickstart.

Endpoints

Changes

• 0.3.1 (Oct 20, 2026): an oil and gas wells value's vintage is the date the state's well records describe: the day we fetched them, or an earlier date where the only public copy is older (Mississippi's is from July 22, 2025). A place reaching states with different dates gets the earliest and latest, such as 2025-07-22 to 2026-10-20.
• 0.3.0 (Oct 20, 2026): topic environment, group environment.wells: oil and gas wells from each state's oil and gas regulator, counted inside your shape by where they stand (active, idle, orphaned or plugged); the people and homes within 1 km of an active or idle well, added up from census blocks (block_sum); and new drilling permits over the last 12 full months and the change from the 12 before, where a state publishes them with locations (Texas, for now). Only the states whose well records we have count: as for building permits, a value's coverage is the share of your place's homes in them, with the warning partial_coverage when that's less than all and no number when it's none. States with no oil or gas production show no active or idle wells.
• 0.2.14 (Oct 19, 2026): a building permit value's coverage counts only the cities whose permits show that kind of work: where a city's permits don't say which are EV chargers or heat pumps, its homes count as not covered for those, so the number is never an undercount.
• 0.2.13 (Oct 19, 2026): group housing.building: building permits that cities publish (new homes, demolitions, renovations and what they cost, solar panels, EV chargers and heat pumps), counted inside your shape over the last 12 full months, and the change from the 12 months before; vintage gives the months, such as 2025-10 to 2026-09. Only cities whose permits we have count: a value's coverage is the share of your place's homes in them, with the warning partial_coverage when that's less than all and no number when it's none. Aggregations point_sum and point_change.
• 0.2.12 (Oct 18, 2026): group housing.permits: new homes approved with building permits, from the Census Bureau's Building Permits Survey, which publishes them for counties. A shape gets each county's number shared out by where its homes are, with resolution county and the warning coarser_resolution, whose wording now fits numbers worked out from larger areas.
• 0.2.11 (Oct 11, 2026): an error's type links to its entry in the docs, at https://docs.kadrindata.com/errors# (it was kadrindata.com/docs/errors). The docs are at docs.kadrindata.com.
• 0.2.10 (Oct 11, 2026): /jobs reads columns by their common names ("Latitude", "Zip Code", "Street Address") or by place_columns, numbers rows when the file has no id column, and its cost preview shows how the file was read (JobCostEstimate). GET /jobs lists the account's recent jobs; Job gains file_name, preset, created_at and finished_at.
• 0.2.9 (Oct 10, 2026): presets (GET /presets, and preset in /enrich and /jobs) ask for a site report or a submarket report by name. Job growth (group labor.growth): the change in jobs over the last 5 and 10 years, as a number and a percent, ranked against census tracts like rates; new type change, aggregations block_change and block_percent_change, and the warning no_base. /jobs files can give addresses instead of coordinates (found with the Census Bureau's geocoder; error address_not_found), and results can keep the file's own columns (keep_columns) and use plain-language headers (columns: labels).
• 0.2.8 (Oct 10, 2026): a release made later in the same month gets a third number, such as 2026.11.1 after 2026.11; releases are listed and latest is chosen by those numbers.
• 0.2.7 (Oct 10, 2026): /jobs works. around turns uploaded points into radius or drive-time areas; DELETE /jobs/{id} cancels a job; options.dry_run previews a job's cost; Job gains release and expires_at; the results' columns are described under JobSpec's output_format; webhooks carry only the job's ID and status.
• 0.2.6 (Oct 10, 2026): options.benchmarks works: each measure's county, state and US values, and for rates and medians the place's percentile among those areas' census tracts. Looking up areas by name, ZIP code, GEOID or location works. Rate limits are stated (60 and 600 requests a minute), with 429 answers on every endpoint.
• 0.2.5 (Oct 9, 2026): drawing a drive-time area costs 2 credits, in /enrich or /isochrones (it was 10 in /isochrones and nothing extra in /enrich). /isochrones takes a release, can fail one area without failing the rest, and returns request_id, release and sources like /enrich. A drive-time area must start within 5 km (3 miles) of a road. Release 2026.11 has no road data, so drive-time areas start with the next release. The example tract is now one that exists in 2020.
• 0.2.4 (Oct 9, 2026): adds the error code invalid_request, for a request that needs fixing as a whole, such as broken JSON or more than 100 places. The production address is api.kadrindata.com.
• 0.2.3 (Oct 8, 2026): adds the warning method_disagreement, for numbers that depend heavily on where people live inside the areas your shape cuts.
• 0.2.2 (Oct 8, 2026): adds the warnings top_coded and bottom_coded for medians at the top or bottom of the published range.
• 0.2.1 (Oct 8, 2026): plain-language descriptions throughout; no changes to fields or behavior.
• 0.2.0 (Oct 8, 2026): topic-based IDs replace source-based IDs; adds topics to /enrich and /jobs, a topic filter on /variables and /groups, and the /topics endpoint.