Geocoding and Autocomplete Search¶
The Stadia Maps geocoding and autocomplete 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.
-
Geocoding
Search for places by name or address and get their geographic coordinates, website, postal code, and more.
-
Structured Geocoding
Search for places information using structured address components rather than free-form text.
-
Reverse Geocoding
Find places (most commonly street addresses) near a specific location.
-
Autocomplete Search
Build interactive search-as-you-type user experiences, doing quick searches on incomplete input.
-
Place Lookup
Get details on a place via its GID. Useful for looking up details of related places in a response.
Best Practices¶
Tip
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¶
Geographic Coordinates¶
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.
Structured Data¶
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 which 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.), address
, and 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
narrow.
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.