Reverse geocoding

GET /v1/geocode/reverse returns the address or place nearest a coordinate. Use it to label a map click, a GPS fix or a stored point. Without type you get a building-level answer; with type you can ask for the street, city, state, postcode, country or an amenity instead.

How it worksCopy Anchor Link

Everything is answered from the service's own Engines, never from a third party.

1. Canonical Addresses (PostGIS). Without type, the gateway looks up the nearest Canonical Address in the Address Point layer (NAD for the US, StatCan NAR for Canada, Overture). Any within 75 m count as building results. The query reads at most 30 candidates.
2. Nominatim (OSM, TIGER). If fewer than limit results exist, the gateway asks Nominatim for a reverse lookup at building zoom (street zoom for type=street). A building already returned by step 1 is not repeated.
3. Sort and filter. Results are sorted by distance, then countrycodes is applied, then the list is cut to limit.

With type set, only Nominatim answers. The X-Geo-Stage response header names the stage of the first result (canonical, an Engine stage, or none).

Quick startCopy Anchor Link

curl -s "https://api.data.graphitelab.ai/v1/geocode/reverse?lat=38.8977&lon=-77.0365&apiKey=$GRAPHITE_API_KEY"

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "White House",
        "country_code": "us",
        "state_code": "DC",
        "city": "Washington",
        "postcode": "20500",
        "street": "Pennsylvania Avenue Northwest",
        "housenumber": "1600",
        "formatted": "White House, 1600 Pennsylvania Avenue Northwest, Washington, DC 20500, United States",
        "result_type": "amenity",
        "datasource": {
          "sourcename": "openstreetmap",
          "attribution": "© OpenStreetMap contributors",
          "license": "Open Database License",
          "url": "https://www.openstreetmap.org/copyright"
        },
        "rank": { "confidence": 1, "match_type": "match_by_city_or_disrict" },
        "place_id": "gp:osm:r19761182",
        "distance": 8.2
      },
      "geometry": { "type": "Point", "coordinates": [-77.0365525, 38.8976387] }
    }
  ],
  "query": { "lat": 38.8977, "lon": -77.0365 }
}

ParametersCopy Anchor Link

Full parameter reference

ResponseCopy Anchor Link

The default geojson format is a FeatureCollection sorted by distance; format=json returns the same properties under results. An uncovered point returns an empty list, not an error.

Differences from GeoapifyCopy Anchor Link

• approximated: at most one Nominatim result plus the Canonical Addresses within 75 m are returned, so lists are short (usually 1 to 2) even with a large limit.

• approximated (limit): accepted up to 100, but few candidates exist per point.

• approximated (countrycodes): a post-filter on results. Any two-letter code is accepted, but only us and ca have data.

• approximated (lang): not defaulted to en. Canonical Address results ignore lang.

• unsupported: type=locality and type=building are rejected with 400. To get a building, omit type.

• empty: only a subset of Geoapify's place fields is populated.

• extra: datasource.sources[] when several Address Point sources agree, and the X-Geo-Stage response header.

US and Canada notesCopy Anchor Link

• Coverage is the United States and Canada only. A point elsewhere returns an empty list.

• Building-level answers come from NAD (US), StatCan NAR (Canada) and Overture; OSM and TIGER fill the rest through Nominatim.

• Canadian postcodes come back in full postal-code form, for example K1P 5M7.

• Address Point street casing is echoed from the source, so you can see values like PENNSYLVANIA Avenue Northwest.

More examplesCopy Anchor Link

curl -s "https://api.data.graphitelab.ai/v1/geocode/reverse?lat=45.4215&lon=-75.6972&apiKey=$GRAPHITE_API_KEY"

Errors and limitsCopy Anchor Link

Limits: limit is 1 to 100, countrycodes takes at most 10 codes, and Canonical Addresses count only within 75 m of the point.