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").

Many 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) or [GET] /geocoder/autocomplete (to support users when entering data in address fields). See Choosing the most suitable Endpoint to find the best endpoint for your use case.

Important

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

Choosing the most suitable Endpoint

There are three endpoints to query coordinates of addresses (geocoding) and one to find addresses near a coordinate (reverse geocoding). You should select different endpoints depending on the use case:

  1. [GET] /geocoder/structured accepts structured address data, i.e. a street, a house number, a postal code and a city. If your data is already structured, for example in an Excel file with columns for the address components, you should choose this endpoint. The quality of structured data is generally better, as more context is provided. See Geocode a Structured Address.

  2. [GET] /geocoder handles address strings which contain street, house number, postal code and / or city. If your data is complete address strings like Weiherstr. 38, 53111 Bonn, this is the best endpoint to use. See Geocode an Address String.

  3. [GET] /geocoder/autocomplete processes incomplete strings to help users enter addresses as they type. For this purpose, the input is sent to this endpoint after each keystroke and the suggested addresses are shown to the user. Use this endpoint for address fields in forms. See Geocoder Autocomplete Mode.

  4. [GET] /geocoder/reverse find the nearest addresses for a coordinate provided as latitude and longitude. See Reverse Geocoding.

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.

Geocoder Autocomplete Mode

The endpoint [GET] /geocoder/autocomplete is very similar to [GET] /geocoder, but the input is treated as a prefix of an address. Use this endpoint to build an autocomplete functionality for an input form by sending the user input after every keystroke and showing the addresses to the user.

The user input can be a city name, city part, postal code, street (with or without house number) or a combination. Therefore, the result can contain different types of addresses: The input string neust is the prefix of the city Neustadt an der Weinstraße, the city part Neustadt of Berlin, and the street Neustrelitzer Str. in Berlin. For this query string, the response is a mix of cities, parts and streets (see the highlighted attributes quality in the example).

Request to [GET] /geocoder/autocomplete

Example curl command:

curl -X GET "https://api.maptrip.de/v1/geocoder/autocomplete?provider=TomTom&address=Bre&country=DEU&limit=5" -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
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
[
  {
    "quality": "City",
    "address": {
      "city": "Neustadt an der Weinstraße",
      "part": "",
      "zipcode": "67434",
      "country": "DEU",
      "coordinate": {
        "lat": 49.350289,
        "lon": 8.137916
      }
    }
  },
  {
    "quality": "City",
    "address": {
      "city": "Neustadt am Rübenberge",
      "part": "",
      "zipcode": "31535",
      "country": "DEU",
      "coordinate": {
        "lat": 52.504469,
        "lon": 9.462111
      }
    }
  },
  {
    "quality": "Part",
    "address": {
      "city": "Berlin",
      "part": "Neustadt",
      "zipcode": "13585",
      "country": "DEU",
      "coordinate": {
        "lat": 52.552938,
        "lon": 13.199372
      }
    }
  },
  {
    "quality": "Street",
    "address": {
      "city": "Berlin",
      "part": "Alt-Hohenschönhausen",
      "zipcode": "13055",
      "street": "Neustrelitzer Str.",
      "country": "DEU",
      "coordinate": {
        "lat": 52.537381,
        "lon": 13.495175
      }
    }
  },
  {
    "quality": "Street",
    "address": {
      "city": "Berlin",
      "part": "Karow",
      "zipcode": "13125",
      "street": "Neustädter Str.",
      "country": "DEU",
      "coordinate": {
        "lat": 52.612056,
        "lon": 13.462841
      }
    }
  }
]

Important

The parameter country is a mandatory field for the endpoint [GET] /geocoder/autocomplete.

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