Geocoding is the process of converting an address, place name, or point of interest into geographic coordinates (latitude and longitude). Also called address geocoding, address lookup, or place search, geocoding is the foundation of any product that needs to bridge human-readable places and machine-readable coordinates. Reverse geocoding does the opposite: it takes a coordinate pair and returns the nearest place. The Stadia Maps Geocoding API handles both directions, along with structured, bulk, and autocomplete variants, and draws on a documented set of open data sources so the provenance of every result is inspectable.

Key Takeaways

  • Geocoding converts a human-readable address or place name into geographic coordinates (latitude and longitude). Reverse geocoding does the opposite.
  • Geocoding quality depends on the underlying data. The Stadia Maps Geocoding API documents its five sources: OpenStreetMap, OpenAddresses, Who's On First, GeoNames, and Foursquare Open Source Places.
  • One credit pool covers forward, reverse, structured, bulk, and autocomplete variants. Pick the endpoint that matches the input shape.
  • Accuracy varies by country. Build a confidence check into any product that geocodes internationally.
  • Stadia Maps permits permanent storage of geocoded results on Standard, Professional, and Enterprise plans without a per-request surcharge.

Forward vs. Reverse Geocoding

Geocoding has a direction. Every product decision that involves it starts with picking the right one.

  • Forward geocoding takes a string like Pärnu mnt 388b and returns coordinates like 59.381096, 24.661382. Used for search bars, address forms, and any workflow where a user or dataset knows the place name and needs the location.
  • Reverse geocoding takes coordinates like 59.381096, 24.661382 and returns the nearest known place. Used when the input is a GPS fix, a map click, or an IoT device pinging its location.

Some products need both. A ride-share driver's phone reverses their coordinates to display an address; the passenger's app forward-geocodes a destination string to route to it. The Stadia Maps Geocoding API exposes separate endpoints for each direction, plus specialized ones for autocomplete, structured input, and bulk processing.

For a deeper look at the coordinates-to-place direction, see What Is Reverse Geocoding?

How Geocoding Actually Works

Under the hood, a geocoder is a chain of parsing, matching, scoring, and ranking decisions. The steps look roughly like this:

  1. Parse the input. Break the query into components (house number, street, city, postal code, country, place type).
  2. Search candidate records. Query the underlying database for matches across the relevant data sources and layers.
  3. Score candidates. Rank by string similarity, geographic focus, layer priority, and boundary constraints.
  4. Interpolate when necessary. For addresses that do not exist verbatim in the database, the geocoder can estimate the location by interpolating along the street segment. Not every geocoder does this. The Stadia Maps Forward Geocoding endpoint does.
  5. Return the best matches with a confidence score and full attribution so the caller can decide what to trust.

The details of each step vary by provider, which is why two geocoders can return different results for the same query. Understanding this pipeline is the difference between debugging a geocoding bug in an hour and shipping a workaround that quietly returns the wrong city for 3% of your users.

What Data Sources Does a Geocoder Use?

Every geocoder is only as good as the data it searches. The Stadia Maps Geocoding API is transparent about what it queries; the full source list is documented and each result carries attribution back to its origin.

  • OpenStreetMap provides the primary global coverage for roads, addresses, and points of interest. Community-maintained and open.
  • OpenAddresses aggregates authoritative address data from government and public sources worldwide. Stadia Maps is a corporate sponsor of the project.
  • Who's On First provides a global gazetteer of administrative places (countries, regions, counties, localities, neighborhoods). Used for hierarchy and reverse geocoding at the boundary level.
  • GeoNames adds populated places, natural features, and administrative fill-in for parts of the world where OSM coverage is thinner.
  • Foursquare Open Source Places contributes point-of-interest data for businesses and venues.

Filtering the sources parameter lets you constrain results to a subset when you want to control what backs your search. That is a real feature; most competitor APIs treat their data provenance as a trade secret.

Key Geocoding API Parameters

The forward geocoding endpoint takes one required parameter (text) and several optional ones that dramatically change what you get back. Full details in the Forward Geocoding docs.

  • text: The place name or address. Required.
  • focus.point.lat / focus.point.lon: Bias results toward a focus point. Use the user's map center or their known location to prefer nearby matches.
  • boundary.rect.*, boundary.circle.*, boundary.country, boundary.gid: Hard limits on where results can appear. Use these when your product only operates in specific regions.
  • layers: Restrict to specific data layers (address, venue, postalcode, country, and more). Fewer layers means faster, more relevant results.
  • sources: Restrict to specific data sources (openstreetmap, openaddresses, whosonfirst, geonames, foursquare). Useful when you want, for example, only address-authoritative sources for a shipping form.
  • size: Maximum number of results to return. Default is 10.
  • lang: A BCP47 language tag for localized results.

The single most common mistake is over-constraining. If your first query returns nothing, drop a boundary or a layer filter before assuming the geocoder is broken.

Why Geocoding Accuracy Varies by Country

Geocoding quality is not uniform globally. Address density, government data availability, and OSM coverage all vary by country. This is a factual limitation that competitor "what is geocoding" pages tend to skip.

Some patterns worth knowing:

  • North America and Western Europe have deep coverage across OSM, OpenAddresses, and Who's On First. Interpolation fills in most missing house numbers along known streets.
  • Japan and parts of East Asia use non-linear addressing systems that do not map cleanly to street-and-number geocoders. Structured input helps a lot here; see the Structured Geocoding endpoint.
  • Rapidly growing cities in South Asia, Southeast Asia, and Africa may have addresses that exist physically but are not yet in any data source. Fuzzy matching and community-driven OSM contributions close the gap over time; expect variance.
  • Rural and remote areas everywhere degrade gracefully to the nearest named place rather than an exact street number.

If your product operates internationally, build in a confidence check (see the Determining Result Quality docs) and design a fallback UX for low-confidence matches. Do not assume the same accuracy in every market.

How Do You Geocode an Address?

Here is what a forward geocoding request to the Stadia Maps Geocoding API looks like. This example geocodes an address in Tallinn, Estonia.

GET https://api.stadiamaps.com/geocoding/v1/search?text=P%C3%B5hja+pst+27

The response is a GeoJSON FeatureCollection. Each feature carries the coordinates, the parsed address components, a confidence score, and source attribution. Full response format details are in the Common Response Format docs.

For runnable code in TypeScript, Python, Kotlin, Swift, PHP, or cURL, see the Stadia Maps Forward Geocoding API docs.

Structured vs. Bulk vs. Autocomplete Geocoding

Forward geocoding is not always the right endpoint. The Geocoding & Search overview breaks down when to use each variant.

  • Building an interactive search-as-you-type experience? Use the Autocomplete endpoint. It is optimized for partial input and faster response times. See What Is Address Autocomplete?
  • Working with pre-parsed address components (house_number, street, city, region, postalcode, country)? Use Structured Geocoding. It takes the guesswork out of string parsing and improves accuracy for postal addresses, especially internationally.
  • Processing thousands of addresses at once? Use Bulk Geocoding. Up to 5,000 queries per request.
  • Reversing coordinates back to a place? Use the Reverse Geocoding endpoint.

Comparing providers rather than endpoints? See What Is the Best Geocoding API? for the evaluation criteria that matter after launch.

Where Geocoding Falls Short

Geocoding has real limits. A page that pretends otherwise is not being honest with the reader.

  • A geocoder is not an address validator. It returns the best match it can find. If your user typed a nonexistent address, the geocoder will often return a nearest-street-segment interpolation rather than an error. Check the confidence score and layer type on every result before treating it as authoritative.
  • Autocomplete and forward geocoding are not interchangeable. Autocomplete is optimized for speed on partial input; forward geocoding is optimized for accuracy on complete input. Using one where the other belongs produces bad UX or bad results.
  • Interpolated addresses are estimates, not guarantees. The result may be tens of meters off the actual building, or on the wrong side of the street. For delivery-critical use cases, verify with a follow-up reverse geocode or with authoritative sources.
  • Two providers rarely agree exactly. Different providers use different data sources, different scoring, and different parsers. Pick one and standardize within your own product to avoid inconsistencies.
  • You may or may not be allowed to store results. Most vendors charge extra to persist geocoding results in your own database. Stadia Maps allows permanent storage on the Standard, Professional, and Enterprise plans without a surcharge; see the terms of service for details.

Common Geocoding Use Cases

Geocoding shows up anywhere a product needs to move between human-readable places and machine-readable coordinates. A partial list:

  • Address forms and checkout flows. Convert a user-entered shipping address to coordinates for downstream routing, delivery-zone checks, or tax calculation.
  • Store locator and site finder. Take a user's zip code or city and center the map on the corresponding coordinates.
  • Lead enrichment and CRM cleanup. Bulk-geocode a customer list to enable geographic segmentation, territory analysis, or field-sales routing.
  • Logistics and last-mile delivery. Convert delivery addresses to coordinates for isochrone-based service-area decisions or routing.
  • Real estate search. Geocode a listing's address to place it on a map and enable spatial queries.
  • Location-aware AI and agents. Give an LLM or agent the ability to translate free-text user requests ("a coffee shop near Union Square") into structured coordinates for a follow-up API call.

Frequently Asked Questions

What is address geocoding?

Address geocoding is the process of converting a street address or place name into geographic coordinates (latitude and longitude). It is the primary way products bridge between human-readable location input and machine-readable spatial data. The Stadia Maps Geocoding API handles address geocoding through its forward geocoding, structured geocoding, and autocomplete endpoints.

What is the difference between geocoding and reverse geocoding?

Geocoding (forward geocoding) converts an address or place name into coordinates. Reverse geocoding does the opposite: it converts coordinates into an address or place. Products that combine both directions are common. For example, a user types a destination (forward geocoded) and a driver's phone shows the address of their current GPS position (reverse geocoded).

What data sources does the Stadia Maps Geocoding API use?

The Stadia Maps Geocoding API queries five documented open sources: OpenStreetMap for global roads and points of interest, OpenAddresses for authoritative government address data, Who's On First for administrative places, GeoNames for populated places and natural features, and Foursquare Open Source Places for business and venue data. Every result carries attribution back to its source, and Stadia Maps is a corporate sponsor of the OpenAddresses project.

Can I store geocoded addresses permanently on Stadia Maps?

Yes. With an active Standard, Professional, or Enterprise subscription, geocoded results can be stored permanently in your own database, with no per-request surcharge and no per-user re-validation. Temporary storage in the normal course of your work is allowed on all plans, including Free. Per Stadia Maps' published analysis, Mapbox, AWS, and ESRI often charge between 6x and 8x the cost of a regular query to store results, and Google generally forbids caching outside a specific end-user session.

How much does a geocoding request cost on Stadia Maps?

Geocoding requests draw from a unified credit pool that also covers routing, tiles, and other endpoints. Forward, structured, and reverse geocoding each cost 20 credits per request. Autocomplete v2 costs 1 credit per request. Bulk geocoding is billed per query inside the batch at the same rate as an individual request, so there are no extra fees for using batch mode.

How accurate is geocoding?

Accuracy varies by country and by data source. North America and Western Europe have deep coverage across OpenStreetMap, OpenAddresses, and Who's On First. Regions with non-linear addressing systems or newer construction see more variance. Every Stadia Maps result returns a confidence score and a layer type, which is how you detect a weak match in production rather than shipping it to a user.

Where to Go Next

From the Blog

More on geocoding from the Stadia Maps blog: