Points of Interest Details
Service version: 2
Last edit: 2020.08.27
On this page
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, and user reviews.
Request data
HTTPS methods: GETHEAD
URL format
For ease of viewing and identification:
- Constants and parameters enclosed in angle brackets (< >) must be replaced with their values.
- See the following Request parameters section with the Required and Optional parameters tables for these values.
https://<baseURL>/search/<versionNumber>/poiDetails.<ext>?key=<Your_API_Key>&id=<id>
curl command format
curl 'https://<baseURL>/search/<versionNumber>/poiDetails.<ext>?key=<Your_API_Key>&id=<id>'
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 parameters | |
---|---|
Parameter | Description |
baseURL string |
The base URL for calling the API. Value: api.tomtom.com
|
versionNumber string |
The service version. Value: The current value is 2 .
|
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 Search Response. Value: Example: Rm91cnNxdWFyZTo1NTExYWY3MTQ5OGUwZjc4OWNkODRhZjI=
|
Optional parameters | |
Note: There are no optional parameters in this endpoint. |
HTTP Request headers
The following table describes HTTP Request headers.
Optional headers | |
---|---|
Header | Description |
Accept-Encoding string |
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 string |
Specifies an identifier for the Request.
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:
{
"id": "Rm91cnNxdWFyZTo1NTExYWY3MTQ5OGUwZjc4OWNkODRhZjI=",
"result": {
"description": "Award winning restaurant founded by the De Visscher family.",
"rating": {
"totalRatings": 214,
"value": 8.84,
"minValue": 0,
"maxValue": 10
},
"priceRange": {
"label": "Moderate",
"value": 2,
"minValue": 1,
"maxValue": 4
},
"socialMedia": [
{
"name": "facebook",
"url": "https://facebook.com/profile.php?id=564078493731401"
}
],
"photos": [
{
"id": "23bc3b0b-d33d-3c07-8612-e660ea7c0864"
},
{
"id": "df424a18-8710-3f85-952f-5528ed9b3e46"
},
{
"id": "9a27ffba-c7b6-3d15-9334-417a3281a6c0"
},
{
"id": "6b49c97b-da5c-3dc3-b802-aa83e14337e7"
},
{
"id": "1dd59289-87f2-30e0-bd32-e4f08775889f"
}
],
"reviews": [
{
"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",
"date": "2020-02-23"
},
{
"text": "fresh oysters, square lobster soup",
"date": "2020-01-08"
},
{
"text": "My favorite in Amsterdam!",
"date": "2020-01-01"
},
{
"text": "Oysters are delicious, catch of the day dish was very good! Soup is tasty, but could be better. Be careful with the price.",
"date": "2016-05-31"
},
{
"text": "Прекрасный ресторан с морепродуктами! Если соберетесь туда вечером - забронируйте заранее столик у них на сайте.",
"date": "2015-03-29"
}
],
"popularHours": [
{
"dayOfWeek": 1,
"timeRanges": [
{
"startTime": {
"hour": 12,
"minute": 0
},
"endTime": {
"hour": 16,
"minute": 0
}
}
]
},
{
"dayOfWeek": 2,
"timeRanges": [
{
"startTime": {
"hour": 12,
"minute": 0
},
"endTime": {
"hour": 14,
"minute": 0
}
}
]
},
{
"dayOfWeek": 3,
"timeRanges": [
{
"startTime": {
"hour": "12",
"minute": 0
},
"endTime": {
"hour": "14",
"minute": 0
}
}
]
},
{
"dayOfWeek": 4,
"timeRange": [
{
"startTime": {
"hour": 12,
"minute": 0
},
"endTime": {
"hour": 14,
"minute": 0
}
}
]
},
{
"dayOfWeek": 5,
"timeRange": [
{
"startTime": {
"hour": 12,
"minute": 0
},
"endTime": {
"hour": 14,
"minute": 0
}
},
{
"startTime": {
"hour": 17,
"minute": 0
},
"endTime": {
"hour": 19,
"minute": 0
}
},
{
"startTime": {
"hour": 21,
"minute": 0
},
"endTime": {
"hour": 2,
"minute": 0
}
}
]
},
{
"dayOfWeek": 6,
"timeRanges": [
{
"startTime": {
"hour": 18,
"minute": 0
},
"endTime": {
"hour": 3,
"minute": 0
}
}
]
}
]
}
}
If the <ext>
parameter value is set to .xml
, the Response will be a XML format with the following structure:
<response>
<id>Rm91cnNxdWFyZTo1NTExYWY3MTQ5OGUwZjc4OWNkODRhZjI=</id>
<result>
<description>Award winning restaurant founded by the De Visscher family.</description>
<rating>
<totalRatings>214</totalRatings>
<value>8.84</value>
<minValue>0</minValue>
<maxValue>10</maxValue>
</rating>
<priceRange>
<label>Moderate</label>
<value>2</value>
<minValue>1</minValue>
<maxValue>4</maxValue>
</priceRange>
<socialMedia>
<media>
<name>facebook</text>
<url>https://facebook.com/profile.php?id=564078493731401</date>
</media>
</socialMedia>
<photos>
<photo>
<id>23bc3b0b-d33d-3c07-8612-e660ea7c0864</id>
</photo>
<photo>
<id>df424a18-8710-3f85-952f-5528ed9b3e46</id>
</photo>
<photo>
<id>9a27ffba-c7b6-3d15-9334-417a3281a6c0</id>
</photo>
<photo>
<id>6b49c97b-da5c-3dc3-b802-aa83e14337e7</id>
</photo>
<photo>
<id>1dd59289-87f2-30e0-bd32-e4f08775889f</id>
</photo>
</photos>
<reviews>
<review>
<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>
<date>2020-02-23</date>
</review>
<review>
<text>fresh oysters, square lobster soup</text>
<date>2020-01-08</date>
</review>
<review>
<text>My favorite in Amsterdam!</text>
<date>2020-01-01</date>
</review>
<review>
<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>
<date>2016-05-31</date>
</review>
<review>
<text>Прекрасный ресторан с морепродуктами! Если соберетесь туда вечером - забронируйте заранее столик у них на сайте.</text>
<date>2015-03-29</date>
</review>
</reviews>
<popularHours>
<hours>
<dayOfWeek>1</dayOfWeek>
<timeRanges>
<timeRange>
<startTime>
<hour>12</hour>
<minute>0</minute>
</startTime>
<endTime>
<hour>16</hour>
<minute>0</minute>
</endTime>
</timeRange>
</timeRanges>
</hours>
<hours>
<dayOfWeek>2</dayOfWeek>
<timeRanges>
<timeRange>
<startTime>
<hour>12</hour>
<minute>0</minute>
</startTime>
<endTime>
<hour>14</hour>
<minute>0</minute>
</endTime>
</timeRange>
</timeRanges>
</hours>
<hours>
<dayOfWeek>3</dayOfWeek>
<timeRanges>
<timeRange>
<startTime>
<hour>12</hour>
<minute>0</minute>
</startTime>
<endTime>
<hour>14</hour>
<minute>0</minute>
</endTime>
</timeRange>
</timeRanges>
</hours>
<hours>
<dayOfWeek>4</dayOfWeek>
<timeRanges>
<timeRange>
<startTime>
<hour>12</hour>
<minute>0</minute>
</startTime>
<endTime>
<hour>14</hour>
<minute>0</minute>
</endTime>
</timeRange>
</timeRanges>
</hours>
<hours>
<dayOfWeek>5</dayOfWeek>
<timeRanges>
<timeRange>
<startTime>
<hour>12</hour>
<minute>0</minute>
</startTime>
<endTime>
<hour>14</hour>
<minute>0</minute>
</endTime>
</timeRange>
<timeRange>
<startTime>
<hour>17</hour>
<minute>0</minute>
</startTime>
<endTime>
<hour>19</hour>
<minute>0</minute>
</endTime>
</timeRange>
<timeRange>
<startTime>
<hour>21</hour>
<minute>0</minute>
</startTime>
<endTime>
<hour>2</hour>
<minute>0</minute>
</endTime>
</timeRange>
</timeRanges>
</hours>
<hours>
<dayOfWeek>6</dayOfWeek>
<timeRanges>
<timeRange>
<startTime>
<hour>18</hour>
<minute>0</minute>
</startTime>
<endTime>
<hour>3</hour>
<minute>0</minute>
</endTime>
</timeRange>
</timeRanges>
</hours>
</popularHours>
</result>
</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.
Response | |
---|---|
Field | Description |
id string |
The ID of the returned entity. |
result object |
An object that contains the result of the Request.result{} object
|
result{} object |
|
Field | Description |
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.array of media{} objects
|
photos[] array |
Photo ids of the POI.array of photo{} objects
|
reviews[] array |
User reviews about the POI.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.array of hours{} objects
|
rating{} object |
|
Field | Description |
totalRatings integer |
Total number of ratings. |
value double |
Rating value, between min/max values inclusive. |
minValue double |
Min value of the rating. |
maxValue double |
Max value of the rating. |
priceRange{} object |
|
Field | Description |
value integer |
Price range value, between min/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 |
|
Field | Description |
name string |
Name of the social media. |
url string |
Link to the social media. |
photo{} object |
|
Field | Description |
id string |
Id of the photo. To be used in the Points of Interest Photos API. |
review{} object |
|
Field | Description |
text string |
Content of the review. |
date string |
Date of the review, YYYY-MM-DD format ISO_8601 |
hours{} object |
|
Field | Description |
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.array of timeRange{} objects
|
timeRange{} object |
|
Field | Description |
startTime object |
Start of the time range.startTime{} object
|
endTime object |
End of the time range.endTime{} object
|
startTime{}, endTime{} object |
|
Field | Description |
hour integer |
Hours are in the 24 hour format in the local time of the POI.0..23
|
minute integer |
Minutes are in the local time of the POI.0..59
|
HTTP Response codes
Code | Meaning and 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 in the Response body. For example:
JSON
XML
|
400 |
Bad request: one or more parameters were incorrectly specified or are out of range. |
403 |
Forbidden: Possible causes include:
|
404 |
Not Found: The requested resource could not be found, but it may be available again in the future. |
405 |
Method Not Allowed. |
429 |
Too Many Requests: The API Key is over QPS (Queries per second). |
5xx |
Server Error: The service was unable to process your Request. Contact support to resolve the issue. |
Response headers
Header | Description |
---|---|
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.
no-cache
|
Content-Type |
Indicates the format of the Response as chosen by the client. Format: type/subtype; charset=utf-8 Value: type/subtype:
|
Tracking-ID |
An identifier for the Request.
An identifier for the Request.
|
Error Response
The error Response content type depends on the ext
parameter.
Error Response example (JSON)
{
"message":"Missing parameter 'parameterName'",
"detailedError":{
"code":"MissingParameter",
"message":"Missing required parameter 'parameterName'.",
},
"httpStatusCode":"400"
}
Error Response example (XML)
<ErrorEvResponse>
<message>Missing parameter 'parameterName'</message>
<detailedError>
<code>MissingParameter</code>
<message>Missing required parameter 'parameterName'.</message>
</detailedError>
</ErrorEvResponse>
Error Response fields
Primary fields | |
---|---|
Field | Description |
message string |
A human-readable description of the error. |
detailedError object |
Detailed information about the error.detailedError{} object
|
detailedError{} object |
|
Field | Description |
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. |