Docs

Places People B2C Links

Learn more about our data, services, and APIs.

Scan API

< Prev Next >

Pull a list of records from the Data Axle Database

Getting started

Whereas Search API returns the top, most relevant places, Scan API specializes in returning all records that match a filter.

Use Scan API with a two step process:

  • Initialize a scan by defining a filter.
  • Scroll through results with a scroll_id.

Creating a Scan

POST /v1/places/scan

A scan is created with a filter defined in a POST request:

curl -XPOST https://qa.api.data-axle.com/v1/places/scan -d '{
  "filter": {
    "relation": "equals",
    "attribute": "cuisines",
    "value": "sushi"
  }
}'

The response returns the count of matching results, along with a scroll_id to retrieve results:

{
  "scroll_id": "b0f142cc5765b8628162",
  "count": 1231
}
Read the Filter DSL to learn about syntax and filtering options.

Scanning Results

GET /v1/places/scan/:id

After acquiring a scroll_id, retrieve results in pages of up to 200 records.

curl 'https://qa.api.data-axle.com/v1/places/scan/b0f142cc5765b8628162'

Response:

[
  {
    "id": "433179528",
    "name": "Sushi Roku",
    "city": "Indianapolis",
    "street": "6414 E 82nd St",
    "zip": "46250"
    ...
  },
  {
    "id": "712584264",
    "name": "Paradise Sushi & Grill",
    "city": "Santa Rosa",
    "street": "119 4th St",
    "zip": "95401"
    ...
  }
  ...
]

Continue to use the same scroll_id to retrieve further results.

Keep Alive Between Pages

If unused for over 60 seconds, the scroll_id expires. This means that each page must be requested in intervals less than one minute.

Parameters

Creation Time Parameters

A description of parameters when scroll is first created:

ParameterUseDescription
filtersYesReduce potential results with the Filter DSL.
perspectiveYesPivot the top level object.

Scroll Parameters

ParameterUseDescription
fieldsNoSelect the fields returned in the results.
packagesNoSelect packages of fields returned in the results.
include_labelsNoGet the labels for encoded fields.

Filters

The filter parameter reduces results to records matching a specified criteria, using the Filter DSL.

Perspective

The perspective pivots the top level record. Read more about perspectives in Delivery Schema.

{
  "perspective": "contacts",
}

Fields

By default, all information about a record is returned. The amount of data returned per result can be adjusted with the fields parameter. This can reduce bandwidth and improve performance.

curl 'https://qa.api.data-axle.com/v1/places/scan/b0f142cc5765b8628162?fields=name,website'

Packages

Select packages of fields by providing a package param_key to the packages parameter. By default, every field on a package is returned. The packages parameter is combined with the fields parameter to return only specified fields.

curl 'https://qa.api.data-axle.com/v1/places/scan/b0f142cc5765b8628162?packages=base_v1,contacts_v1'

Include Labels

The fields returned within 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/scan/b0f142cc5765b8628162?include_labels=true'

Read the Lookups API documentation for more information.

< Prev Next >