Query Examples
This page demonstrates practical examples of Deliberate API queries. Each example includes an explanation of what we're trying to accomplish, followed by an interactive playground where you can run the query and see real results.
Find a State by Name
One of the most common queries is looking up a geographic set by name. In this example, we're searching for the state of California. We use the tags filter to narrow results to sets tagged with us_state, then use the properties filter to match the exact name.
This pattern works for any named geographic set—states, counties, countries, or national parks. Try changing "California" to another state name in the playground below!
What's at This Location?
The spatial contains_point filter lets you discover what geographic sets contain a given latitude/longitude coordinate. This is perfect for reverse geocoding—finding out what country, state, county, or other boundaries contain a specific location.
In this example, we're querying the coordinates for Los Angeles, California (34.0522°N, 118.2437°W). The API will return all sets that contain this point, such as the United States, California, and Los Angeles County. Try changing the coordinates to any location you're interested in!
Find the Timezone for a Location
Combining tags with spatial queries enables powerful lookups. Here we're finding which timezone contains a specific location—in this case, New York City (40.7128°N, 74.0060°W).
By filtering for sets tagged with timezone and using the contains_point spatial filter, we can instantly determine the timezone for any coordinate. This is useful for applications that need to schedule events, display local times, or handle time-sensitive operations across different regions.
Find All National Parks in Utah
Relationships let you query geographic sets based on their spatial associations with other sets. In this example, we want to find all national parks that are geographically contained within the state of Utah.
The query works in two steps: First, we target sets tagged with us_national_park. Then we use a relationships filter with type SUBSET and direction outbound to find parks that are subsets of Utah. This returns famous parks like Zion, Arches, Bryce Canyon, and more.
Find States That Have National Parks
Relationships can work in both directions. In the previous example, we found national parks within a state. Now we're reversing the relationship—finding all states that contain at least one national park.
By using direction inbound instead of outbound, we're looking for states where national parks have an outbound SUBSET relationship to them. This efficiently finds all states with national parks without having to query each state individually.
Find States the Appalachian Trail Passes Through
The INTERSECTS relationship type is perfect for finding geographic sets that share some area with each other, even if one isn't completely contained within the other. In this example, we're finding all states that the Appalachian National Scenic Trail passes through.
The trail spans multiple states from Georgia to Maine, crossing state boundaries many times. Using INTERSECTS with direction any finds all states that share any geographic area with the trail, regardless of which direction the relationship was created. This returns all 14 states along the trail's route.