By: Ian Villeda
What can you do with a point? With reverse geocoding, we can find out that -77.036547, 38.897675 is 1600 Pennsylvania Ave NW, Washington DC. But what if we want to know more about this {longitude},{latitude}, and build experiences based on the additional context — say, what type of place it is, the five closest restaurants within a mile, or the elevation at that point?
Do all of that and more with our Tilequery API, just released from preview. Now you can look for features within vector tilesets, including both Mapbox data and your custom data. It allows you to query within a radius of a point and returns features with their properties and distance from the given point. Query custom data, multiple composited layers, or perform complex point-in-polygon queries — all without needing to render a map on your mobile phone or in a browser.
Building with Tilequery API
Want to create different experiences in-app when your users are at restaurants vs. parks vs. theaters? Receive notifications when your trucks are approaching your distribution centers? See all of the geographic boundaries in which a customer is situated? Share the current elevation profile of your hikers at their location or for their upcoming route? Here are the main use cases the Tilequery API enables :
- Point-in-polygon queries: Receive all of the administrative boundaries that a specific point falls within, such as city, county, state, country, legislative district, etc. This works great with Enterprise Boundaries and helps answer questions like Which region or country is my user or this point from my dataset in?
- Elevation queries: Receive the elevation at a point or along a line by querying the Mapbox Vector Terrain tileset. Helps answer questions like: What’s the elevation along my run?
- Geofencing: Determine how far away a point is from a custom polygon. Helps answer questions like: Are my fleet of taxis within certain congestion zones, if not how far away are they?
- Landuse and place category queries: Know whether a point is in a shopping mall, at the beach, in the park, at a restaurant, etc. Helps answer questions like: Are my users close to a coffee shop? Then, you’re able to drive in-app actions based on the result, such as notifying users of a special offer for coffee.
- Custom geocoding supplement: Upload your custom POI data to Mapbox, know which features from your custom data are within a certain radius from a given point. Helps answer questions like: How many/which of my POIs are within a 5-mile radius?
KEEP, one of the top fitness apps in China with over 100,000,000 daily users, uses the Tilequery API to provide users a complete picture of their outdoor workout. With it, they’re able to provide users with elevation data for a better user experience.
“KEEP provides exercise tracking outdoors, where altitude information plays a very important role. The traditional methods of obtaining altitude from GPS are not accurate nor stable. To optimize the user experience and display more accurate altitude readings, KEEP uses the baseline altitude as reference and changes in barometer readings for tracking over time. The baseline altitude is the altitude information of the user at the beginning of the exercise, which is obtained using Mapbox’s Tilequery API.” — Mengyang Zhu, Outdoor Technology Engineer, KEEP
GovTrack uses Tilequery to help Americans figure out who represents them in Congress and what Congressional district they live in. GovTrack uses our Geocoding API to turn users’ addresses into long/lat coordinates and the Tilequery API then uses those long/lat coordinates to look up congressional data from GovTrack’s custom tilesets. This allows them to present state and district information to their users.
“The Tilequery API has been crucial for making this work. We can’t do the state and district lookup client-side because there’s too much data — — we use the highest accuracy congressional district boundaries, provided by the US Census Bureau, to ensure we provide our users with the most accurate information. So without the Tilequery API we would have had to host our own spatial database, which we used to do until we discovered the Tilequery API. Using Mapbox instead of rolling our own database has been much better for us.” — Joshua Tauberer, Founder & President of GovTrack
Parameters available to customize a query
A request to the Tilequery API only requires two parameters: the ID of the tileset(s) you want to query, and the desired geographic coordinates. However, you can further customize your call with these five optional parameters:
- radius: Specify the size of a radius to query within. If you set this, the returned features will be within the radius around the queried location, rather than right at the queried location.
- limit: Indicate the number of features you want to be returned. If you don’t explicitly set this parameter, the query defaults to returning five features.
- geometry: Request a specific geometry type to be returned. This allows you to limit the response to return features of one specific kind of geometry (point, polygon, or linestring) instead of returning features of all three types.
- layers: Specify a layer or layers to query within. This would allow you to, for example, search for only features only within the building or poi_layer layers.
- dedupe: Indicate whether you want the returned features to be automatically deduplicated or not.
Get started
Our Tilequery API is now included as part of our pay-as-you-go pricing plan, meaning you get 50,000 free API calls every month and only pay for what you use beyond that. Ready to take it for a spin? Start building with Tilequery and get in touch with our team if you have questions.
Unlock context-rich experiences with the new Tilequery API was originally published in Points of interest on Medium, where people are continuing the conversation by highlighting and responding to this story.