Developer

Points of Interest Details

Service version: 1
Last edit: 2024.11.28
TomTom Orbis Maps
PUBLIC PREVIEW

Public Preview Notice

Important notes:

  • This TomTom Orbis Maps Search API document collection is in Public Preview. Go to the Public Preview - what is it? page to see what this means.
  • This API is powered by TomTom Orbis Maps.
  • See the TomTom Orbis Maps documentation for more information.

This API will be discontinued as of the 24th of June 2022.

Purpose

The Points of Interest (POI) Details endpoint provides additional information about the POIs including: rating, price range, social media links (Facebook, Instagram, Twitter), photo IDs, popular hours, and user reviews.

Request data

HTTPS methods: GET HEAD

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.
get
Request URL format
https://{baseURL}/maps/orbis/places/poiDetails.{ext}?key={Your_API_Key}&apiVersion={apiVersion}&id={id}&sourceName={sourceName}
get
Request curl command format
curl 'https://{baseURL}/maps/orbis/places/poiDetails.{ext}?key={Your_API_Key}&apiVersion={apiVersion}&id={id}&sourceName={sourceName}'

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.
  • Parameters and values are case-sensitive.
Required parametersDescription

baseURL
string

The base URL for calling the API.
Value: api.tomtom.com

ext
string

The response format of the API request. The valid response format is JSON or XML.
Value: json or xml

key
string

An API Key valid for the requested service.
Value: Your valid API Key.

id
string

POI id, previously retrieved from the poiDetails section at the bottom of the Search response.
Value: Example: Rm91cnNxdWFyZTo1NTExYWY3MTQ5OGUwZjc4OWNkODRhZjI=

Optional parametersDescription

apiVersion
string

Service version. If the TomTom-Api-Version header is not present the apiVersion parameter is required.
Value: A service version value. The current value is 1.

sourceName
string

Name of an external data provider. This parameter is required only for MultiNet-R customers. Customers using the Search API should not include this parameter in the request.
Value: Example: Foursquare.

Request headers

The following table describes HTTP request headers.

Optional headersDescription
TomTom-Api-Version

Service version. If the apiVersion parameter is not present the TomTom-Api-Version header is required.
Value: A service version value. The current value is 1.

Accept-Encoding

Should contain a list of encodings acceptable by the client. Used to demand a compressed response.
If specified, the Content-Encoding response header is returned.
Value: gzip

Tracking-ID

Specifies an identifier for the request.

  • It can be used to trace a call.
  • The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'.
  • An example of the format that matches this regular expression is UUID (e.g., 9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1).
  • For details check RFC 4122.
  • If specified, it is replicated in the Tracking-ID response header.
  • 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.

Response data

Response body

If the <ext> parameter value is set to json, the response will be a JSON object with the following structure.

Note: Use the following expand/collapse section to view this response.

Response body with the request URL <ext> parameter value set to 'json'
1{
2  "id": "Rm91cnNxdWFyZTo1NTExYWY3MTQ5OGUwZjc4OWNkODRhZjI=",
3  "result": {
4    "description": "Award winning restaurant founded by the De Visscher family.",
5    "rating": {
6      "totalRatings": 214,
7      "value": 8.84,
8      "minValue": 0,
9      "maxValue": 10
10    },
11    "priceRange": {
12      "label": "Moderate",
13      "value": 2,
14      "minValue": 1,
15      "maxValue": 4
16    },
17    "socialMedia": [
18      {
19        "name": "facebook",
20        "url": "https://facebook.com/profile.php?id=564078493731401"
21      }
22    ],
23    "photos": [
24      {
25        "id": "23bc3b0b-d33d-3c07-8612-e660ea7c0864"
26      },
27      {
28        "id": "df424a18-8710-3f85-952f-5528ed9b3e46"
29      },
30      {
31        "id": "9a27ffba-c7b6-3d15-9334-417a3281a6c0"
32      },
33      {
34        "id": "6b49c97b-da5c-3dc3-b802-aa83e14337e7"
35      },
36      {
37        "id": "1dd59289-87f2-30e0-bd32-e4f08775889f"
38      }
39    ],
40    "reviews": [
41      {
42        "text": "Finger foods bölümündeki kalamar ve ahtapot çok lezzetli, günün balığı olarak da ızgara çupra seçtik o da lezzetli, bu menü 2 kişi için ideal. Beyaz şarap olarak chardonnay seçtik italyan, o da iyiydi",
43        "date": "2020-02-23"
44      },
45      {
46        "text": "fresh oysters, square lobster soup",
47        "date": "2020-01-08"
48      },
49      {
50        "text": "My favorite in Amsterdam!",
51        "date": "2020-01-01"
52      },
53      {
54        "text": "Oysters are delicious, catch of the day dish was very good! Soup is tasty, but could be better. Be careful with the price.",
55        "date": "2016-05-31"
56      },
57      {
58        "text": "Прекрасный ресторан с морепродуктами! Если соберетесь туда вечером - забронируйте заранее столик у них на сайте.",
59        "date": "2015-03-29"
60      }
61    ],
62    "popularHours": [
63      {
64        "dayOfWeek": 1,
65        "timeRanges": [
66          {
67            "startTime": {
68              "hour": 12,
69              "minute": 0
70            },
71            "endTime": {
72              "hour": 16,
73              "minute": 0
74            }
75          }
76        ]
77      },
78      {
79        "dayOfWeek": 2,
80        "timeRanges": [
81          {
82            "startTime": {
83              "hour": 12,
84              "minute": 0
85            },
86            "endTime": {
87              "hour": 14,
88              "minute": 0
89            }
90          }
91        ]
92      },
93      {
94        "dayOfWeek": 3,
95        "timeRanges": [
96          {
97            "startTime": {
98              "hour": "12",
99              "minute": 0
100            },
101            "endTime": {
102              "hour": "14",
103              "minute": 0
104            }
105          }
106        ]
107      },
108      {
109        "dayOfWeek": 4,
110        "timeRange": [
111          {
112            "startTime": {
113              "hour": 12,
114              "minute": 0
115            },
116            "endTime": {
117              "hour": 14,
118              "minute": 0
119            }
120          }
121        ]
122      },
123      {
124        "dayOfWeek": 5,
125        "timeRange": [
126          {
127            "startTime": {
128              "hour": 12,
129              "minute": 0
130            },
131            "endTime": {
132              "hour": 14,
133              "minute": 0
134            }
135          },
136          {
137            "startTime": {
138              "hour": 17,
139              "minute": 0
140            },
141            "endTime": {
142              "hour": 19,
143              "minute": 0
144            }
145          },
146          {
147            "startTime": {
148              "hour": 21,
149              "minute": 0
150            },
151            "endTime": {
152              "hour": 2,
153              "minute": 0
154            }
155          }
156        ]
157      },
158      {
159        "dayOfWeek": 6,
160        "timeRanges": [
161          {
162            "startTime": {
163              "hour": 18,
164              "minute": 0
165            },
166            "endTime": {
167              "hour": 3,
168              "minute": 0
169            }
170          }
171        ]
172      }
173    ]
174  }
175}

If the <ext> parameter value is set to xml, the response will be an XML format with the following structure.

Note: Use the following expand/collapse section to view this response.

Response body with the request URL <ext> parameter value set to 'xml'
1<?xml version="1.0" encoding="UTF-8"?>
2<response>
3  <id>Rm91cnNxdWFyZTo1NTExYWY3MTQ5OGUwZjc4OWNkODRhZjI=</id>
4  <result>
5    <description>Award winning restaurant founded by the De Visscher family.</description>
6    <rating>
7      <totalRatings>214</totalRatings>
8      <value>8.84</value>
9      <minValue>0</minValue>
10      <maxValue>10</maxValue>
11    </rating>
12    <priceRange>
13      <label>Moderate</label>
14      <value>2</value>
15      <minValue>1</minValue>
16      <maxValue>4</maxValue>
17    </priceRange>
18    <socialMedia>
19      <media>
20        <name>facebook</name>
21        <url>https://facebook.com/profile.php?id=564078493731401</url>
22      </media>
23    </socialMedia>
24    <photos>
25      <photo>
26        <id>23bc3b0b-d33d-3c07-8612-e660ea7c0864</id>
27      </photo>
28      <photo>
29        <id>df424a18-8710-3f85-952f-5528ed9b3e46</id>
30      </photo>
31      <photo>
32        <id>9a27ffba-c7b6-3d15-9334-417a3281a6c0</id>
33      </photo>
34      <photo>
35        <id>6b49c97b-da5c-3dc3-b802-aa83e14337e7</id>
36      </photo>
37      <photo>
38        <id>1dd59289-87f2-30e0-bd32-e4f08775889f</id>
39      </photo>
40    </photos>
41    <reviews>
42      <review>
43        <text>Finger foods bölümündeki kalamar ve ahtapot çok lezzetli, günün balığı olarak da ızgara çupra seçtik o da lezzetli, bu menü 2 kişi için ideal. Beyaz şarap olarak chardonnay seçtik italyan, o da iyiydi</text>
44        <date>2020-02-23</date>
45      </review>
46      <review>
47        <text>fresh oysters, square lobster soup</text>
48        <date>2020-01-08</date>
49      </review>
50      <review>
51        <text>My favorite in Amsterdam!</text>
52        <date>2020-01-01</date>
53      </review>
54      <review>
55        <text>Oysters are delicious, catch of the day dish was very good! Soup is tasty, but could be better. Be careful with the price.</text>
56        <date>2016-05-31</date>
57      </review>
58      <review>
59        <text>Прекрасный ресторан с морепродуктами! Если соберетесь туда вечером - забронируйте заранее столик у них на сайте.</text>
60        <date>2015-03-29</date>
61      </review>
62    </reviews>
63    <popularHours>
64      <hours>
65        <dayOfWeek>1</dayOfWeek>
66        <timeRanges>
67          <timeRange>
68            <startTime>
69              <hour>12</hour>
70              <minute>0</minute>
71            </startTime>
72            <endTime>
73              <hour>16</hour>
74              <minute>0</minute>
75            </endTime>
76          </timeRange>
77        </timeRanges>
78      </hours>
79      <hours>
80        <dayOfWeek>2</dayOfWeek>
81        <timeRanges>
82          <timeRange>
83            <startTime>
84              <hour>12</hour>
85              <minute>0</minute>
86            </startTime>
87            <endTime>
88              <hour>14</hour>
89              <minute>0</minute>
90            </endTime>
91          </timeRange>
92        </timeRanges>
93      </hours>
94      <hours>
95        <dayOfWeek>3</dayOfWeek>
96        <timeRanges>
97          <timeRange>
98            <startTime>
99              <hour>12</hour>
100              <minute>0</minute>
101            </startTime>
102            <endTime>
103              <hour>14</hour>
104              <minute>0</minute>
105            </endTime>
106          </timeRange>
107        </timeRanges>
108      </hours>
109      <hours>
110        <dayOfWeek>4</dayOfWeek>
111        <timeRanges>
112          <timeRange>
113            <startTime>
114              <hour>12</hour>
115              <minute>0</minute>
116            </startTime>
117            <endTime>
118              <hour>14</hour>
119              <minute>0</minute>
120            </endTime>
121          </timeRange>
122        </timeRanges>
123      </hours>
124      <hours>
125        <dayOfWeek>5</dayOfWeek>
126        <timeRanges>
127          <timeRange>
128            <startTime>
129              <hour>12</hour>
130              <minute>0</minute>
131            </startTime>
132            <endTime>
133              <hour>14</hour>
134              <minute>0</minute>
135            </endTime>
136          </timeRange>
137          <timeRange>
138            <startTime>
139              <hour>17</hour>
140              <minute>0</minute>
141            </startTime>
142            <endTime>
143              <hour>19</hour>
144              <minute>0</minute>
145            </endTime>
146          </timeRange>
147          <timeRange>
148            <startTime>
149              <hour>21</hour>
150              <minute>0</minute>
151            </startTime>
152            <endTime>
153              <hour>2</hour>
154              <minute>0</minute>
155            </endTime>
156          </timeRange>
157        </timeRanges>
158      </hours>
159      <hours>
160        <dayOfWeek>6</dayOfWeek>
161        <timeRanges>
162          <timeRange>
163            <startTime>
164              <hour>18</hour>
165              <minute>0</minute>
166            </startTime>
167            <endTime>
168              <hour>3</hour>
169              <minute>0</minute>
170            </endTime>
171          </timeRange>
172        </timeRanges>
173      </hours>
174    </popularHours>
175  </result>
176</response>

Usage of Points of Interest Details

With respect to the Points of Interest Details endpoint, the following applies:

  • You shall attribute all results delivered by the Extended Search API Points of Interest Details endpoint and Points of Interest Photos endpoint as being "powered by Foursquare".

  • You shall not use any results delivered by the Extended Search API Points of Interest Details endpoint and Points of Interest Photos endpoint to create, improve, or edit a venue or point of interest database.

  • You shall not cache any results delivered by the Extended Search API Points of Interest Details endpoint and Points of Interest Photos endpoint for more than 30 days.

  • See the Terms and Conditions for more details.

Response fields

The following table describes 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

id
string

The ID of the returned entity.

result
object

An object that contains the result of the request.
result object

result object
FieldDescription

description
string

Description of the POI.

rating
object

An object that contains rating information.
rating object

priceRange
object

An object that contains price range information.
priceRange object

socialMedia
array

Social media links of the POI.
An array of media objects

photos
array

Photo ids of the POI.
An array of photo objects

reviews
array

User reviews about the POI.
An array of review objects

popularHours
array

List of popular hours of the week when people typically visit a POI. The time is represented by the local time of the POI (timezone is available in the Search API response).
An array of hours objects

rating object
FieldDescription

totalRatings
integer

Total number of ratings.

value
double

Rating value, between min and max values inclusive.

minValue
double

Min value of the rating.

maxValue
double

Max value of the rating.
priceRange object
FieldDescription

value
integer

Price range value, between min and max values inclusive.

label
string

Label which describes the price range, for example: Cheap, Moderate, Expensive, Very Expensive. Values might differ per data provider.

minValue
integer

Min value of the price range.

maxValue
integer

Max value of the price range.
media object
FieldDescription

name
string

Name of the social media.

url
string

Link to the social media.
photo object
FieldDescription

id
string

Id of the photo. To be used in the Points of Interest Photos endpoint.

review object
FieldDescription

text
string

Content of the review.

date
string

Date of the review, YYYY-MM-DD format ISO_8601

hours object
FieldDescription

dayOfWeek
integer

A number from 1 to 7, corresponding to the days of the week, starting from Monday, ISO_8601 format. For example, 4 means Thursday.

timeRanges
array

List of the popular hours time ranges.
An array of timeRange objects

timeRange object
FieldDescription

startTime
object

Start of the time range.
startTime object

endTime
object

End of the time range.
endTime object

startTime, endTime objects
FieldDescription

hour
integer

Hours are in the 24 hour format in the local time of the POI.
Values: 0..23

minute
integer

Minutes are in the local time of the POI.
Values: 0..59

Response codes

CodeMeaning & possible causes
200

OK: If the given POI was found, the body of the response will contain the data. Otherwise, the response will contain an empty result object/empty <result></result> result element in the response body. For example:

Code 200 response body - JSON
1{
2  "id": "Rm91cnNxdWFyZTo0YTI3MDNjOGY5NjRhNTIwNjY4NTFmZTM=",
3  "result": {}
4}
Code 200 response body - XML
1<response>
2  <id>Rm91cnNxdWFyZTo0YTI3MDNjOGY5NjRhNTIwNjY4NTFmZTM=</id>
3  <result></result>
4</response>
400Bad request: one or more parameters were incorrectly specified or are out of range.
403

Forbidden: Possible causes include:

  • Service requires SSL
  • Not authorized
  • Rate or volume limit exceeded
  • Unknown referer
404Not Found: The requested resource could not be found, but it may be available again in the future.
405Method Not Allowed: The HTTP method (GET, POST, etc.) is not supported for this request.
429Too Many Requests: The API Key is over QPS (Queries per second).
5xxServer Error: The service was unable to process your request. Contact support to resolve the issue.

Response headers

HeaderDescription
Access-Control-Allow-Origin

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

Content-Encoding

The service applies gzip compression to the responses if it is requested by the client with the Accept-Encoding header.
Value: gzip

Cache-Control

The Cache-Control general-header field is used to specify directives that must be obeyed by all caching mechanisms along the request/response chain.

  • Supported by HTTP/1.1 clients.
  • May not be supported by HTTP/1.0 clients.

Value: no-cache

Content-Type

Indicates the format of the response as chosen by the client. Format: type/subtype; charset=utf-8
Value: type/subtype:

  • application/json

  • application/xml

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

The error response content type depends on the ext parameter.

Response body with the request URL <ext> parameter value set to "json"
1{
2  "message": "Missing parameter 'parameterName'",
3  "detailedError": {
4    "code": "MissingParameter",
5    "message": "Missing required parameter 'parameterName'."
6  },
7  "httpStatusCode": "400"
8}
Response body with the request URL <ext> parameter value set to "xml"
1<ErrorEvResponse>
2  <message>Missing parameter 'parameterName'</message>
3  <detailedError>
4    <code>MissingParameter</code>
5    <message>Missing required parameter 'parameterName'.</message>
6  </detailedError>
7</ErrorEvResponse>

Error response fields

Primary fieldsDescription

message
string

A human-readable description of the error.

detailedError
object

Detailed information about the error.
detailedError object

detailedError object
FieldDescription

code
string

One of a server-defined set of error codes.

message
string

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