Delivery Schema

< Prev Next >

How to consume Data Axle data

Overview

Data Axle's schema is designed to be straightforward and flexible, while retaining the depth and breadth of information Data Axle is known for.

Fields

Data Axle objects are defined by fields. For example, the zip field describes the zip code on record. The following properties define a field:

Property	Description	Example
`name`	The attribute name as it appears in the API. It is always lowercased and underscored.	`first_name`
`display name`	The friendly name is used on Data Axle web pages.	First Name
`type`	Specifies how the data is stored and delivered.	string

See the Data Dictionary for a list of all fields.

Field Ordering

Field ordering within files is dynamically based on groupings in the Data Dictionary, and is subject to change. Never assume fixed field positions in files. Instead, rely on key/value logic within your ingestion program.

Types

The format of each type may vary based on the feed format.

Type	Description
boolean	A true or false value
date	A specific day of the calendar year in ISO 8601 format
float	A signed number with a component
integer	A signed number without a decimal component
string	A sequence of characters
time	Represents both a date and time and is output in ISO 8601 format
array	A list of values
integer_range	An estimate of a value within a set of bounds
date_range	An estimate of a date within a set of bounds
geo_point	A geographic point with latitude & longitude values

Boolean

Boolean values are true, false, or blank. A blank value does not mean it is false.

Date

Dates are always specified according to the ISO 8601 (YYYY-MM-DD) standard.

Example: 2005-07-30

Float

Example: 173.41

Integer

Example: 42

String

Example: Hello World

Time

Times are always specified according to the ISO 8601 standard extended format, in Coordinated Universal Time (UTC)

2017-10-26T04:58:15Z

Array

Arrays represent a series of values.

JSON Example

{
  "languages_spoken": ["english", "japanese"]
}

XML Example

<languages_spoken>
  <value>english</value>
  <value>japanese</value>
</languages_spoken>

CSV Example

languages_spoken
"english,japanese"

Integer Range

Integer ranges are inclusive. For example, a range from 1 to 3 includes the values 1, 2, and 3.

The lower and upper values are formatted as integers. If the upper value is omitted (or null, when using the JSON format), the range is unbounded on that end.

JSON Example

When bounded:

{
  "estimated_daily_visitors": [120, 180]
}

When unbounded:

{
  "estimated_daily_visitors": [150, null]
}

XML Example

When bounded:

<estimated_daily_visitors lower="100" upper="120"/>

When unbounded:

<estimated_daily_visitors lower="50"/>

CSV Example

When bounded:

estimated_daily_visitors.lower, estimated_daily_visitors.upper
80,                             110

When unbounded:

estimated_daily_visitors.lower, estimated_daily_visitors.upper
90,

Date Range

Date ranges are inclusive. For example, a date range between 2017-03-01 and 2017-03-31 includes March 1st and March 31st.

The lower and upper values are formatted as dates.

JSON Example

{
  "estimated_move_in_date": ["2017-07-01", "2017-07-11"]
}

XML Example

<estimated_move_in_date lower="2017-07-01" upper="2017-07-11"/>

CSV Example

estimated_move_in_date.lower, estimated_move_in_date.upper
2017-07-01,                   2017-07-11

GeoPoint

JSON Example

{
  "geocoordinate": {"lat": 30.298103, "lon": -81.394095}
}

XML Example

<geocoordinate>
  <lat>30.298103</lat>
  <lon>-81.394095</lon>
</geocoordinate>

CSV Example

geocoordinate.lat, geocoordinate.lon
30.298103,         -81.394095

Nested Objects

Nested objects express a piece of data with several attributes or collections of data.

Singular Nested Objects

An example of data with many attributes would include a Person's family:

JSON Example

{
  "family": {
    "adult_count": 2,
    "behaviors": [
      "smart_phones",
      "high_end_apparel"
    ],
    "children_count": 0,
    "home_owner": false
  }
}

XML Example

<family>
  <adult_count>2</adult_count>
  <behaviors>
    <value>smart_phones</value>
    <value>high_end_apparel</value>
  </behaviors>
  <children_count>0</children_count>
  <home_owner>false</home_owner>
</family>

CSV Example

family.adult_count, family.behaviors,                family.children_count, family.home_owner
2,                  "smart_phones,high_end_apparel", 0,                     false

Nested Object Collections

The list of contacts associated with a Place is an example of a nested object collection:

JSON Example

{
  "contacts": [
    {
      "id": "63ca41bb84594b9fa007eafd7a8881de",
      "first_name": "Jerry",
      "last_name": "Williams",
      "email": "jerryw@acme.net"
    },
    {
      "id": "5cab2f7b884a4c549dab290d4425036a",
      "first_name": "Sally",
      "last_name": "Smith",
      "professional_title": "DDS"
    }
  ]
}

XML Example

<contacts>
  <item>
    <id>63ca41bb84594b9fa007eafd7a8881de</id>
    <first_name>Jerry</first_name>
    <last_name>Williams</last_name>
    <email>jerryw@acme.net</email>
  </item>
  <item>
    <id>5cab2f7b884a4c549dab290d4425036a</id>
    <first_name>Sally</first_name>
    <last_name>Smith</last_name>
    <professional_title>DDS</professional_title>
  </item>
</contacts>

CSV Example

infogroup_id, first_name, last_name, email,           professional_title
421766665,    Jerry,      Williams,  jerryw@acme.net,
421766665,    Sally,      Smith,                    , DDS

In the CSV format, nested object collections are delivered in a separate file. For example, when contacts are selected for a delivery, both a places file and a contacts file are generated.

Perspectives

A perspective indicates which part of the record is considered the top level. For example, specifying a contacts perspective on a place delivery produces a file of contacts instead of places.

The following perspectives are supported for places:

benefit_plans
contacts
happy_hours
images
location_intents
ucc_filings

The following perspectives are supported for people:

cell_phones
emails
vehicles

JSON Example

{
  "id": "63ca41bb84594b9fa007eafd7a8881de",
  "first_name": "Jerry",
  "last_name": "Williams",
  "email": "jerryw@acme.net",
  "place": {
    "infogroup_id": "421766665",
    "name": "Acme Dentistry"
  }
}

XML Example

<contact>
  <id>63ca41bb84594b9fa007eafd7a8881de</id>
  <first_name>Jerry</first_name>
  <last_name>Williams</last_name>
  <email>jerryw@acme.net</email>
  <place>
    <infogroup_id>421766665</infogroup_id>
    <name>Acme Dentistry</name>
  </place>
</contact>

CSV Example

In a CSV delivery, some field names will change to reflect the nested structure. For example, name is changed to place.name.

                              id, first_name, last_name,           email, professional_title, infogroup_id,     place.name
63ca41bb84594b9fa007eafd7a8881de,      Jerry,  Williams, jerryw@acme.net,                   ,    421766665, Acme Dentistry
33e1fb992fc87c7f9bf88dd91fb99f28,      Sally,     Smith,                ,                DDS,    421766665, Acme Dentistry

In the CSV format, other nested object collections are still delivered in a separate file when a perspective is specified.

Incremental Update Type

Incremental subscriptions deliver changes to a scope of records. As records are updated, it's possible for them to enter or exit a subscription's scope. So, incremental deliveries contain a special field for each record: change_type. Its possible values are given below:

addition - The record is new to the record scope.
removal - The record is exiting the record scope.
update - The record is already in the record scope, and has a field change.

When a record exits a record scope, it will be delivered one final time. For instance, if an incremental subscription delivers in_business: yes places, and one of its places is marked in_business: no, that place will be delivered one final time as an change_type: removal.

To learn more about incremental subscriptions, read File Delivery API and Changes API.

Pipe Delimited Format

Deliveries using the Pipe Delimited format are nearly identical to CSVs, but use the pipe symbol (|) to separate values instead of commas. This format is useful for programs that do not support embedded commas. For example, compare the two formats below:

CSV

first_name,last_name,job_titles,place.name,place.company_description
Jerry,Williams,Dental Assistant,ACME Dentistry,Satisfaction|Safety|Smiles
Sally,Smith,"Dentist,Orthodontist",ACME Dentistry,Satisfaction|Safety|Smiles

Pipe Delimited

first_name|last_name|job_titles|place.name|place.company_description
Jerry|Williams|Dental Assistant|ACME Dentistry|Satisfaction/Safety/Smiles
Sally|Smith|Dentist, Orthodontist|ACME Dentistry|Satisfaction/Safety/Smiles

Notice in the above example, the double quotes (") around values containing commas are no longer necessary.

Any occurrence of pipe symbols (|) within values will be replaced with a forward slash (/).

Flat CSV Format

Deliveries using the Flat CSV format do not create separate files for Nested Object collections. Instead, the nested objects are "flattened" into the top-level files (e.g. Place).

Example

infogroup_id,name,street,city,state,contacts.01.first_name,contacts.01.last_name,contacts.01.email,contacts.02.first_name,contacts.02.last_name,contacts.02.email
421766665,ACME Dentistry,123 Enamel Way,Seattle,WA,Sally,Smith,,Jerry,Williams,jerry@acme.net

Each row in a delivery file includes up to 10 nested objects per collection. Any nested objects over this limit are not included in the delivery.