Filter DSL
Narrow results with specific criteria
The Filter DSL (Domain Specific Language) is a JSON structure consisting of relations and connective nodes.
Supported APIs
The following APIs support a filter
parameter:
Relations
Relations allow you to specify a comparison operation on any attribute in the Data Dictionary. For example, to filter by the state of Maine:
curl -XGET https://qa.api.data-axle.com/v1/people/search -d '{
"filter": {
"relation": "equals",
"attribute": "state",
"value": "ME"
}
}'
The syntax for a relation filter:
{
"relation": <relation>,
"attribute": <attribute_name>,
"value": <value_string>,
"negated": <true|false>
}
The relation
defines the type of comparison operation. Possible values for the relation
depend on the field type:
Relation | Description | Supported Types |
equals | Exactly match a value. | string , numeric , date , boolean |
matches | Fuzzy match a value. | string |
in | Match one of the values in a list. | string , array , numeric |
between | The number or date falls between the specified bounds. | numeric , date |
greater_than | The number is greater or date is after. | numeric , date |
less_than | The number is less or date is before. | numeric , date |
missing | The attribute is missing. | - |
present | The attribute is filled. | - |
range | The range overlaps, contains, or is within the specified bounds. | numeric_range , date_range |
Equals
The equal
relation filters results by exact value. The following example returns places in a specific postal code:
curl -XGET https://qa.api.data-axle.com/v1/people/search -d '{
"filter": {
"relation": "equals",
"attribute": "postal_code",
"value": "98117"
}
}'
Matches
The matches
relation filters results by value. The following example returns places that have cafe in their names:
curl -XGET https://qa.api.data-axle.com/v1/people/search -d '{
"filter": {
"relation": "matches",
"attribute": "name",
"value": "cafe"
}
}'
In
The in
relation filters results by multiple possible values from a list. The following example returns places in Washington, Oregon, Idaho, and California:
curl -XGET https://qa.api.data-axle.com/v1/people/search -d '{
"filter": {
"relation": "in",
"attribute": "state",
"value": ["WA", "OR", "ID", "CA"]
}
}'
Between
The between
relation filters results based on a date or number between two values. The following example returns places with 5-10 employees:
curl -XGET https://qa.api.data-axle.com/v1/people/search -d '{
"filter": {
"relation": "between",
"attribute": "location_employee_count",
"value": [5, 10],
}
}'
For querying a range field, use range instead.
Inequalities
The greater_than
and less_than
relations filter results based on a date or number. The following example returns places with more than 5 employees:
curl -XGET https://qa.api.data-axle.com/v1/people/search -d '{
"filter": {
"relation": "greater_than",
"attribute": "location_employee_count",
"value": 5,
}
}'
Missing
The missing
relation retrieves records with a missing value.
For example, return all people that are missing credit card information:
curl -XGET https://qa.api.data-axle.com/v1/people/search -d '{
"filter": {
"relation": "missing",
"attribute": "credit_card_types"
}
}'
Present
The present
relation retrieves records with a filled value.
For example, return all people that are known to have a credit card:
curl -XGET https://qa.api.data-axle.com/v1/people/search -d '{
"filter": {
"relation": "present",
"attribute": "credit_card_types"
}
}'
Range
The range
relation filters results based on a date range or number range between two values. The following example returns places that opened for business on a date range containing the queried range.
curl -XGET https://qa.api.data-axle.com/v1/people/search -d '{
"filter": {
"relation": "range",
"attribute": "estimated_opened_for_business",
"value": {
"start": "1985-01-01"
"end": "1985-12-31",
"relation": "contains"
}
}
}'
Range | Description |
intersects | Matches documents with a range field value that intersects the query’s range, e.g. the query "1985-01-01" - "1985-01-31" intersects with the document "1985-01-15" - "1985-02-15". |
contains | Matches documents with a range field value that entirely contains the query’s range, e.g. the query "1985-01-01" - "1985-01-31" is contained by the document value "1985-01-01" - "1985-12-31". |
within | Matches documents with a range field value entirely within the query’s range, the document "1985-01-01" - "1985-01-31" is within the query "1985-01-01" - "1985-12-31". |
Negating
The negated
parameter is optional and negates the relation. The following filters by all states except NY:
curl -XGET https://qa.api.data-axle.com/v1/people/search -d '{
"filter": {
"relation": "equals",
"attribute": "state",
"value": "NY",
"negated": true
}
}'
Geo Filters
Geo filters limit results by distance or by a bounding shape.
Distance
Filter by distance from geocoordinates:
curl -XGET https://qa.api.data-axle.com/v1/people/search -d '{
"filter": {
"relation": "geo_distance",
"value": {
"distance": "7km",
"lat": 47.60,
"lon": -122.33
}
}
}'
Filter by distance from postal_codes:
curl -XGET https://qa.api.data-axle.com/v1/people/search -d '{
"filter": {
"relation": "geo_distance",
"value": {
"distance": "7km",
"postal_codes": [
"98117",
"98103"
]
}
}
}'
Notes:
- The
distance
field is always required. - Either
coordinates
orpostal_codes
is required. - Denote the units for distance with
km
,m
,mi
&ft
. If no unit is specified,m
are used.
Bounding Box
Find records within a bounding box:
curl -XGET https://qa.api.data-axle.com/v1/people/search -d '{
"filter": {
"relation": "geo_box",
"value": {
"left": -124.33,
"right": -123.84,
"top": 47.15,
"bottom": 46.37
}
}
}'
Polygon
Find records within an arbitrary polygon, using up to 500 points:
curl -XGET https://qa.api.data-axle.com/v1/people/search -d '{
"filter": {
"relation": "geo_polygon",
"value": [
{"lat": 47.15, "lon": -124.33},
{"lat": 46.63, "lon": -124.42},
{"lat": 46.15, "lon": -123.84}
]
}
}'
Connectives
Connectives allow combinations of multiple filters using the boolean AND and OR operators.
And
The following request searches for records that are within a mile away and whose house has more than one bedroom:
curl -XGET https://qa.api.data-axle.com/v1/people/search -d '{
"filter": {
"connective": "and",
"propositions": [
{
"geo": "distance",
"lat": 47.60,
"lon": -122.33,
"distance": "1mi"
},
{
"relation": "greater_than",
"attribute": "mortgage.number_of_bedrooms",
"value": "1"
}
]
}
}'
Or
The following request searches for records where state is "AZ" or "NM":
curl -XGET https://qa.api.data-axle.com/v1/people/search -d '{
"filter": {
"connective": "or",
"propositions": [
{
"attribute": "state",
"relation": "equals",
"value": "AZ"
},
{
"attribute": "state",
"relation": "equals",
"value": "NM"
}
]
}
}'
Connectives can include further connectives, allowing for nested queries such as
(zip:98117 AND number_of_bedrooms>4) OR (zip:10021 AND number_of_bedrooms>1)
.
curl -XGET https://qa.api.data-axle.com/v1/people/search -d '{
"filter": {
"connective": "or",
"propositions": [
{
"connective": "and",
"propositions": [
{
"attribute": "zip",
"relation": "equals",
"value": "98117"
},
{
"attribute": "mortgage.number_of_bedrooms",
"relation": "greater_than",
"value": "4"
}
]
},
{
"connective": "and",
"propositions": [
{
"attribute": "zip",
"relation": "equals",
"value": "10021"
},
{
"attribute": "mortgage.number_of_bedrooms",
"relation": "greater_than",
"value": "1"
}
]
}
]
}
}'