Enrichment
Get numbers for the places you send.
Get numbers for up to 100 places
POST /v1/enrich
Send up to 100 places and say what you want: whole topics, groups of related measures,
single measures, or indices (single scores that combine several measures). You get one
result per place. If one place fails, the others still come back; the failed place
carries an error and isn't charged.
To see the cost first, for free, set options.dry_run to true. For more than 100
places, use /jobs.
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
EnrichRequest as application/json.
| Field | Type | What it is |
|---|---|---|
preset | string | A ready-made request by name (GET /presets lists them): its groups and comparisons are added to anything else you ask for. Its suggested area isn't applied for you; send that shape as the place. |
areasrequired | array of Area | The places, up to 100. For more, use /jobs. |
topics | array of TopicId | Whole topics, such as demographics. You pay one credit for each group in the topic, per place. |
groups | array of string | Groups of related measures, such as housing.costs. One credit per group per place. |
variables | array of string | Single measures, such as income.household.median. You pay for the group each one belongs to, once per group per place. |
indices | array of string | Indices (single scores that combine several measures), such as kadrin.economic_momentum. Three credits each per place. |
options | EnrichOptions | Optional settings. The defaults suit most uses. |
Send at least one of preset, topics, groups, variables or indices.
For example:
{
"areas": [
{
"id": "store-12",
"geometry": {"type": "isochrone", "center": [-71.0589, 42.3601], "mode": "drive", "minutes": 10}
},
{"id": "tract-a", "geometry": {"type": "geoid", "geoid": "25025070102"}}
],
"topics": ["demographics"],
"groups": ["housing.costs"],
"variables": ["income.household.median", "labor.jobs.total"],
"indices": ["kadrin.economic_momentum"],
"options": {"release": "latest", "benchmarks": ["county", "state", "us"]}
}
Answers
| Status | When | Body |
|---|---|---|
| 200 | One result per place, or a cost estimate if dry_run was on. A place that failed has an error instead of values. | EnrichResponse or CostEstimate |
| 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 |