Developer

Region-specific content

Last edit: 2022.11.14

Some parts of TomTom data are subject to additional legal terms and conditions. When used, the customer must agree to and follow these additional conditions. Also, for some regions our APIs can have differences in requests and responses compared to the default API behavior. Customers should be aware of these differences before using the region-specific content.

Available region-specific contents

Hostname

Description

kr-api.tomtom.com

  • Hostname, where detailed South Korea data is available.

  • Detailed South Korean data is processed and hosted in South Korea.

    • It may impact the latency for requests sent from outside of South Korea.

  • The service customers are not allowed to download, store, cache nor host the South Korean data outside of South Korea (except for web browser cache).

  • The service customers are not allowed to display any coordinates of any place within South Korea.

  • Response data for South Korea can have additional response data.

Region-specific API changes

Response data for South Korea

South Korea switched from a land lot-based addressing format to a street name-based format in 2011. The old format is still widely used and therefore supported by the Search API, which means both address formats can be found and returned by various Search APIs (geocode, search, and reverse geocode).

Changes to the API response only apply to results of type Point Address. The Search API supports Point Address results with

  1. only a street name-based address
  2. both a street name-based address and a land lot-based address
Example response for a point in South Korea - JSON
1{
2  "summary": {
3    "queryTime": 3,
4    "numResults": 1
5  },
6  "addresses": [
7    {
8      "address": {.. 16 Items ..},
9      "linkedAddress": {
10        "routeNumbers": [],
11        "street": "석산로119번길",
12        "streetName": "석산로119번길",
13        "countryCode": "KR",
14        "countrySubdivision": "경기도",
15        "municipality": "양평군",
16        "postalCode": "12528",
17        "municipalitySubdivision": "단월면",
18        "country": "대한민국",
19        "countryCodeISO3": "KOR",
20        "freeformAddress": "12528 경기도 양평군 단월면 향소리 167-3",
21        "boundingBox": {
22          "northEast": "37.561549,127.661349",
23          "southWest": "37.561467,127.661073",
24          "entity": "position"
25        },
26      "localName": "단월면",
27      "dependentLocalName": "향소리",
28      "landCode": "167-3"
29    },
30    "position": "37.561466,127.661072"
31    }
32  ]
33}

Street name-based address only

For a Point Address with only a street name-based address, the API response is identical to the default API response.

Example response for the result of the Point Address type is in the following format:

Point Address type example response - JSON
1{
2  "summary": {
3    "queryTime": 17,
4    "numResults": 1
5  },
6  "addresses": [
7    {
8      "address": {
9        "buildingNumber": "2501",
10        "streetNumber": "2501",
11        "routeNumbers": [],
12        "street": "Soquel Drive",
13        "streetName": "Soquel Drive",
14        "streetNameAndNumber": "2501 Soquel Drive",
15        "speedLimit": "35.00MPH",
16        "countryCode": "US",
17        "countrySubdivision": "CA",
18        "countrySecondarySubdivision": "Santa Cruz",
19        "municipality": "Santa Cruz",
20        "postalCode": "95065",
21        "municipalitySubdivision": "Santa Cruz, Live Oak",
22        "sideOfStreet": "L",
23        "offsetPosition": "36.988430,-121.974731",
24        "country": "United States",
25        "countryCodeISO3": "USA",
26        "freeformAddress": "2501 Soquel Drive, Santa Cruz, CA 95065",
27        "boundingBox": {
28          "northEast": "36.988197,-121.974752",
29          "southWest": "36.988156,-121.975108",
30          "entity": "position"
31        },
32        "extendedPostalCode": "950651900",
33        "countrySubdivisionName": "California",
34        "localName": "Santa Cruz"
35      },
36      "position": "36.988159,-121.974762",
37      "roadUse": [
38        "Arterial"
39      ],
40      "matchType": "AddressPoint",
41      "mapcodes":[
42        {
43          "type":"Local",
44          "fullMapcode":"US-CA FS.WRH3",
45          "territory":"US-CA",
46          "code":"FS.WRH3"
47        },
48        {
49          "type":"International",
50          "fullMapcode":"S4ZW4.990V"
51        },
52        {
53          "type":"Alternative",
54          "fullMapcode":"US-CA 4349.S8W",
55          "territory":"US-CA",
56          "code":"4349.S8W"
57        },
58        {
59          "type":"Alternative",
60          "fullMapcode":"US-CA JJCH.H9DF",
61          "territory":"US-CA",
62          "code":"JJCH.H9DF"
63        },
64        {
65          "type":"Alternative",
66          "fullMapcode":"USA JJCH.H9DF",
67          "territory":"USA",
68          "code":"JJCH.H9DF"
69        }
70      ]
71    }
72  ]
73}

Both address formats

Most street name-based addresses have a matching land lot-based address linked to it. To support this dual-addressing scheme, the API response contains the address field, as well as an additional field linkedAddress. The address field contains the street name-based address, while the region-specific linkedAddress field contains the land lot-based address. The linkedAddress response object mostly follows the default address object, except for the addition of the following two fields.

FieldDescription

landCode
string

Land-lot number.

dependentLocalName
string

Neighborhood ( dong ).

A Point Address element in the results array with both address formats present is represented in JSON as follows:

Response structure - JSON
1{
2  "summary": {
3    "queryTime": 102,
4    "numResults": 1
5  },
6  "addresses": []
7}

Example response for the Geography result with entityType=PostalCodeArea filtering:

Geography example response - JSON
1{
2  "summary": {
3    "queryTime": 10,
4    "numResults": 1
5  },
6  "addresses": [
7    {
8      "address": {
9        "routeNumbers": [],
10        "countryCode": "US",
11        "countrySubdivision": "CA",
12        "countrySecondarySubdivision": "Santa Cruz",
13        "municipality": "Santa Cruz",
14        "postalName": "Santa Cruz",
15        "postalCode": "95065",
16        "country": "United States",
17        "countryCodeISO3": "USA",
18        "freeformAddress": "Santa Cruz, CA 95065",
19        "boundingBox": {
20          "northEast": "37.085762,-121.949375",
21          "southWest": "36.983408,-122.013236",
22          "entity": "position"
23        },
24        "countrySubdivisionName": "California"
25      },
26      "position": "36.988171,-121.974876",
27      "dataSources": {
28        "geometry": {
29          "id": "00005543-3300-3c00-0000-00004dc8b8e5"
30        }
31      },
32      "entityType": "PostalCodeArea",
33      "mapcodes":[
34        {
35          "type":"Local",
36          "fullMapcode":"US-CA FS.WRG0",
37          "territory":"US-CA",
38          "code":"FS.WRG0"
39        },
40        {
41          "type":"International",
42          "fullMapcode":"S4ZW4.89XV"
43        },
44        {
45          "type":"Alternative",
46          "fullMapcode":"US-CA 4349.S7L",
47          "territory":"US-CA",
48          "code":"4349.S7L"
49        },
50        {
51          "type":"Alternative",
52          "fullMapcode":"US-CA JJCH.H9CF",
53          "territory":"US-CA",
54          "code":"JJCH.H9CF"
55        },
56        {
57          "type":"Alternative",
58          "fullMapcode":"USA JJCH.H9CF",
59          "territory":"USA",
60          "code":"JJCH.H9CF"
61        }
62      ]
63    }
64  ]
65}