Deliberate API
Developer Portal

Query Reference

This page documents the query language used to filter and retrieve sets from the Deliberate API.

Request Structure

Every query follows this structure:

json
{
  "where": {
    // Filter conditions
  },
  "limit": 100,    // Optional: 1-1000, default 100
  "offset": 0      // Optional: skip N results, default 0
}

Tag Filters

Filter sets by their associated tags.

contains

Set must have this specific tag.

json
{
  "tags": {"contains": "us_state"}
}

contains_all

Set must have ALL specified tags (AND logic).

json
{
  "tags": {"contains_all": ["container_terminal", "inland_port"]}
}

contains_any

Set must have AT LEAST ONE of the specified tags (OR logic).

json
{
  "tags": {"contains_any": ["sea_port", "inland_port"]}
}

not_contains

Set must NOT have this tag.

json
{
  "tags": {"not_contains": "container_terminal"}
}

Property Filters

Filter sets by property values. Currently supports equality checks only.

eq (equals)

Property must equal the specified value. Works with strings, numbers, booleans, and null.

json
{
  "properties": {
    "name": {"eq": "California"}
  }
}

Multiple Properties

All property filters are combined with AND.

json
{
  "properties": {
    "state": {"eq": "CA"},
    "status": {"eq": "active"}
  }
}

Spatial Filters

Query sets by geographic location.

contains_point

Find sets that contain a specific lat/lng point.

json
{
  "spatial": {
    "contains_point": {
      "lat": 34.0522,
      "lng": -118.2437
    }
  }
}

Constraints: lat must be -90 to 90, lng must be -180 to 180

Relationship Filters

Query sets based on their relationships with other sets.

Structure

json
{
  "relationships": {
    "type": "SUBSET",
    "direction": "outbound",
    "to": {
      // Any valid filter conditions
    }
  }
}

Relationship Types

  • SUBSET - Set A is completely contained within Set B
  • INTERSECTS - Set A shares some area with Set B

Relationship Directions

  • outbound - From current set to target (A → B) (default)
  • inbound - From target to current set (B → A)
  • any - Either direction

Example

Find all counties in California:

json
{
  "tags": {"contains": "us_county"},
  "relationships": {
    "type": "SUBSET",
    "direction": "outbound",
    "to": {
      "tags": {"contains": "us_state"},
      "properties": {"name": {"eq": "California"}}
    }
  }
}

Logical Operators

Combine filters with boolean logic.

Implicit AND

All filters at the same level are ANDed together by default. No explicit and operator needed.

and

Explicitly combine conditions with AND (rarely needed).

json
{
  "and": [
    {"tags": {"contains": "terminal"}},
    {"properties": {"status": {"eq": "active"}}}
  ]
}

or

Match if ANY condition is true.

json
{
  "or": [
    {"tags": {"contains": "sea_port"}},
    {"tags": {"contains": "inland_port"}},
    {"tags": {"contains": "dry_port"}}
  ]
}

not

Negate a condition.

json
{
  "not": {
    "properties": {"closed": {"eq": true}}
  }
}

Response Format

All queries return this structure:

json
{
  "data": [
    {
      "uuid": "set-uuid",
      "tags": [
        {
          "uuid": "tag-uuid",
          "name": "tag_name"
        }
      ],
      "properties": {
        // Arbitrary key-value pairs
      }
    }
  ],
  "metadata": {
    "total_count": 42,
    "execution_time_ms": 123.45,
    "query_complexity": 8
  },
  "limit": 100,
  "offset": 0
}

Pagination

Use limit and offset for pagination:

json
{
  "where": {"tags": {"contains": "us_county"}},
  "limit": 50,
  "offset": 100
}

Constraints: limit: 1-1000 (default: 100), offset: ≥0 (default: 0)

Available Data

The database comes pre-loaded with geographic data:

TypeCountTagsProperties
US States50us_statename, abbreviation, capital, statehood, gnis_feature_id
US Counties3,214us_countyname, geoid, fips_code, gnis_feature_id
World Countries~250countryname, iso_a2, continent
National Parks~400+national_park, npsname, unit_code, unit_type, gnis_feature_id
PortsVarioussea_port, inland_portname, location info
TerminalsVariousocean_terminal, rail_terminal, etc.name, location info, operator, firms_code