Geocoding Addresses

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

Geocoding is the process of translating an address into map coordinates. The geocode call provides forward geocoding to find the latitude and longitude of an address. To translate a latlon into an address, see the Reverse Geocode endpoint.

Note

It is important to manually verify geocoding results. Ideally customers should use a map to select and verify their delivery locations.

Query Parameters

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

Status Codes

200 - Success.
302 - If wait=1 was provided and the 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 geocode all addresses in this request. The response is an error_response. See geostream_unavailable.

geocode_request

Name	Type	Description
addresses	geocode_address_request[]	The addresses to geocode.
custom	custom	User-supplied custom fields that are returned unmodified in the response. These have no effect on optimization.
id	string	Inherited. An identifier for the request. See Request IDs.
name	string	Inherited. A name for the request. See Request IDs.

{
  "id": "request+1234567",
  "name": "territory1",
  "addresses": [
    { "id": "address0", "query": "20 Enterprise Drive, Aliso Viejo, CA", "country": "US" },
    { "query": "10801 N Mopac Expy #500, Austin, TX 78759", "country": "US", "max_results": 1 }
  ]
}

An example geocode request.

geocode_address_request

Name	Type	Description
country	string	Required. The two letter ISO 3166-1 country code of the address. For example, `US` or `GB`.
custom	custom	User-supplied custom fields that are returned unmodified in the response. These have no effect on optimization.
id	id	Optional. The ID of the address to geocode.
max_results	integer	The maximum number of results to return. Defaults to `10`.
query	string	Required. The address to geocode. For example, `4463 Cherokee Street, Denver, CO 80216`.

geocode_response

Name	Type	Description
custom	custom	User-supplied custom fields that were sent in the request.
geocoded_locations	geocoded_location[]	The map coordinates and corresponding addresses of the geocoded locations.

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

An example geocode response.

The geocode response contains an array of geocode_address_response objects in the geocoded_locations array. The array has the same ordering as the request array. If IDs are provided in the request, they persist in the response. Each geocode_address_response object has a list of suggestions, which can be empty if geocoding failed.

Incomplete Geocodes

The query "Denver, Colorado" does not include street information. For that reason, the street_number, street_name, post_code, and intersection fields are omitted from its response.

When geocoding for the purpose of route optimization, it is important to verify that the response contains a street_name, as this verifies that a street-level match was found. A city-level match is not accurate enough for route optimization.

Request

{
  "addresses": [
    { "query": "Denver, Colorado", "country": "US", "max_results": 1 }
  ]
}

Response

{
  "geocoded_locations": [
    {
      "suggestions": [
        {
          "location": "39.740009,-104.992020",
          "formatted_address": "Denver, Colorado",
          "subregions": [],
          "regions": [
            "Denver",
            "Denver",
            "Colorado"
          ],
          "country": "US"
        }
      ]
    }
  ]
}

The string "Denver" appears in the regions list twice because it is both the City and the County in this case.