Search API

< Prev Next >

Find relevant listings in the database

Getting Started

GET /v1/b2c_links/search

There are two ways to execute a search request: with URL parameters and with a JSON body. Let's first look at an example of searching with URL parameters.

The following request searches for 'Jackson Smith':

curl https://api.data-axle.com/v1/b2c_links/search?query=Jackson+Smith

The sample response:

{
  "count": 48372,
  "documents": [
    {
      "name": "Jackson",
      "last_name": "Smith",
      "workplace": {
        "city": "Brooklyn",
        "street": "15511 Edwards St",
        "zip": "11201"
      }
      ...
    },
    {
      "first_name": "Elias",
      "last_name": "Smith",
      "workplace": {
        "city": "Jackson",
        "street": "19 Front Street",
        "zip": "39056"
      }
      ...
    }
    ...
  ]
}

The query parameter searches across core attributes.
By default, up to 10 records are returned. This can be changed with the limit parameter.
All available fields are included in the output. This can be changed with the fields parameter.

JSON Request

More powerful searches are performed by specifying a JSON body in the request. The request body supports additional parameters for fine-tuning search results not available with URL parameters.

The following search finds consumers named Smith in the state of California, returning only the first name, last name, and email address fields in the results:

curl -XGET https://api.data-axle.com/v1/b2c_links/search -d '{
  "fields": ["first_name", "last_name", "emails.address"],
  "query": "Smith",
  "filter": {
    "relation": "equals",
    "attribute": "workplace.state",
    "value": "CA"
  }
}'

Parameters

A description of all available parameters, and which are supported via URL parameters and/or a request body, is given below:

Parameter	Requires JSON Request?	Description
`query`	No	A query string that defaults to matching to name, address, and phone fields.
`scoring`	Yes	Define what fields are considered with the `query` parameter.
`sort`	Yes	Change order of results by field or geo distance.
`limit`	No	Change the max number of results returned.
`offset`	No	Skip over a number of initial results, usually for pagination.
`perspective`	Yes	Pivot the top level object.
`packages`	No	Select packages of fields returned in the results.
`fields`	No	Select the fields returned in the results.
`include_labels`	No	Get the labels for encoded fields.
`include_ranges`	No	Get the range for integer fields with frequency ranges.
`filters`	Yes	Reduce potential results with the Filter DSL.
`ids`	No	Get details of records based on a list of known IDs.

Query

The query parameter is the common way for users to find a record with a free-form search.

By default, the following fields are searched: workplace_id, first_name, and last_name.

If each of the terms in the query match any of the fields, the record is returned. Results are scored based on how well they match, and the greatest scores are returned first:

By default, core name and phone fields have a greater weight than other fields. To change this behavior, use the scoring parameter.
Less common terms have a larger weight.
Lookup fields such as state are searched by label. For example, "Washington" will find state:WA.

Scoring

To search on a subset of the default fields or to alter their boost weights you can pass in the scoring parameter:

{
  "query": "Macy California",
  "scoring": {
    "last_name": "2",
    "first_name": "1",
    "workplace_id": "1"
  }
}

When the scoring parameter is used, the query will only search the fields listed. The numeric values represent the boost score. In this example, the field with a value of "2" will be weighted twice as much as the fields weighted a "1".

Sort

By default, sorting is based on how well the query matches. Use the sort parameter to change this behavior.

Sorting by Field

{
  "query": "John Smith",
  "sort": [
    "workplace.verified_on"
  ]
}

A list of fields can be provided, and the sort order can be reversed:

{
  "query": "John Smith",
  "sort": [
    {"workplace.verified_on": "desc"},
    "workplace.name"
  ]
}

Sorting by Geo Distance

A frequent use case is to sort by distance from a location. Use the special "geo" sort to request this:

{
  "query": "john smith",
  "sort": [
    {"geo": {"lat": 47.3, "lon": -122.7}}
  ]
}

Limit

The default number of records returned is 10. This can be adjusted with the limit parameter:

curl 'https://api.data-axle.com/v1/b2c_links/search?query=john+smith&limit=25'

The maximum limit is 400. To retrieve all possible results, use the Scan API.

Offset

Additional pages of results can be retrieved by requesting the search with an offset. To get the third page of results for "Pizza":

curl 'https://api.data-axle.com/v1/b2c_links/search?query=john+smith&limit=10&offset=20'

The maximum offset is 4,000. To retrieve all possible results, use the Scan API.

Perspective

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

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/search?query=john+smith&packages=base_v1,emails_v2'

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. The following returns only the business name and website:

curl 'https://api.data-axle.com/v1/b2c_links/search?query=john+smith&fields=first_name,last_name'

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/search?include_labels=true

Read the Lookups API documentation for more information.

Include Ranges

Some integer fields have default ranges for use with the Insights API. To retrieve the range that a value falls within in addition to the value, add the include_ranges=true option.

curl https://api.data-axle.com/v1/b2c_links/search?include_ranges=true

Filters

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

IDs Query

Records can be requested by ID with the ids parameter. This is the same ID that is often referenced as the b2c_link_id:

Multiple IDs

curl https://api.data-axle.com/v1/b2c_links/search?ids=8f850f0730015fdb66e709bd74dbdcef,4975b795f52000b746c717a9e7cc2ccf

The response is similar to search results:

{
  "count": 2,
  "documents": [
    {
      "b2c_link_id": "8f850f0730015fdb66e709bd74dbdcef",
      "name": "Jackson",
      "last_name": "Smith",
      "workplace": {
        "city": "Brooklyn",
        "street": "15511 Edwards St",
        "zip": "11201",
        ...
      },
      ...
    },
    {
      "b2c_link_id": "4975b795f52000b746c717a9e7cc2ccf",
      "first_name": "Elias",
      "last_name": "Smith",
      "workplace": {
         "city": "Jackson",
         "street": "19 Front Street",
         "zip": "39056",
         ...
       },
      ...
    }
  ]
}

Single ID

GET /v1/b2c_links/:id

If you want a single record by ID, you can request the attributes for the b2c_link by performing a simple request:

curl https://api.data-axle.com/v1/b2c_links/8f850fa730015fdb66e709bd74cbdcea

The response contains the single place:

 {
   "workplace_id": "859302832",
   "name": "Jackson",
   "last_name": "Smith",
   "workplace": {
     "city": "Brooklyn",
     "street": "15511 Edwards St",
     "zip": "11201"
   }
 }

The fields parameter is supported with this request, to reduce the payload returned:

curl https://api.data-axle.com/v1/b2c_links/8f850fa730015fdb66e709bd74cbdcea?fields=workplace.name,first_name