Getting Started
GET /v1/profilefuse/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 sample response:
- 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.
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: places.infogroup_id
, places.first_name
, and places.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:
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
A list of fields can be provided, and the sort order can be reversed:
Sorting by Geo Distance
A frequent use case is to sort by distance from a location. Use the special "geo" sort to request this:
Limit
The default number of records returned is 10. This can be adjusted with the limit
parameter:
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":
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.
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:
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 Example:
curl https://qa.api.data-axle.com/v1/profilefuse/search?include_labels=true
JSON Example:
{
"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 Example:
curl https://qa.api.data-axle.com/v1/profilefuse/search?include_ranges=true
JSON Example:
{
"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 persistent_id
:
Multiple IDs
The response is similar to search results:
Single ID
GET /v1/profilefuse/:id
If you want a single record by ID, you can request the attributes for the profilefuse by performing a simple request:
The response contains the single place:
The fields
parameter is supported with this request, to reduce the payload returned: