Geography
Look up official areas and draw drive-time areas.
Draw drive-time areas (2 credits each)
POST /v1/isochrones
Returns the outline of everywhere you can reach from a point within a set number of minutes by car, on foot or by bike, using travel times without traffic delays. This outline is called an isochrone.
Use this when you need the shape itself, for example to draw it on a map. To get numbers
for the area, send it to /enrich instead; you don't need to draw it first. Each area is
drawn on the roads in the release you choose, so the same request always gets the same
outline. If one area fails, the others still come back; the failed area carries an error
and isn't charged.
The roads come from OpenStreetMap. Wherever you show an outline, credit "© OpenStreetMap contributors".
Parameters
| Name | In | Type | What it is |
|---|---|---|---|
Kadrin-Max-Credits | header | integer | The most you're willing to spend on this request. If the estimated cost is higher, we stop before running it, charge nothing, and return error 402. |
Request body
object as application/json.
| Field | Type | What it is |
|---|---|---|
isochronesrequired | array of any | The drive-time areas to draw, up to 100. |
simplify | boolean | Smooth the outline so it's smaller to download. On by default, and the outline /enrich uses for the same area. Off, the outline has about five times as many corner points. Default |
release | string | Which data release's roads to use (a frozen snapshot, such as 2026.12). Name one to get the same outline every time; |
Answers
| Status | When | Body |
|---|---|---|
| 200 | The outlines. An area that failed has an error instead of a geometry. | object |
| 400 | Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.) | Problem |
| 401 | Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.) | Problem |
| 402 | Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.) | Problem |
| 413 | Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.) | Problem |
| 422 | Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.) | Problem |
| 429 | Too many requests in a short time. Wait the number of seconds in Retry-After, then try again. | Problem |
| 503 | Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.) | Problem |
Find official areas by name or location
GET /v1/geographies/lookup
Send a place name (such as 'Cook County, IL' or a ZIP code), or a latitude and longitude, and get back the official areas that match or contain it. Each comes with its GEOID, the ID number the government gives each area, which you can then send to /enrich.
Send either q, or both lat and lon. A name can be followed by a comma and a state, such
as 'Boston, MA', and small misspellings are fine. You get up to 10 matches, closest first.
Congressional and state legislative districts aren't available yet. Free, up to 600 requests a
minute.
Parameters
| Name | In | Type | What it is |
|---|---|---|---|
lat | query | number | Latitude (how far north), such as 42.36 for Boston. |
lon | query | number | Longitude (how far east or west; negative in the US), such as -71.06 for Boston. |
q | query | string | A place name, county, city, ZIP code or district. |
levels | query | array of GeographyLevel | Only return these kinds of area, such as county or tract. Separate several with commas. |
Answers
| Status | When | Body |
|---|---|---|
| 200 | Matching areas. | object |
| 400 | Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.) | Problem |
| 401 | Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.) | Problem |
| 422 | Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.) | Problem |
| 429 | Too many requests in a short time. Wait the number of seconds in Retry-After, then try again. | Problem |