Explanation

Some attributes are coded by a value. That value references an entry in a separate lookup table. Consider an example record with a primary SIC code:

{
  "infogroup_id": "255947954",
  "name": "Panera Bread",
  "street": "526 John Ross Pkwy",
  "city": "Rock Hill",
  "postal_code": "29730-9035",
  "state": "SC",
  "primary_sic_code_id": "581208"
}

The attribute, primary_sic_code_id: "581208", references an entry in a separate SIC table. The Lookup API describes the label and further information about "581208".

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 Coinstar chain:

curl https://qa.api.data-axle.com/v1/lookups/chains?q=coinstar

Each result always includes a value and label. Additional information specific to the lookup is also available:

[
  {
    "value": "06916859-9abc-43c7-9a16-67a7d46ac21c",
    "label": "Coinstar",
    "sic_codes": ["738905"],
    "country_code": "US"
  }
]

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/sic_codes/download

The response includes every lookup entry:

[
  {"value": "508523", "label": "Abrasives (Whls)"},
  {"value": "516904", "label": "Absorbents (Whls)"},
  {"value": "573606", "label": "Accordions"},
  ...
]

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/sic_codes/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/sic_codes/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, primary_sic_code_id: "581208" means that the place is a "Restaurant".

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/places/changes?include_labels=true

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

{
  "next_token": "13835315192676945401741312",
  "changes": [
    {
      "infogroup_id": "985166431",
      "type": "update",
      "current": {
        "name": "New York Pizza",
        "primary_sic_code_id": "581208",
        "labels": {
          "primary_sic_code_id": "Restaurants"
        }
      },
      "previous": {
        "primary_sic_code_id": "581301",
        "labels": {
          "primary_sic_code_id": "Bars"
        }
      },
      "timestamp": "2015-12-20T05:45:15Z"
    }
  ]
}

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

• Changes API
• Search API
• Scan API
• Match API

Inline Labels in File Delivery

File Deliveries support optional labels. When attributes have mapped values, a "labels" key is emitted with the same JSON structure used with the APIs:

JSON Format

The JSON "labels" key appears at the end of the place object:

{
  "cbsa_code": "36540",
  "state": "NE",
  "labels": {
    "cbsa_code": "Omaha-Council Bluffs, NE-IA",
    "state": "Nebraska"
  }
}

XML Format

A label key is emitted within each element:

<place>
  ...
  <cbsa_code label="Omaha-Council Bluffs, NE-IA">36540</cbsa_code>
  <state label="Nebraska">NE</state>
  ...
</place>

CSV Format

The label is emitted in a column immediately following the attribute value.

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.