Getting Started

GET /v1/places/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 'Brooklyn Pizza':

curl https://qa.api.data-axle.com/v1/places/search?query=Brooklyn+Pizza

The sample response:

{
  "count": 143426,
  "documents": [
    {
      "id": "830123091",
      "name": "Brooklyn Pizza",
      "city": "Huntington Beach",
      "street": "15511 Edwards St",
      "zip": "92648"
      ...
    },
    {
      "id": "712584264",
      "name": "Grimaldi's Pizza",
      "city": "Brooklyn",
      "street": "Front Street",
      "zip": "11201"
      ...
    }
    ...
  ]
}

• 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 Pizza places filtered to the state of California, returning only the name and website fields in the results:

curl -XGET https://qa.api.data-axle.com/v1/places/search -d '{
  "fields": ["name", "website"],
  "query": "Pizza",
  "filter": {
    "relation": "equals",
    "attribute": "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:

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: infogroup_id, name, phone, street, city, state, zip, website, sic_code_ids, cuisines, primary_contact.first_name, primary_contact.last_name, and primary_contact.professional_title.

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": {
    "name": "2",
    "street": "1",
    "state": "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": "pizza",
  "sort": [
    "location_sales_volume"
  ]
}

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

{
  "query": "pizza",
  "sort": [
    {"location_sales_volume": "desc"},
    "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": "pizza",
  "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://qa.api.data-axle.com/v1/places/search?query=Pizza&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://qa.api.data-axle.com/v1/places/search?query=Pizza&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://qa.api.data-axle.com/v1/places/search?query=Pizza&packages=base_v1,contacts_v1'

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://qa.api.data-axle.com/v1/places/search?query=Pizza&fields=name,website'

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/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://qa.api.data-axle.com/v1/places/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 infogroup_id:

Multiple IDs

curl https://qa.api.data-axle.com/v1/places/search?ids=386897342,412307825

The response is similar to search results:

{
  "count": 2,
  "documents": [
    {
      "id": "386897342",
      "name": "Apple Computer",
      "street": "1 Infinite Loop",
      "city": "San Jose",
      "state": "CA",
      "phone": "(408) 974-0159",
      ...
    },
    {
      "id": "412307825",
      "name": "Top Dog",
      "street": "1221 Covina CT",
      "city": "Allen",
      "state": "TX",
      "phone": "(972) 359-0507",
      ...
    }
  ]
}

Single ID

GET /v1/places/:id

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

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

The response contains the single place:

{
  "id": "859302832",
  "name": "Top Dog",
  "phone": "(510) 555-1212",
  "street": "2160 Center Street",
  "city": "Berkeley",
  "state": "CA"
}

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

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