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:

• Search API
• Match API v1
• Match API v2
• Scan API
• Insights API

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/places/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:

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/places/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/places/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/places/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/places/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/places/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 records without a toll free number:

curl -XGET https://qa.api.data-axle.com/v1/places/search -d '{
  "filter": {
    "relation": "missing",
    "attribute": "toll_free_number"
  }
}'

Present

The present relation retrieves records with a filled value.

For example, return all records with a toll free number:

curl -XGET https://qa.api.data-axle.com/v1/places/search -d '{
  "filter": {
    "relation": "present",
    "attribute": "toll_free_number"
  }
}'

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/places/search -d '{
  "filter": {
    "relation": "range",
    "attribute": "estimated_opened_for_business",
    "value": {
      "start": "1985-01-01"
      "end": "1985-12-31",
      "relation": "contains"
    }
  }
}'

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/places/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/places/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/places/search -d '{
  "filter": {
    "relation": "geo_distance",
    "value": {
      "distance": "7km",
      "postal_codes": [
        "98117",
        "98103"
      ]
    }
  }
}'

Notes:

• The distance field is always required.
• Either coordinates or postal_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/places/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/places/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 have more than 9 employees:

curl -XGET https://qa.api.data-axle.com/v1/places/search -d '{
  "filter": {
    "connective": "and",
    "propositions": [
      {
        "geo": "distance",
        "lat": 47.60,
        "lon": -122.33,
        "distance": "1mi"
      },
      {
        "relation": "greater_than",
        "attribute": "location_employee_count",
        "value": 9
      }
    ]
  }
}'

Or

The following request searches for records where state is "AZ" or "NM":

curl -XGET https://qa.api.data-axle.com/v1/places/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 employee_size>10) OR (zip:10021 AND employee_size>20).

curl -XGET https://qa.api.data-axle.com/v1/places/search -d '{
  "filter": {
    "connective": "or",
    "propositions": [
      {
        "connective": "and",
        "propositions": [
          {
            "attribute": "zip",
            "relation": "equals",
            "value": "98117"
          },
          {
            "attribute": "location_employee_count",
            "relation": "greater_than",
            "value": "10"
          }
        ]
      },
      {
        "connective": "and",
        "propositions": [
          {
            "attribute": "zip",
            "relation": "equals",
            "value": "10021"
          },
          {
            "attribute": "location_employee_count",
            "relation": "greater_than",
            "value": "20"
          }
        ]
      }
    ]
  }
}'