TomTom LogoDocs
Products
Resources
Pricing
Sign in
Geocoding API
Documentation
API Explorer

Structured Geocode

Service version: 2Last edit: 2026.06.10TomTom Orbis Maps

Purpose

The structured geocode endpoint allows you to pass address components such as house number (houseNumber), street (street) and city (municipality) as separate query parameters instead of a single query string. You can specify some or all address components in the request.

This enables more accurate filtering, reduces ambiguity, and ensures that only documents consistent with the provided structured fields are considered. As a result, the Structured Geocode endpoint returns the most relevant match based on the specific address components supplied in the request.

Request data

HTTPS Method: GET

For ease of viewing and identification:

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.

Important note: TomTom-Api-Version header is required for this version.

get
URL request format
https://{baseURL}/maps/orbis/places/structuredGeocode?countryCodeIso2={countryCodeIso2}&position={position}&radiusInMeters={radiusInMeters}&types={types}&areaTypes={areaTypes}&geopoliticalView={geopoliticalView}&maxResults={maxResults}&countrySubdivision={countrySubdivision}&countrySecondarySubdivision={countrySecondarySubdivision}&countryTertiarySubdivision={countryTertiarySubdivision}&municipality={municipality}&municipalitySubdivision={municipalitySubdivision}&postalCode={postalCode}&street={street}&houseNumber={houseNumber}&bbox={bbox}
get
URL request example
https://api.tomtom.com/maps/orbis/places/structuredGeocode?street=De%20Ruijterkade&houseNumber=154&postalCode=1011%20AC&municipality=Amsterdam&countryCodeIso2=NL
get
curl command request example
curl 'https://api.tomtom.com/maps/orbis/places/structuredGeocode?street=De%20Ruijterkade&houseNumber=154&postalCode=1011%20AC&municipality=Amsterdam&countryCodeIso2=NL'

Request parameters

The following table describes the parameters that can be used in a request.

  • Required parameters must be used or the call will fail.
  • Optional parameters may be used.
  • The order of request parameters is not important.
Required parametersDescription

baseURL string

Base URL for calling the API.
Value: api.tomtom.com

countryCodeIso2 string

A country code in ISO 3166-1 alpha-2 format. This will limit the search to the specified country. The choice of view may restrict which countries are available. Visit the Geocoding API Market Coverage page for a list of all the countries supported by the Geocoding API engine.
Format: Two-letter country code
Value: A valid ISO 3166-1 alpha-2 country code.
Example: US
Optional parametersDescription

position string

A position used to bias the search to.
Format: longitude,latitude
Value: A coordinate point.

radiusInMeters integer

This parameter can be only set when the position parameter is also set. When both radiusInMeters and position are set, the results will be constrained to the defined area.
Value: Radius in meters.
Minimum value: 1

types string

A comma-separated list of location types to filter the results.
If no location types are specified then all possible values may occur.
Available values:

  • address
  • street
  • intersection
  • area

Value: A comma-separated list of location types.

areaTypes string

A comma-separated list of sub-types of location type ‘area’ to filter the results.
Available values:

  • country
  • countrySubdivision
  • countrySecondarySubdivision
  • countryTertiarySubdivision
  • municipality
  • municipalitySubdivision
  • municipalitySecondarySubdivision
  • postalCode
  • neighborhood

Value: A comma-separated list of area types.
Example: countrySubdivision,countrySecondarySubdivision

geopoliticalView string

Geopolitical view. The context used to resolve the handling of disputed territories.
Default value: Unified
Available values: Unified, AR, CN, IL, IN, MA, PK, RU, TR, TW, RS
Value: A geopolitical view code.

maxResults integer

Maximum number of results to return.
Default value: 10
Maximum value: 100
Minimum value: 1

countrySubdivision string

A first-level administrative subdivision name of a country or an ISO 3166-2 code.
Value: A country subdivision name or code.

countrySecondarySubdivision string

A second-level administrative subdivision of a country.
Value: A country secondary subdivision.

countryTertiarySubdivision string

A third-level administrative subdivision of a country.
Value: A country tertiary subdivision.

municipality string

A city, town, or municipality.
Value: A municipality name.

municipalitySubdivision string

A subdivision of a municipality.
Value: A municipality subdivision.

postalCode string

A postal code or extended postal code.
Value: A postal code.

street string

A street name.
Value: A street name.

houseNumber string

A house number.
Value: A house number.

bbox string

The corners of the area to report on, expressed in the EPSG:4326 projection. bbox parameter is ignored if position parameter is also provided.
Value: southWestLon,southWestLat,northEastLon,northEastLat
Example: -122.453,37.553,-120.453,39.553

Request headers

Required headersDescription
TomTom-Api-Key

An API Key valid for the requested service.
See: How do I get a TomTom API Key?
Value: Your valid API Key.

TomTom-Api-Version

Version of the API. The API version MUST be specified in all requests.
Value: A service version value. The current value is 2.

Attributes

A list of response fields to return, specified in dot-notation. Nested fields are expressed using . separators and optional grouped subfields using parentheses.
Attributes header must contain at least one valid top-level field. Using only a top-level * wildcard is not allowed.
When a field name refers to a non-primitive object, all its non-EXPLICIT subfields are returned by default unless further restricted in the header. EXPLICIT fields (as documented per API) are only returned when they are explicitly listed in Attributes (they are never included solely by selecting their parent or by using *).
The * wildcard may be used only at non–top-level positions to include all non-EXPLICIT subfields of the selected object.
Syntax:

  • <field-list> ::= <field> (',' <field>)*
  • <field> ::= <name> ('.' <field> | <field-set>)?
  • <field-set> ::= '(' <field-set-list> ')'
  • <field-set-list> ::= '*' (',' <field>)* | <field> (',' <field>)*
  • <name> ::= one or more alphabetic characters

Note:

  • All listed field names must exist in the response domain model; unknown fields result in an error.
  • APIs may restrict which fields are allowed in Attributes. Disallowed-but-existing fields result in an error.
  • New response fields may be added over time. When they are marked EXPLICIT, they are not returned unless explicitly requested via Attributes, preserving backward compatibility and performance.

Examples:

  • Attributes: results.title, results.position
  • Attributes: results(title, position)
  • Attributes: results(*, address(neighborhood))
Optional headersDescription
Tracking-Id

A unique identifier for tracking the request across services. The client should provide a globally unique value, preferably a UUID ( v4 or v7 ). While any string format is accepted, the tracking ID must be unique to enable effective request tracing and correlation in logs.

Accept-Language

Sequence of preferred response IETF BCP 47 language tags compliant with RFC 7231 (section 5.3.5) .
The API makes best effort to return results in one of the preferred languages, falling back to the prevalent local language in the result’s geographical region if none of the preferred languages is available.

Accept

The standard HTTP Accept header indicating the media type(s) the client is able to understand.
Available values: application/json

Accept-Encoding

Enables response compression.
Value: gzip

Attributes-Exclude

A list of response fields to omit from the response, specified in dot-notation. Nested fields are expressed using . separators and optional grouped subfields using parentheses.
Any field listed in Attributes-Exclude, including its entire sub-tree, is omitted from the response, regardless of whether it was included implicitly or explicitly via the Attributes header. Exclusion always overrules inclusion.
The format of the field list is the same “listed dot-notation” used for the Attributes header:
Syntax:

  • <field-list> ::= <field> (',' <field>)*
  • <field> ::= <name> ('.' <field> | <field-set>)?
  • <field-set> ::= '(' <field-set-list> ')'
  • <field-set-list> ::= '*' (',' <field>)* | <field> (',' <field>)*
  • <name> ::= one or more alphabetic characters

Notes:

  • The exclusion list is applied to the result of the inclusion list. If a parent field is excluded, all of its children are excluded, even if some of those children were explicitly listed in Attributes.
  • Listed field names in Attributes-Exclude must exist in the response domain model; unknown fields result in an error.
  • APIs may restrict which fields are allowed in Attributes-Exclude. Disallowed-but-existing fields result in an error.
  • Fields may occur multiple times in Attributes-Exclude (not recommended, but not an error).
  • Some overlap between Attributes and Attributes-Exclude is allowed. In case of overlap, the exclusion takes precedence.
  • Whether a field is EXPLICIT or not does not change the semantics of exclusion: if it is present in Attributes-Exclude, it is omitted whenever it would otherwise have been returned.

Examples:

  • Attributes: results(title, position)
    Attributes-Exclude: results.position
    Results in only the title field being returned for each result, while position is excluded despite being included in Attributes.

  • Attributes: results(*, address(neighborhood, postalCode))
    Attributes-Exclude: results.address.postalCode
    Results in all address fields being returned except for the postalCode field.

Response data

Response body

For illustrative purposes the example below is neatly indented and includes all possible response fields. Actual responses are more compact and the fields present will vary based on the result type and the data available. See the following response fields documentation for more information. When requesting JSON output the response has the following structure:

Response structure - JSON
{
  "results": []
}

Where each element of the results array is in the following format:

Results array elements format - JSON
{
  "id": "a1tgyOViGEeZLkAtZWsQtg",
  "type": "address",
  "title": "2501 Soquel Dr, Santa Cruz, CA 95065",
  "distanceInMeters": 0,
  "position": {
    "type": "Point",
    "coordinates": [-121.97482, 36.98844]
  },
  "address": {
    "country": "United States Of America",
    "countryCodeIso2": "US",
    "countrySubdivision": "CA",
    "countrySubdivisionCodeIso": "US-CA",
    "countrySecondarySubdivision": "Santa Cruz",
    "countryTertiarySubdivision": "Santa Cruz",
    "municipality": "Santa Cruz",
    "municipalitySubdivision": "Live Oak",
    "neighborhood": "Santa Cruz",
    "postalCode": "95065",
    "extendedPostalCode": "950652023",
    "street": "Soquel Dr",
    "houseNumber": "2501"
  },
  "accessPoints": [
    {
      "position": {
        "type": "Point",
        "coordinates": [-121.97487, 36.98817]
      }
    }
  ]
}

Response fields

The following tables describe all of the fields that can appear in a response. Fields are listed by the response section they belong to, and in the order that they appear in the response.

Primary fields
FieldDescription

results array

The result list. results array

results array
FieldDescription

id string

Unique identifier of the result. It can change between new data releases.

type string

Type of result.
Value: One of:

  • address
  • street
  • intersection
  • area

title string

Localized display title for the result.

distanceInMeters integer

This is the great-circle distance, the shortest path between two points on a sphere to returned entity from position. Only present if position parameter is set in the request.

position object

The position of the result in GeoJSON format. position object

address object

The structured address for the result. address object

areaType string

Sub-type of the type=area only present for such result types. One of: country, countrySubdivision, countrySecondarySubdivision, countryTertiarySubdivision, municipality, municipalitySubdivision, municipalitySecondarySubdivision, postalCode, neighborhood

accessPoints array

List of access points of the location. accessPoints array

address object
FieldDescription

country string

Country name.

countryCodeIso2 string

ISO 3166-1 alpha-2 country code. Example: US

countrySubdivision string

State or province.

countrySubdivisionCodeIso string

ISO 3166-2 country subdivision code. Example: US-CA

countrySecondarySubdivision string

County.

countryTertiarySubdivision string

Named area.

municipality string

City or town.

municipalitySubdivision string

Subdivision of a city.

municipalitySecondarySubdivision string

Smaller subdivision of a city.

neighborhood string

Neighborhood.

postalCode string

Postal code (ZIP code).

postalName string

An address component which represents the name for a postal code that is related to a single administrative area, city, town, or other populated place.

extendedPostalCode string

Extended postal code (availability dependent on region).

street string

Name of the street.

houseNumber string

The building number on the street.
position object ( GeoJSON Point )
FieldDescription

type string

GeoJSON type .
Value: Point

coordinates array

A GeoJSON position: [longitude, latitude] optionally followed by elevation in meters.
Example: [-73.935242, 40.73061] or [-73.935242, 40.73061, 10.5]

accessPoints array
FieldDescription

position object

Position of the access point in GeoJSON format. position object

Default view mapping

Default view is recognized based on the country the request came from.

Country

Default view

Other available views

Argentina

AR

Unified, IL, IN, MA, PK, RU, TR, CN, TW, RS

India

IN

-

Morocco

MA

Unified, AR, IL, IN, PK, RU, TR, CN, TW, RS

Pakistan

PK

Unified, AR, IL, IN, MA, RU, TR, CN, TW, RS

Russia

RU

Unified, AR, IL, IN, MA, PK, TR, CN, TW, RS

Turkey

TR

Unified, AR, IL, IN, MA, PK, RU, CN, TW, RS

China

CN

Unified, AR, IL, IN, MA, PK, RU, TR, TW, RS

Taiwan

TW

Unified, AR, IL, IN, MA, PK, RU, TR, CN, RS

Serbia

RS

Unified, AR, IL, IN, MA, PK, RU, TR, CN, TW

Others

Unified

AR, IL, IN, MA, PK, RU, TR, CN, TW, RS

Response codes

The following data table contains HTTP response codes signifying successful and failed requests to an API server.

Successful and failed response codes
CodeMeaning & possible causes
200

OK: The search successfully returned zero or more results.

4XX

Bad Request: Client error.

5XX

Server Error: The service was unable to process your request. Contact support to resolve the issue.

Response headers

The following table contains response headers sent back from an API server.

HeaderDescription
Access-Control-Allow-Origin

Ensures that clients implementing the CORS security model are able to access the response from this service. Value: An asterisk * that signifies access to the TomTom API using the Access-Control-Allow-Origin (ACAO) header in its response, indicating which origin sites are allowed.

Content-Type

Indicates the format of the response, as chosen by the client.
Format: <application/json>; charset=utf-8
Values: <type/subtype> currently supports application/json
Example: application/json; charset=utf-8

Content-Encoding

If requested by the client, the Search service applies gzip compression to the responses with the Accept-Encoding header.
Value: gzip

Content-Language

The HTTP Content-Language representation header is used to describe the language(s) intended for the audience, so users can differentiate it according to their own preferred language. For example, Content-Language: de-DE indicates that the document is intended for German language speakers. The document may be written in English, not German, as part of a language course for German speakers. To indicate the language the document is written in, use the lang attribute instead. If no Content-Language is specified, the default is that the content is intended for all language audiences. Multiple language tags are also possible, as well as applying the Content-Language header to various media types and not only to textual documents.

Tracking-ID

An identifier for the request. If the Tracking-ID header was specified, it is replicated in the response. Otherwise, it is generated automatically by the service. It is only meant to be used for support and does not involve tracking of you or your users in any form.
Value: An identifier for the request.

Error response

Error response content type - JSON
{
  "detailedError": {
    "code": "BAD_REQUEST",
    "message": "Empty countryCodeIso2 parameter"
  }
}

Error response fields

Primary fields
FieldDescription

detailedError object

Detailed error information. detailedError object

detailedError object
FieldDescription

code string

A unique identifier for this particular occurrence of the problem that SHOULD be human-readable.

message string

A description of the error. It is intended as an aid to developers and is not suitable for exposure to end users.

target string

Optional. The target of the error (e.g., the name of the property in error).