Points of Interest Details

Service version: 2
Last edit: 2023.09.29
Automtive only

Purpose

The Points of Interest (POI) Details API provides additional information about the POIs including: rating, price range, photo IDs, 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}/search/{versionNumber}/poiDetails.{ext}?key={Your_API_Key}&id={id}&sourceName={sourceName}
get
Request curl command format
curl 'https://{baseURL}/search/{versionNumber}/poiDetails.{ext}?key={Your_API_Key}&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

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 the Search response.
Value: Example: Rm91cnNxdWFyZTo1NTExYWY3MTQ5OGUwZjc4OWNkODRhZjI=

Optional parametersDescription

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: TripAdvisor.

Request headers

The following table describes HTTP request headers.

Optional headersDescription

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:

Response body with the request URL <ext> parameter value set to 'json'
1{
2 "id": "test-id",
3 "result": {
4 "description": {
5 "value": "Melkweg stands for pop culture in the most broad of senses. Each year, hundreds of concerts, club nights, films and music films, theatre performances, expositions and multidisciplinary events together attract more than 400,000 visitors. The venue is located in the only surviving factory building on the Amsterdam canal ring, a former sugar and, later, milk factory. This historical building houses two concert halls, a cinema, a theatre, and an exposition space, which each can be used separately or combined together. In the Melkweg, established names can be seen alongside new talent and emerging styles get the chance to reach a broader audience. The diversity of its programming and visitors, together with its different spaces and special location, have for years made the Melkweg a unique place.",
6 "language": "en-US"
7 },
8 "rating": {
9 "scale": {
10 "min": 0,
11 "max": 5
12 },
13 "totalRatings": 136,
14 "value": 4.5,
15 "imageId": "image-id-1"
16 },
17 "priceRange": {
18 "scaledRange": {
19 "scale": {
20 "min": 1,
21 "max": 4
22 },
23 "start": {
24 "label": "$$",
25 "value": 2
26 },
27 "end": {
28 "label": "$$$",
29 "value": 3
30 }
31 },
32 "explicitRange": {
33 "start": 100,
34 "end": 200,
35 "currency": "USD"
36 }
37 },
38 "photos": [
39 {
40 "id": "photo-id-1"
41 },
42 {
43 "id": "photo-id-2"
44 }
45 ],
46 "reviews": [
47 {
48 "text": "De Melkweg – or Milky Way – has a long reputation as a live venue and will never let you down. A must-see on your night out in Amsterdam!",
49 "date": "2022-02-16",
50 "language": "en-US"
51 },
52 {
53 "text": "Friday May 31st at Melkweg: Lovebirds Amsterdam, featuring DJ's D-Rok (NL) & Simbad (UK) with a warm mix of soul, funk, hiphop, jazz, boogie, disco and house.",
54 "date": "2022-03-05"
55 },
56 {
57 "text": "Su bedava olsun",
58 "date": "2022-11-01",
59 "language": "tr-TR"
60 },
61 {
62 "text": "Offers a program that unites five artistic disciplines under one roof: dance/theatre, film, photography, and media art.",
63 "date": "2022-01-23"
64 }
65 ]
66 }
67}

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

Response body with the request URL <ext> parameter value set to 'xml'
1<?xml version='1.0' encoding='UTF-8'?>
2<response>
3 <id>test-id</id>
4 <result>
5 <description>
6 <value>Melkweg stands for pop culture in the most broad of senses. Each year, hundreds of concerts, club nights, films and music films, theatre performances, expositions and multidisciplinary events together attract more than 400,000 visitors. The venue is located in the only surviving factory building on the Amsterdam canal ring, a former sugar and, later, milk factory. This historical building houses two concert halls, a cinema, a theatre, and an exposition space, which each can be used separately or combined together. In the Melkweg, established names can be seen alongside new talent and emerging styles get the chance to reach a broader audience. The diversity of its programming and visitors, together with its different spaces and special location, have for years made the Melkweg a unique place.</value>
7 <language>en-US</language>
8 </description>
9 <rating>
10 <scale>
11 <min>0</min>
12 <max>5</max>
13 </scale>
14 <totalRatings>136</totalRatings>
15 <value>4.5</value>
16 <imageId>image-id-1</imageId>
17 </rating>
18 <priceRange>
19 <scaledRange>
20 <scale>
21 <min>1</min>
22 <max>4</max>
23 </scale>
24 <start>
25 <label>$$</label>
26 <value>2</value>
27 </start>
28 <end>
29 <label>$$$</label>
30 <value>3</value>
31 </end>
32 </scaledRange>
33 <explicitRange>
34 <start>100</start>
35 <end>200</end>
36 <currency>USD</currency>
37 </explicitRange>
38 </priceRange>
39 <photos>
40 <photo>
41 <id>photo-id-1</id>
42 </photo>
43 <photo>
44 <id>photo-id-2</id>
45 </photo>
46 </photos>
47 <reviews>
48 <review>
49 <text>De Melkweg – or Milky Way – has a long reputation as a live venue and will never let you down. A must-see on your night out in Amsterdam!</text>
50 <date>2022-02-16</date>
51 <language>en-US</language>
52 </review>
53 <review>
54 <text>"Friday May 31st at Melkweg: Lovebirds Amsterdam, featuring DJ's D-Rok (NL) & Simbad (UK) with a warm mix of soul, funk, hiphop, jazz, boogie, disco and house."</text>
55 <date>2022-03-05</date>
56 </review>
57 <review>
58 <text>Su bedava olsun</text>
59 <date>2022-11-01</date>
60 <language>tr-TR</language>
61 </review>
62 <review>
63 <text>"Offers a program that unites five artistic disciplines under one roof: dance/theatre, film, photography, and media art."</text>
64 <date>2022-01-23</date>
65 </review>
66 </reviews>
67 </result>
68</response>

Usage of Points of Interest Details

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

  • Rich Content shall not be provided to Enterprise Customers under any circumstances.

  • Upon expiry or termination of this Agreement (or as it relates to the expiry or termination of a Commercial Agreement): (i) all of Partner’s and Customers rights regarding Rich Content shall extinguish, (ii) all use of Rich Content shall cease, and (iii) all Rich Content shall be returned or destroyed.

  • Partner shall ensure that Tripadvisor’s logos and ratings bars will be served directly from Tripadvisor URLs, and that it shall not store and/or locally serve Tripadvisor logos. Partner will make all displays of Rich Content on Partner Product non-indexable by search engines, unless otherwise agreed in a Commercial Agreement.

  • See the Branding guidelines 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
object

Description of the POI.
description object

rating
object

An object that contains rating information.
rating object

priceRange
object

An object that contains price range information.
priceRange object

photos
array

Photo ids of the POI.
array of photo objects

reviews
array

User reviews about the POI.
array of review objects

description object
FieldDescription

value
string

Description of the POI.

language
string

Language in which search results should be returned. It should be one of the TomTom supported IETF language tags , case insensitive. When data in the specified language is not available for a specific field or the language is not specified, the language best matched with your query is used.
rating object
FieldDescription

scale
object

Scale object with min/max values.
scale object

totalRatings
integer

Total number of ratings.

value
double

Rating value, between scale min and max values inclusive.

imageId
string

Id of the rating bars image. To be used in the Points of Interest Photos API. IMPORTANT: The image is a mandatory element when the rating is displayed. Displaying the rating in a different style will breach the license agreement. For more details, please relate to TripAdvisor Brand Guidelines For Partners
priceRange object
FieldDescription

scaledRange
object

Scaled range object.
scaledRange object

explicitRange
object

Explicit range object.
explicitRange object

scaledRange object
FieldDescription

scale
object

Scale object with min/max values.
scale object

start
object

Start of the scaled range.
start object within scale min/max values inclusive.

end
object

End of the scaled range.
end object within scale min/max values inclusive.

explicitRange object
FieldDescription

start
double

Start of the explicit range.

end
double

End of the explicit range.

currency
string

The currency of the price range in ISO 4217 representation. Available values: ARS, AUD, BAM, BGN, BRL, CAD, CHF, CLP, CZK, DKK, EUR, GBP, HKD, HRK, HUF, MXN, NOK, PLN, RON, RSD, RUB, SEK, TRY, TWD, USD
start, end object
FieldDescription

value
double

Value of the range.

label
string

Label of the range.
scale object
FieldDescription

min
double

'min' value of the scale.

max
double

'max' value of the scale.
photo object
FieldDescription

id
string

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

review object
FieldDescription

text
string

Content of the review.

date
string

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

language
string

Language in which search results should be returned. It should be one of the TomTom supported IETF language tags , case insensitive. When data in the specified language is not available for a specific field or the language is not specified, the language best matched with your query is used.

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>
400 Bad 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
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

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.