Location Types

Each location in a Directions request must have exactly one of: latLng, address, or address_structured. Types can be mixed freely within a single request.

All locations accept an optional id field — a caller-supplied string echoed back in the response waypoints for matching results to your input records.

Coordinates — latLng

Use when you already have GPS coordinates. No geocoding is performed.

{
  "id": "depot",
  "latLng": { "lat": 54.6872, "lng": 25.2797 }
}

Field	Type	Required
latLng.lat	number	yes
latLng.lng	number	yes

Unstructured address — address

Use for free-form address strings. Handles missing postcodes, abbreviations, and mixed formats.

{
  "id": "stop-1",
  "address": "Laisves al. 82, Kaunas"
}

Field	Type	Required
address	string (min 3 chars)	yes

If the address cannot be matched above the confidence threshold, the location is excluded from routing and returned in excluded_waypoints.

Structured address — address_structured

Use when your input data has postcode, city, and street as separate fields — typically from an order management system or spreadsheet import.

{
  "id": "stop-2",
  "address_structured": {
    "postcode": "44280",
    "city": "Kaunas",
    "street": "Laisves al. 82"
  }
}

Field	Type	Required	Notes
address_structured.street	string	yes	Street name and building number
address_structured.postcode	string	no	Improves accuracy significantly when provided
address_structured.city	string	no	Used as a filter when postcode is absent

Providing an accurate postcode gives the best match results. When postcode is omitted, city is used to narrow the search.

Mixed example

All three types can be used in the same request:

{
  "profile": "auto",
  "locations": [
    {
      "latLng": { "lat": 54.6872, "lng": 25.2797 }
    },
    {
      "id": "stop-1",
      "address": "Laisves al. 82, Kaunas"
    },
    {
      "id": "stop-2",
      "address_structured": {
        "postcode": "76352",
        "city": "Šiauliai",
        "street": "Vilniaus g. 88"
      }
    },
    {
      "latLng": { "lat": 54.6872, "lng": 25.2797 }
    }
  ]
}