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 findstate: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