Reverse geocode

Signed in? Open this endpoint in the dashboard playground, which uses your organization automatically. Signed out, use Try in Playground below with your API key.

GET

/geocode/reverse

GET

/geocode/reverse

Finds the address or place at a coordinate.

Without type, the nearest Canonical Address (Address Point layer: NAD, NAR, Overture) within 75 m wins as a building result; Nominatim (OSM, TIGER) fills the remaining slots up to limit. With type, only Nominatim answers (see type). Results are sorted by distance and carry a per-result datasource. The response header X-Geo-Stage names the stage of the first result (canonical, an Engine stage, or none). Results outside the United States and Canada are not expected; an uncovered point returns an empty result list, not an error.

Deviation (approximated): limit up to 100 is accepted, but at most one Nominatim result plus the Canonical Addresses within 75 m (at most 30 candidates) are returned, so lists are usually 1-2 long.

Not supported (rejected or removed): type=locality and type=building (400). Callers that want a building result omit type.

Example: GET /geocode/reverse?lat=38.8977&lon=-77.0365&apiKey=YOUR_API_KEY

Authorization

queryapiKey<token>

Your API key from the dashboard, sent as ?apiKey=<key>.

Query Parameters

lat*number

Latitude (-90 to 90).

Range-90 <= value <= 90

lon*number

Longitude (-180 to 180).

Range-180 <= value <= 180

limit?integer

Maximum number of results, 1-100 (default 1). Deviation (approximated): the result list is short regardless; see the operation description.

Range1 <= value <= 100

Default1

type?string

Requested result type. Omitted: building-level lookup (Canonical Addresses within 75 m, then Nominatim). street queries Nominatim at street zoom; country, state, city, postcode return the address found at the point reduced to that level (empty result if the level is missing); amenity queries Nominatim POI and address layers and returns a result only if it is an amenity. Canonical Addresses are not used when type is set. Deviation (unsupported): locality and building are rejected with 400.

Value in"country""state""city""postcode""street""amenity"

countrycodes?array<>

Keep only results in these ISO 3166-1 alpha-2 countries (case-insensitive, at most 10). Repeat the parameter or comma-separate values. Applied after lookup, so it can empty the result list. Deviation (approximated): any two-letter code is accepted; only us and ca have data.

Itemsitems <= 10

lang?string

Result language, forwarded to Nominatim as accept-language. Omitted: local names. Deviation (approximated): no default of en; Canonical Address results are not translated.

Value in"ab""aa""af""ak""sq""am""ar""an""hy""as""av""ae""ay""az""bm""ba""eu""be""bn""bh""bi""bs""br""bg""my""ca""ch""ce""ny""zh""cv""kw""co""cr""hr""cs""da""dv""nl""en""eo""et""ee""fo""fj""fi""fr""ff""gl""ka""de""el""gn""gu""ht""ha""he""hz""hi""ho""hu""ia""id""ie""ga""ig""ik""io""is""it""iu""ja""jv""kl""kn""kr""ks""kk""km""ki""rw""ky""kv""kg""ko""ku""kj""la""lb""lg""li""ln""lo""lt""lu""lv""gv""mk""mg""ms""ml""mt""mi""mr""mh""mn""na""nv""nb""nd""ne""ng""nn""no""ii""nr""oc""oj""cu""om""or""os""pa""pi""fa""pl""ps""pt""qu""rm""rn""ro""ru""sa""sc""sd""se""sm""sg""sr""gd""sn""si""sk""sl""so""st""es""su""sw""ss""sv""ta""te""tg""th""ti""bo""tk""tl""tn""to""tr""ts""tt""tw""ty""ug""uk""ur""uz""ve""vi""vo""wa""cy""wo""fy""xh""yi""yo""za"

format?string

Response format.

Default"geojson"

Value in"json""geojson""xml"

Response Body

Results sorted by distance; empty when nothing is found. Header X-Geo-Stage names the first result's stage.

response

GeoJSON FeatureCollection (format=geojson, application/geo+json). features is empty when nothing is found.

type*unknown

features*array<>

query*

Echo of the request coordinates.

Example Request

curl -X GET 'https://api.data.graphitelab.ai/v1/geocode/reverse?lat=38.8977&lon=-77.0365&limit=2&type=street&countrycodes=us&lang=en&format=json'

Example Request

curl -X GET 'https://api.data.graphitelab.ai/v1/geocode/reverse?lat=38.8977&lon=-77.0365&limit=2&type=street&countrycodes=us&lang=en&format=json'

Example ResponseSchema

{
  "results": [
    {
      "name": "White House",
      "country": "United States",
      "country_code": "us",
      "state": "District of Columbia",
      "state_code": "DC",
      "city": "Washington",
      "postcode": "20500",
      "street": "Pennsylvania Avenue Northwest",
      "housenumber": "1600",
      "lon": -77.0365525,
      "lat": 38.8976387,
      "formatted": "White House, 1600 Pennsylvania Avenue Northwest, Washington, DC 20500, United States",
      "address_line1": "1600 Pennsylvania Avenue Northwest",
      "address_line2": "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,
        "confidence_city_level": 1,
        "confidence_street_level": 1,
        "confidence_building_level": 1,
        "match_type": "match_by_city_or_disrict",
        "importance": 0.00000999999999995449
      },
      "place_id": "gp:osm:r19761182",
      "distance": 8.2,
      "bbox": {
        "lon1": -77.0368541,
        "lat1": 38.8974904,
        "lon2": -77.0362509,
        "lat2": 38.8977959
      }
    }
  ],
  "query": {
    "lat": 38.8977,
    "lon": -77.0365
  }
}

{  "results": [    {      "name": "White House",      "country": "United States",      "country_code": "us",      "state": "District of Columbia",      "state_code": "DC",      "city": "Washington",      "postcode": "20500",      "street": "Pennsylvania Avenue Northwest",      "housenumber": "1600",      "lon": -77.0365525,      "lat": 38.8976387,      "formatted": "White House, 1600 Pennsylvania Avenue Northwest, Washington, DC 20500, United States",      "address_line1": "1600 Pennsylvania Avenue Northwest",      "address_line2": "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,        "confidence_city_level": 1,        "confidence_street_level": 1,        "confidence_building_level": 1,        "match_type": "match_by_city_or_disrict",        "importance": 0.00000999999999995449      },      "place_id": "gp:osm:r19761182",      "distance": 8.2,      "bbox": {        "lon1": -77.0368541,        "lat1": 38.8974904,        "lon2": -77.0362509,        "lat2": 38.8977959      }    }  ],  "query": {    "lat": 38.8977,    "lon": -77.0365  }}

Reverse geocode

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Authorization

Query Parameters

Response Body