Skip to content

Geocoding

Definition

A Geocoder is software that maps an address to a coordinate ("geocoding") or finds the nearest addresses to a coordinate ("reverse geocoding").

Almost all MapTrip Server API endpoints are based on coordinates. For example, if you want to calculate a route between two addresses, you need to know their coordinates. To do this, you can use the endpoints [GET] /geocoder (if you have an address string) or [GET] /geocoder/structured (if you have structured address information, i.e. street, house number, postal code and city). Generally the quality is better for structured data as more context is provided.

Important

All coordinates in the MapTrip Server API are specified as WGS84 decimal degrees (EPSG:4326).

Countries

If you know the country where an address is located, you should specify it in the request. This may improve the quality of the results. Countries are specified as ISO 3166-1 alpha-3 country codes (see Wikipedia).

If the country where the address is located is not known, leave the parameter country empty. In this case, all countries are searched.

Geocode an Address String

Used if the address of a destination is known as an address string but the coordinates are needed.

Request to [GET] /geocoder

Example curl command:

curl -X GET "https://api.maptrip.de/v1/geocoder?provider=TomTom&address=Berlin&country=DEU&limit=1" -H "accept: application/json" -H "Authorization: Bearer <token>"

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
[
  {
    "quality": "DADD",
    "probability": 100,
    "address": {
      "city": "Berlin",
      "part": "",
      "zipcode": "10178",
      "street": "",
      "housenumber": "",
      "ags": "11000000",
      "country": "DEU",
      "coordinate": {
        "lat": 52.523429,
        "lon": 13.411437
      }
    }
  }
]

For details on the highlighted fields see Quality and probability of the results.

Geocode a Structured Address

Used if the address of a destination is known as street, house number, postal code and city (or part of that information).

Request to [GET] /geocoder/structured

Example curl command:

curl -X GET "https://api.maptrip.de/v1/geocoder/structured?provider=TomTom&street=Weiherstr.&housenumber=38&postalcode=53111&city=Bonn&country=DEU&limit=1" -H "accept: application/json" -H "Authorization: Bearer <token>"

Response

The response format for this endpoint is the same as for [GET] /geocoder.

Reverse Geocoding

Used to find the nearest addresses for a coordinate. Use the parameter limit to specify the number of addresses to return.

Request to [GET] /geocoder/reverse

Example curl command:

curl -X GET "https://api.maptrip.de/v1/geocoder/reverse?provider=TomTom&lat=50.7365574&lon=7.0919497&limit=2" -H "accept: application/json" -H "Authorization: Bearer <token>"

Response

In this example 2 addresses where queried. These addresses are ordered by distance (in meters) to the specified coordinate:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
[
  {
    "distance": 0,
    "address": {
      "city": "Bonn",
      "part": "Nordstadt",
      "zipcode": "53111",
      "street": "Weiherstr.",
      "housenumber": "38",
      "ags": "05314000",
      "country": "DEU",
      "coordinate": {
        "lat": 50.7365574,
        "lon": 7.0919497
      }
    }
  },
  {
    "distance": 11.757,
    "address": {
      "city": "Bonn",
      "part": "Nordstadt",
      "zipcode": "53111",
      "street": "Weiherstr.",
      "housenumber": "36",
      "ags": "05314000",
      "country": "DEU",
      "coordinate": {
        "lat": 50.7366517,
        "lon": 7.092026
      }
    }
  }
]

Administrative Areas

If you use a data provider whose data includes administrative areas, they will be returned in geocoded and reverse geocoded addresses. The number and types of areas vary from country to country. For example, for Germany these are Bundesland, Kreis and Gemeinde, and for France Région, Département and Commune.

If administrative areas are available, geocoded addresses contain an attribute administrativeAreas, which is an array of areas with a type and a name each. These are sorted from the largest to the smallest level:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
[
  {
    "quality": "AAAA",
    "probability": 100,
    "address": {
      "city": "Bonn",
      "part": "Nordstadt",
      "zipcode": "53111",
      "street": "Weiherstr.",
      "housenumber": "38",
      "ags": "05314000",
      "country": "DEU",
      "administrativeAreas": [
        {
          "type": "Bundesland",
          "name": "Nordrhein-Westfalen"
        },
        {
          "type": "Kreis",
          "name": "Bonn"
        },
        {
          "type": "Gemeinde",
          "name": "Bonn"
        }
      ],
      "coordinate": {
        "lat": 50.7367,
        "lon": 7.09214
      }
    }
  }
]

Administrative areas are available for the data providers TomTom and HERE, but not for OpenStreetMap.

Quality and probability of the results

The field probability is a rough probability that this address corresponds to the one searched for. This is a numerical value between 0 and 100. This value can be used to select the most likely best result from several results.

The 4-letter code quality in the geocoder response indicates for each address component (postal code, city, street and house number) how well the input matches the found address. This code can be used to determine, for example, whether a spelling error in the street name was corrected or whether the postal code was missing from the input. This is the most detailed quality information.

The order of the letters in this code (e.g. AMAA) is:

  1. Postal code
  2. City
  3. Street
  4. House number

The meaning of the letters is as follows:

Letter Description Examples
A Your input could be found exactly (taking standardizing procedures into account) in the reference database. Due to standardization, typical systematic typing errors are tolerated. "Eupener Straße" can also be written as "Eupenerstraße"
B Your input can only be found in the reference data by a phonetic search. This may occur if the address contains spelling errors. "Dekan-Husler-Str." instead of "Dekan-Häusler-Str.", "Neuenkirchen" instead of "Neunkirchen"
C This input cannot be found in the reference data in connection with your address. It may well be that a piece of information appears as a single piece of information in the reference data, but not in connection with the other components of your address. Both the postal code 50829 and the city Leverkusen can be found, but both information in context cannot be found as this postal code belongs to another city.
D This part of the address (e.g. postal code) was not specified.
E There is only a coordinate for this street (or part of this street), since there are no house numbers for this street in the reference database.
G This input can only be found with successive approximation in the reference data. This can happen if the address contains spelling errors. "Schliefenbühl" instead of "Schliefebühl", "Wolfbanksring" instead of "Wolfbankring"
M This input can only be found by comparing with different street types and expanding abbreviations in the reference data This can happen if the address contains an incorrect street name. "Kupferplatz" instead of "Kupferstr.", "M.-Brüggen-Str." instead of "Mathias-Brüggen-Str."

Example: Geocoding Rimenschneider 12, Bonn results in the quality DABC.

  1. letter D: The postal code was not specified
  2. letter A: The city was found as specified
  3. letter B: The street contains spelling errors and was found by a phonetic search
  4. letter C: The house number 12 was corrected to 10 (same side of the street), because the street has only house numbers 1 - 11