Docs

Places People B2C Links

Learn more about our data, services, and APIs.

Changes API

< Prev Next >

Subscribe to changes in real-time

Getting Changes

GET /v1/places/changes

To get recent changes, start with a simple query:

curl https://qa.api.data-axle.com/v1/places/changes

The response contains a list of changes. Each change describes the current record and the previous values for fields that changed:

{
  "next_token": "13835315192676945401741312",
  "changes": [
    {
      "infogroup_id": "985166431",
      "type": "update",
      "current": {
        "name": "New York Pizza",
        "phone": "(206) 567-4321"
      },
      "previous": {
        "name": "Brooklyn Pizza"
      },
      "timestamp": "2015-12-20T05:45:15Z"
    },
    ...
  ]
}

Specifying a Subscription

If you have multiple subscriptions, you can get changes on a specific subscription by adding subscription_id to your query string:

curl https://qa.api.data-axle.com/v1/places/changes?subscription_id=your-subscription-id

Scrolling Through Changes

The first request to the Changes API returns the earliest changes. To continue reading a chronological list of changes, grab the next_token value and add it to your next query using ?since=[next_token].

curl https://qa.api.data-axle.com/v1/places/changes?since=13835315192676945401741312

This process is repeated until there are no further changes. When all changes are read, the last request returns the same next_token passed in as a parameter, along with an empty set of changes:

{
  "next_token": "13835315192676945401741312",
  "changes": []
}

Using a Date to Read Changes

You may also want to jump into the middle of the change feed based on a time. This is possible by using a UTC date with the since parameter:

curl https://qa.api.data-axle.com/v1/places/changes?since=2014-12-24

Additions, Removals and Updates

Most changes are updates to existing records. However, some changes are for completely new records and others are for the removal of records.

The type of change is described by the type field, which can be one of three values:

  • "addition" - The record is new to the feed.
  • "removal" - The record is exiting the feed.
  • "update" - The record is already in the feed and has a field change.

Additions

Additions happen for one of two reasons:

  • A new record is added to the Data Axle database.
  • An existing record is modified to match the changes being subscribed to. For example, if your account only receives records in the state of California, and an existing record has a state change from Arizona to California, it will appear as an "addition":
{
  "infogroup_id": "940302867",
  "type": "addition",
  "current": {
    "name": "California Pizza",
    "phone": "(425) 555-4321",
    "state": "CA"
  },
  "previous": {
    "state": "AZ"
  },
  "timestamp": "2015-12-23T12:27:19Z"
}

Removals

Removals happen for one of two reasons:

  • An existing record is invalidated in the Data Axle database. Reasons for this can include businesses closure and duplicate record detection.
  • An existing record is modified to no longer match the changes being subscribed to. For example, if your account only receives records in the state of California, and an existing record has a state change from California to Arizona, it will appear as a "removal":
{
  "infogroup_id": "940302724",
  "type": "removal",
  "current": {
    "name": "Arizona BBQ",
    "state": "AZ"
  },
  "previous": {
    "state": "CA"
  },
  "timestamp": "2015-01-17T08:41:34Z"
}

Attribute Updates, Fills and Removals

The current section of the record shows the record after the change was applied, including all attributes. The previous section shows an abbreviated record which highlights changes made to the record. By comparing the values in the current and previous sections, you can determine which attributes changed and how they were changed.

An attribute that has changed from one value to another is shown as follows:

{
  "infogroup_id": "985166431",
  "type": "update",
  "current": {
    "name": "New York Pizza",
    "phone": "(206) 567-4321"
  },
  "previous": {
    "name": "Brooklyn Pizza"
  }
}

This shows that the name was changed from "Brooklyn Pizza" to "New York Pizza".

A null JSON value in the previous section indicates that a field's value was added where a value didn't exist before. The following example would show that a suite number was added to a record where there was previously no entry for the suite number:

{
  "infogroup_id": "985166431",
  "type": "update",
  "current": {
    "name": "New York Pizza",
    "city": "New York",
    "state": "NY",
    "suite": "120",
    "phone": "(206) 567-4321"
  },
  "previous": {
    "suite": null
  }
}

Similarly, a null value in the current section represents the removal of a value. The following example indicates that the suite number was removed from the record:

{
  "infogroup_id": "985166431",
  "type": "update",
  "current": {
    "name": "New York Pizza",
    "city": "New York",
    "state": "NY",
    "suite": null,
    "phone": "(206) 567-4321"
  },
  "previous": {
    "suite": "100"
  }
}

Inline Labels

Change records frequently contain encoded values that reference lookup data. To retrieve the labels for lookups, add the include_labels=true option:

curl https://qa.api.data-axle.com/v1/places/changes?include_labels=true

Read the Lookups API documentation for more information.

< Prev Next >