Reverse geocoding is the process of converting a coordinate pair (latitude and longitude) into a human-readable address, place name, or administrative boundary. Also called coordinate lookup or address lookup from coordinates, reverse geocoding is what turns a GPS fix, a map click, or an IoT device ping into something a person can read. It is the counterpart to forward geocoding, which goes the other direction (address to coordinates). The Stadia Maps Reverse Geocoding API can return the nearest address, the nearest point of interest, or the administrative context (neighbourhood, locality, county, region, country) for any point on Earth.

Key Takeaways

  • Reverse geocoding converts coordinates into an address, place name, or administrative boundary.
  • The Stadia Maps Reverse Geocoding API supports fine-grained layers (address, poi, street) and coarse administrative layers (neighbourhood, locality, county, region, country).
  • Coarse-layer requests return features that contain the point. Fine-layer requests return the nearest features by distance.
  • Postal codes are not a reverse-geocoding layer on the Stadia Maps API. Read them from the returned address instead.
  • Reverse geocoding is available on every Stadia Maps plan, and results can be stored permanently on Standard, Professional, and Enterprise plans.

How Reverse Geocoding Works

Under the hood, reverse geocoding is a spatial search problem with two distinct modes.

  1. Nearest-neighbor mode (for fine-grained layers like address, poi, and street). The geocoder searches for the closest features to the coordinate and returns them sorted by distance.
  2. Point-in-polygon mode (for coarse administrative layers like country, region, county, locality, and neighbourhood). The geocoder returns the features whose boundaries contain the point.

The Stadia Maps Reverse Geocoding API runs both modes from the same endpoint. Which behavior you get depends on the layers parameter you pass. Combined queries return a mixed result set.

Each result carries source attribution and a confidence score. See Determining Result Quality for how to read those signals.

What Are Layers in Reverse Geocoding?

Every place in the Stadia Maps geocoder is tagged with a layer that describes what kind of thing it is. Reverse geocoding uses layers in two ways: to filter what comes back, and to determine how the search is executed (nearest versus containing).

The layers most useful for reverse geocoding:

  • address: A specific street address.
  • poi (or venue in v1): A business, building, or point of interest.
  • street: A road or street segment.
  • neighbourhood: A social or administrative neighbourhood (note the British spelling).
  • locality: A town, hamlet, or city.
  • county, region, country: Progressively larger administrative units.
  • coarse: An alias that queries all administrative layers at once. Fast, useful when you only need context.

Postal codes are not used as a reverse-geocoding layer on the Stadia Maps API. If you need a postal code for a point, reverse geocode to the address layer and read the postal code from the result.

Reverse Geocoding Parameters That Matter

The Reverse Geocoding endpoint takes two required parameters and several optional ones that change the result set.

  • point.lat and point.lon: The coordinate to reverse geocode. Both required.
  • layers: Restrict the search to specific layers. Defaults to fine-grained layers when omitted.
  • sources: Restrict to specific data sources (openstreetmap, openaddresses, whosonfirst, geonames, foursquare).
  • boundary.country: Limit results to specific countries (ISO 2 or 3 character codes).
  • boundary.circle.radius: For fine-grained queries, limit the search to a circle around the point. Defaults to 1km.
  • size: Maximum number of results to return. Defaults to 10.

The most common tuning move is switching to layers=coarse for fast administrative-context lookups. That query type does not need to sort by distance and typically returns quickly.

How Do You Reverse Geocode a Coordinate?

Here is what a reverse geocoding request to the Stadia Maps API looks like. This example reverses a point in Tallinn, Estonia.

GET https://api.stadiamaps.com/geocoding/v2/reverse?point.lat=59.444351&point.lon=24.750645

The response is a GeoJSON FeatureCollection. Each feature includes the coordinates, parsed address components, layer, 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 Reverse Geocoding API docs.

Where Reverse Geocoding Falls Short

Reverse geocoding has real limits worth knowing before you build.

  • Coordinates in ambiguous places produce ambiguous results. A point inside a parking lot, an office park, or a large building can return the parent property, a neighboring address, or nothing useful. Always check the layer and confidence of the top result.
  • Coordinates over water or wilderness are best effort. Reverse geocoding returns the nearest feature; if that feature is 20km away, the result is a geographic fact, not an address.
  • Coarse and fine results answer different questions. "What city is this in?" (coarse, point-in-polygon) and "What is the nearest street address?" (fine, nearest-neighbor) look similar but return different shapes of answer. Pick the layer that matches the question.
  • Postal codes are not a reverse-geocoding layer. As noted above, read them from the returned address rather than querying them directly.
  • Two providers rarely agree exactly. Different providers use different data, different scoring, and different tie-breaking logic. Standardize on one provider to keep your product consistent.

Common Reverse Geocoding Use Cases

Reverse geocoding appears wherever a product has coordinates but needs to display something a human can read.

  • Delivery and ride-share pickup. A driver's phone reports GPS coordinates. The app reverses those coordinates to display the pickup address to the passenger.
  • Emergency response. A 911 call carries GPS coordinates. Reverse geocoding turns those into a street address for the dispatcher.
  • Photo and content tagging. Add city, region, and country tags to photos or posts based on where they were captured.
  • IoT and connected devices. A sensor pings its location periodically; reverse geocoding turns that into a place the operator recognizes.
  • Location-aware AI and agents. Give an agent the ability to answer "Where am I?" or "What neighborhood is this?" from raw coordinates.
  • Analytics and segmentation. Roll up event coordinates to city, region, or country for cohort analysis without asking the user for input.

Frequently Asked Questions

What is reverse geocoding used for?

Reverse geocoding is used to convert a coordinate pair into a human-readable address, place name, or administrative boundary. Common uses include showing a rider's pickup address from GPS coordinates, powering nearby-place suggestions in delivery apps, tagging photos with a location, and identifying which city, county, or country a point falls within.

What is the difference between reverse geocoding and forward geocoding?

Forward geocoding converts an address or place name into coordinates. Reverse geocoding does the opposite: it converts coordinates into an address or nearby place. See What Is Geocoding? for a full explanation of the forward direction; products that combine both are common.

What layers can reverse geocoding return on Stadia Maps?

The Stadia Maps reverse geocoding endpoint can return fine-grained layers (address, poi, street) or coarse administrative layers (neighbourhood, locality, county, region, country). Use the layers parameter to restrict results. Coarse layers return features that contain the point; fine layers return the nearest features by distance. Full list in the Layers documentation.

Can I reverse geocode to a postal code?

Not directly. Postal codes are not used as a reverse geocoding layer on the Stadia Maps API. If you need a postal code for a coordinate, use reverse geocoding to retrieve the address and read the postal code from that result.

How much does a reverse geocoding request cost on Stadia Maps?

Reverse geocoding requests are billed from the unified Stadia Maps API credit pool, the same pool that covers forward geocoding, routing, and tiles. Each reverse geocoding request is a single billable request.

Where to Go Next

From the Blog

More on geocoding and search from the Stadia Maps blog: