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:

{
  "first_name": "Joe",
  "last_name": "Smith",
  "workplace": {
    "street": "123 9th St",
    "city": "Omaha",
    "state": "NE",
    "cbsa_code": "36540"
  }
}

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 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://qa.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://qa.api.data-axle.com/v1/lookups/cbsas/download

The response includes every lookup entry: json [ { "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://qa.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://qa.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://qa.api.data-axle.com/v1/b2c_links/search?include_labels=true&query=Joe+Smith

A "labels" field is added to each document in the response:

{
  "count": 43507,
    "documents": [
    {
      "first_name": "Joe",
      "last_name": "Smith",
      "workplace": {
        street": "123 9th St",
        "city": "Omaha",
        "state": "NE",
        "cbsa_code": "36540",
      }
      "labels": {
        "workplace": {
          "cbsa_code": "Omaha-Council Bluffs, NE-IA",
          "state": "Nebraska"
        }
      }
    }
  ]
}

The ?include_labels=true feature is available on the following APIs:

• Search API
• Scan API
• Match API

Available Tables

Requests to Lookup Search API and Lookup Download API support the following values for :collection_name.

Browse lookup tables online under Product > Lookup Tables.