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 Infogroup 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

Browse the list of all fields with the Data Dictionary.

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 login 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

An example of a collection of data is the contacts list of a Place:

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:

contacts
happy_hours
images

The following perspectives are supported for people:

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: update_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 update_type: removal.

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