Use the File Delivery API to detect new deliveries and download a delivery's files. It supports Incremental, Match, and Snapshot file delivery types.

Retrieve Deliveries

GET /v1/places/deliveries
GET /v1/places/deliveries/incrementals
GET /v1/places/deliveries/matches
GET /v1/places/deliveries/snapshots

GET /v1/subscriptions/:subscription_id/deliveries
GET /v1/subscriptions/:subscription_id/deliveries/snapshots
GET /v1/subscriptions/:subscription_id/deliveries/incrementals

These APIs return deliveries, with the newest deliveries appearing first in the list. Results are limited to 30 deliveries.

The /subscriptions prefix filters deliveries to only those associated with a given subscription_id. Also, the additional /incrementals, /matches, and /snapshots paths filter deliveries to that specialized type.

Response Examples

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

{
  "deliveries": [
    {
      "id": "324cb9fb9ab53d97",
      "name": "2017 US New Businesses: Oct 01 Incremental",
      "type": "incremental",
      "url": "https://api.data-axle.com/v1/deliveries/324cb9fb9ab53d97",
      "frequency": "daily",
      "range_start_time": "2017-10-01T00:00:00Z",
      "range_end_time": "2017-10-02T00:00:00Z",
      "delivery_time": "2017-10-02T03:36:37Z",
    },
    {
      "id": "3d81b2882acbc820",
      "name": "September 2017 Snapshot",
      "type": "snapshot",
      "delivery_time": "2017-09-01T02:24:38Z",
      "url": "https://api.data-axle.com/v1/deliveries/3d81b2882acbc820",
    },
    {
      "id": "f66717a2a320dffc",
      "name": "Hotels Near Seattle",
      "type": "match",
      "delivery_time": "2017-08-01T08:26:53Z",
      "url": "https://api.data-axle.com/v1/deliveries/f66717a2a320dffc",
    }
  ]
}

curl https://api.data-axle.com/v1/subscriptions/5356231f-84f5-8db7-877a39ef014b/deliveries

{
  "deliveries": [
    {
      "id": "3d81b2882acbc820",
      "name": "September 2017 Snapshot",
      "type": "snapshot",
      "delivery_time": "2017-09-01T02:24:38Z",
      "url": "https://api.data-axle.com/v1/deliveries/3d81b2882acbc820",
    }
  ]
}

Delivery Fields

A description of each field that may be returned for a delivery is given below:

Parameters

A description of all available parameters is given below:

Discover New Deliveries

Use the after parameter to retrieve deliveries later than a specified Delivery ID.

In the previous example, a delivery with ID 3d81b2882acbc820 was downloaded. Use this ID to discover newer deliveries.

curl https://api.data-axle.com/v1/places/deliveries?after=3d81b2882acbc820

curl https://api.data-axle.com/v1/subscriptions/5356231f-84f5-8db7-877a39ef014b/deliveries?after=3d81b2882acbc820

The API returns deliveries produced after delivery with ID 3d81b2882acbc820. If there are no newer deliveries, the response contains an empty deliveries array.

Download Delivery Files

GET /v1/places/deliveries?id=delivery_id

Specify a Delivery ID to access the file details for that delivery:

curl https://api.data-axle.com/v1/deliveries/3d81b2882acbc820

The files section of the response contains a URL to download each file. Deliveries with more than one million records are split into multiple files.

Tips for file downloads

• Store the Delivery ID to track successful downloads. This makes it easier to download subsequent snapshot deliveries. See Discover New Deliveries above.
• CSV deliveries provide nested objects in separate files. Determine the type of objects in the file with the model field.

Response Example

{
  "id": "324cb9fb9ab53d97",
  "name": "October 2017 Snapshot",
  "type": "snapshot",
  "delivery_time": "2017-10-02T03:36:37Z",
  "format": "xml",
  "subscription": {
    "id": "a1bc596a-8429-c1d5-b550-6c5d58f4f493",
    "name": "Verified US Businesses",
    "contract": "My Contract"
  },
  "files": [
    {
      "filename": "Verified_US_Businesses-00000_place.xml.gz",
      "url": "https://axle-deliveries.s3.amazonaws.com/deliveries/324cb9fb9ab53d97/output/Verified_US_Businesses-00000_place.xml.gz?SIGNATURE",
      "size": 421619919,
      "model": "place",
      "records": 941437,
      "md5": "3f8b293fcae36b9d5173d7cc181cf4a8"
    },
    ...
  ]
}

Delivery Fields

A description of each field that may be returned for a delivery is given below:

File Fields

Each object in files describes details about a single file within a delivery.