Reverse Geocoding Addresses

POST https://routecloud.telogis.com/v1/reverse_geocode.
Authentication required.
Request body: reverse_geocode_request.
Response body: If wait=1 specified, returns the task result (see below). Otherwise, returns a task_redirect_response.
Task result: reverse_geocode_response.

Reverse geocoding is the process of converting map coordinates into an address. To translate an address into a latlon, see the Geocode endpoint.

Note

It is important to manually verify reverse geocoding results.

Query Parameters

wait=1 - Optional. Wait until the reverse_geocode completes before returning the result. See Retrieving API Results.

Status Codes

200 - Success.
302 - If wait=1 was provided and the reverse_geocode result is not yet available, a redirect is sent instead of a normal result every 15 seconds to refresh the HTTP timeout. See Retrieving API Results.
400 - The input is invalid. The response is an error_response.
401 - Authentication required.
429 - Exceeded usage limits.
500 - Unable to reverse_geocode all addresses in this request. The response is an error_response. See geostream_unavailable.

reverse_geocode_request

Name	Type	Description
id	string	Inherited. An identifier for the request. See Request IDs.
locations	reverse_geocode_location[]	The map coordinates of the locations to reverse geocode.
name	string	Inherited. A name for the request. See Request IDs.

{
  "id": "request+1234567",
  "name": "territory1",
  "locations": [
    { "id": "rgc0", "location": "33.584362,-117.730968" },
    { "location": "30.396790,-97.731577" }
  ]
}

reverse_geocode_location

Name	Type	Description
id	id	Optional. The ID of the location to reverse geocode.
location	latlon	The coordinates of the location to reverse geocode.

reverse_geocode_response

Name	Type	Description
geocoded_locations	geocoded_location[]	The addresses of the reverse geocoded locations.

{
  "geocoded_locations": [
    {
      "suggestions": [
        {
          "location": "33.584362,-117.730968",
          "intersection": "33.584409,-117.730945",
          "formatted_address": "20 Enterprise, Aliso Viejo, Orange, California, 92656, USA",
          "street_number": "20",
          "street_name": "Enterprise",
          "subregions": [],
          "regions": [
            "Aliso Viejo",
            "Orange",
            "California"
          ],
          "post_code": "92656",
          "country": "US"
        }
      ],
      "id": "rgc0"
    },
    {
      "suggestions": [
        {
          "location": "30.396790,-97.731577",
          "intersection": "30.396806,-97.731632",
          "formatted_address": "10801 N Mopac Expy, Austin, Travis, Texas, 78759, USA",
          "street_number": "10801",
          "street_name": "N Mopac Expy",
          "subregions": [],
          "regions": [
            "Austin",
            "Travis",
            "Texas"
          ],
          "post_code": "78759",
          "country": "US"
        }
      ]
    }
  ]
}

An example reverse geocode response.

The reverse geocode response contains an array of reverse_geocode_result objects in the results array. The array has the same ordering as the request array. If IDs are provided in the request, they persist in the response. Each reverse_geocode_result object has a list of suggestions, which can be empty if reverse geocoding failed. There is usually only one suggestion.