Points of Interest Details
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.
https://{baseURL}/search/{versionNumber}/poiDetails.{ext}?key={Your_API_Key}&id={id}&sourceName={sourceName}
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 parameters | Description |
---|---|
| The base URL for calling the API. |
| The service version. |
| The response format of the API request. The valid response format is
JSON or XML. |
| An API Key valid for the requested service. |
| POI id, previously retrieved from the poiDetails section at the bottom
of the
Search response. |
Optional parameters | Description |
---|---|
| 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. |
Request headers
The following table describes HTTP request headers.
Optional headers | Description |
---|---|
Should contain a list of encodings acceptable by the client. Used to
demand a compressed response. | |
Tracking-ID | Specifies an identifier for the request. It can be used to trace a call.
The value must match the regular expression
|
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": 512 },13 "totalRatings": 136,14 "value": 4.5,15 "imageId": "image-id-1"16 },17 "priceRange": {18 "scaledRange": {19 "scale": {20 "min": 1,21 "max": 422 },23 "start": {24 "label": "$$",25 "value": 226 },27 "end": {28 "label": "$$$",29 "value": 330 }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 | |
---|---|
Field | Description |
| The ID of the returned entity. |
| An object that contains the result of the request. |
result object | |
Field | Description |
| Description of the POI. |
| An object that contains rating information. |
| An object that contains price range information. |
| Photo ids of the POI. |
| User reviews about the POI. |
description object | |
Field | Description |
| Description of the POI. |
| 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 | |
Field | Description |
| Scale object with min/max values. |
| Total number of ratings. |
| Rating value, between scale min and max values inclusive. |
| 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 | |
Field | Description |
| Scaled range object. |
| Explicit range object. |
scaledRange object | |
Field | Description |
| Scale object with min/max values. |
| Start of the scaled range. |
| End of the scaled range. |
explicitRange object | |
Field | Description |
| Start of the explicit range. |
| End of the explicit range. |
| 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 | |
Field | Description |
| Value of the range. |
| Label of the range. |
scale object | |
Field | Description |
| 'min' value of the scale. |
| 'max' value of the scale. |
photo object | |
Field | Description |
| Id of the photo. To be used in the Points of Interest Photos API. |
review object | |
Field | Description |
| Content of the review. |
| Date of the review, YYYY-MM-DD format ISO_8601 |
| 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
Code | Meaning & possible causes |
---|---|
200 | OK : If the given Code 200 response body - JSON
Code 200 response body - 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 |
---|---|
Ensures that clients implementing the CORS security model are able to
access the response from this service. | |
The service applies gzip compression to the responses if it is requested
by the client with the Accept-Encoding header. | |
The Cache-Control general-header field is used to specify directives that must be obeyed by all caching mechanisms along the request/response chain.
Value: | |
Indicates the format of the response as chosen by the client. Format:
| |
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. |
Error response
The error response content type depends on the ext
parameter.
1{2 "message": "Missing parameter 'parameterName'",3 "detailedError": {4 "code": "MissingParameter",5 "message": "Missing required parameter 'parameterName'."6 },7 "httpStatusCode": "400"8}
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 fields | Description |
---|---|
| A human-readable description of the error. |
| Detailed information about the error. |
detailedError object | |
Field | Description |
| One of a server-defined set of error codes. |
| A human-readable description of the error code. |