This documentation covers a service that is currently in public beta. While we make a reasonable effort to ensure that things stay online, our beta services are not subject to the same availability guarantees of our other services. Additionally, beta services may not have the same global redundancy as our other services, so latency may be higher.
You will not be charged for beta access. If you continue using the service once it goes live, you will be charged as usual per the terms of our public pricing or your enterprise agreement.
Please send any feedback and issue reports to email@example.com.
Geocoding and Search¶
The Stadia Maps geocoding and search APIs help you convert between places and geographic coordinates. Places include points of interest (ex: Times Square), businesses, street addresses, postal codes, and more (see our list of layers). We provide a number of APIs that help you convert between places and coordinates (latitude and longitude) in both directions.
- Search helps you find information about places including geographic coordinates (aka forward geocoding), website, postal code, and more.
- Structured search works similarly to search, but instead of a single string like Search, it accepts structured data such as the street address and postal code as separate fields.
- Reverse search (also known as reverse geocoding or address geocoding) helps you find places nearest to some geographic coordinates.
- Autocomplete enables interactive search-as-you-type user experiences, suggesting places as you type, along with information that will help your users find the correct place quickly.
- Place lookup retrieves details of a place given its GID. Place GIDs are returned as components of all results (for example, an address result may have GIDs for the address itself, the local administrative area, the region, etc.).
Before diving into the technical documentation for each endpoint, we recommend reading this section first. This will help you and your users get the most relevant results.
Use the Correct Endpoint¶
If you have geographic coordinates and want to find out what's nearby, then the choice is easy! Use the reverse endpoint.
Interactive Search Interfaces or Partial Input¶
If you are creating an interactive UI where users see results as they type, use autocomplete for most queries. The notable exception to this rule is that when the user presses the enter/return key, or clicks on a search button after typing, you should probably use search.
If your data is already broken up into logical address chunks like postal code, city, and street address, the structured search endpoint is usually the best choice.
Complete Input as a String¶
If you are dealing with reasonably complete input (ex: from a database or input after the user presses enter), use the search endpoint. This is especially important for address data, as autocomplete does not interpolate missing house numbers along a street.
Specify the Layers you Need¶
All of our data is broken into layers, which separate data of different types. Examples of layers are
venue (businesses, points of interest, etc.),
postalcode. Removing unneeded layers will give you
more relevant results and better performance. Check out the complete list in our layers documentation.
Give the Geocoder Hints¶
Only dealing with US & Canadian addresses? Set
boundary.country. Using the map as a viewport to bias results?
Enforce a minimum map zoom if you can before setting a focus point or bounding box. You get the idea. Read the
endpoint documentation for details of the available parameters. Note that in some cases it's possible to go too
Determining Result Quality¶
While the above have focused on how to refine your queries, the API gives a lot of hints back to you as well! Check out our documentation on determining result quality to learn about these cues.