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/b2c_links/scan

A scan is created with a filter defined in a POST request. Optionally, set limit to stop the scan after that many records have been returned across all pages:

curl -XPOST https://api.data-axle.com/v1/b2c_links/scan -d '{
  "filter": {
    "relation": "equals",
    "attribute": "job_titles",
    "value": "Owner"
  }
}'

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/b2c_links/scan/:id

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

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

Response:

[
    {
      "workplace_id": "433179528",
      "first_name": "Joe",
      "last_name": "Smith"
      ...
    },
    {
      "workplace_id": "712584264",
      "first_name": "Jamie",
      "last_name": "Smith"
      ...
    }
  ...
]

Continue to use the same scroll_id to retrieve further results. When a scan has a limit, its final page may contain fewer than 200 records. Requests after the limit is reached return an empty array.

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:

Parameter	Use	Description
`filters`	Yes	Reduce potential results with the Filter DSL.
`limit`	No	Stop after returning this many records across all pages.
`perspective`	Yes	Pivot the top level object.

Scroll Parameters

Parameter	Use	Description
`fields`	No	Select the fields returned in the results.
`packages`	No	Select packages of fields returned in the results.
`include_labels`	No	Get the labels for encoded fields.

Filters

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

Limit

The limit parameter sets the maximum number of records returned across the entire scan. It must be a non-negative integer. When omitted, all matching records can be retrieved. The count in the creation response continues to report the total number of records matching the filter, even when a limit is set.

Perspective

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

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://api.data-axle.com/v1/b2c_links/scan/b0f142cc5765b8628162?fields=first_name,last_name'

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://api.data-axle.com/v1/b2c_links/scan/b0f142cc5765b8628162?packages=base_v1,emails_v2'

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://api.data-axle.com/v1/b2c_links/scan/b0f142cc5765b8628162?include_labels=true'

Read the Lookups API documentation for more information.