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:
where- Filter conditions (required)limit- Number of results (1-1000, default: 100)offset- Skip N results for pagination (default: 0)
Tag Filters
Filter sets by their associated tags.
contains
Set must have this specific tag.
contains_all
Set must have ALL specified tags (AND logic).
contains_any
Set must have AT LEAST ONE of the specified tags (OR logic).
not_contains
Set must NOT have this tag.
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.
Multiple Properties
All property filters are combined with AND.
Spatial Filters
Query sets by geographic location.
contains_point
Find sets that contain a specific lat/lng point.
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
The to field accepts any valid filter conditions.
Relationship Types
SUBSET- Set A is completely contained within Set BINTERSECTS- 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:
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).
or
Match if ANY condition is true.
not
Negate a condition.
Response Format
All queries return this structure:
The properties object contains arbitrary key-value pairs specific to each set.
Pagination
Use limit and offset for pagination:
Constraints: limit: 1-1000 (default: 100), offset: ≥0 (default: 0)
Available Data
The database comes pre-loaded with geographic data:
| Type | Count | Tags | Properties |
|---|---|---|---|
| US States | 50 | us_state | name, abbreviation, capital, statehood, gnis_feature_id |
| US Counties | 3,214 | us_county | name, geoid, fips_code, gnis_feature_id |
| World Countries | ~250 | country | name, iso_a2, continent |
| National Parks | ~400+ | national_park, nps | name, unit_code, unit_type, gnis_feature_id |
| Ports | Various | sea_port, inland_port | name, location info |
| Terminals | Various | ocean_terminal, rail_terminal, etc. | name, location info, operator, firms_code |