Explanation
Some attributes are coded by a value. That value references an entry in a separate lookup table. Consider an example record with a CBSA:
{
"person_id": "800378494527",
"cbsa_code": "36540",
"first_name": "Joe",
"last_name": "Smith",
"street": "123 9th St",
"city": "Omaha",
"state": "NE"
}
The attribute, cbsa_code: "36540", references an entry in a separate CBSAs table. The Lookup API describes the label and further information about "36540".
Lookup Options
Data Axle offers three mechanisms for working with lookups:
| Lookup Mechanism | Description |
| Lookup Search API | Query lookups by label and value. |
| Lookup Download API | Download and cache all Data Axle lookup tables |
| Inline Labels | Access value:label mappings alongside records |
Lookup Search API
GET /v1/lookups/:collection_name?q=query+string
Search a lookup table by label or value using the Lookup Search API. For example, find the lookup for the CBSA in Omaha:
curl https://api.data-axle.com/v1/lookups/cbsas?q=Omaha
Each result always includes a value and label. Additional information specific to the lookup is also available:
[
{
"value": "36540",
"label": "Omaha-Council Bluffs, NE-IA"
}
]
View Available Tables for a full list of :collection_name values.
Lookup Download API
GET /v1/lookups/:collection_name/download
Download an entire lookup table with the Lookup Download API:
curl https://api.data-axle.com/v1/lookups/cbsas/download
The response includes every lookup entry:
[
{ "value": "10100", "label": "Aberdeen, SD" },
{ "value": "10140", "label": "Aberdeen, WA" },
{ "value": "10180", "label": "Abilene, TX" },
...
]
View Available Tables for a full list of :collection_name values.
Optimize with ETags
The Download API supports ETags. Use ETags to poll the API frequently and receive results only when data changes.
An initial request returns ETag headers:
$ curl -I https://api.data-axle.com/v1/lookups/cbsas/download
HTTP/2 200
content-type: application/json; charset=utf-8
etag: W/"fd194549fea2997da2e9ec2b82d75284"
last-modified: Wed, 13 Jun 2018 12:19:23 GMT
Use the ETag in subsequent requests:
$ curl -I --header 'If-None-Match: W/"fd194549fea2997da2e9ec2b82d75284"' https://api.data-axle.com/v1/lookups/cbsas/download
HTTP/2 304
...
Note the 304 (Not Modified) response with an empty body.
Inline Labels
Use Inline Labels to easily access the label of a lookup value. For example, cbsa_code: "36540" means that the document is in the Combined Statistical Area "Omaha-Council Bluffs, NE-IA".
Inline Labels in APIs
To enable Inline Labels in API responses, add the include_labels=true option to any Data Axle API that returns document records:
curl https://api.data-axle.com/v1/people/search?include_labels=true&query=Joe+Smith
A "labels" field is added to each document in the response:
{
"count": 43507,
"documents": [
{
"person_id": "800378494527",
"cbsa_code": "36540",
"first_name": "Joe",
"last_name": "Smith",
"street": "123 9th St",
"city": "Omaha",
"state": "NE",
"labels": {
"cbsa_code": "Omaha-Council Bluffs, NE-IA",
"state": "Nebraska"
}
}
]
}
The ?include_labels=true feature is available on the following APIs:
Available Tables
Requests to Lookup Search API and Lookup Download API support the following values for :collection_name.
| collection_name | Fields |
attribute_mappings | model, field, value, label |
cbsas | value, label, country_code |
cities | value, label, state, country_code, aliases |
counties | value, label, state, county_code |
csas | value, label |
dma_regions | value, label |
Browse lookup tables online under Product > Lookup Tables.