Sorry, you need to enable JavaScript to visit this website.
Market CoverageExtended Market Coverage
Search API And Extended Search API
Get your key

Points of Interest Details

 

Service version: 2
Last edit: 2021.01.19

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>[&sourceName=<sourceName>]

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

▲ Return to top

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.
  • 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.

▲ Return to top

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

{
    "id": "Rm91cnNxdWFyZTo0YTI3MDNjOGY5NjRhNTIwNjY4NTFmZTM=",
    "result": {}
}

XML

<response>
    <id>Rm91cnNxdWFyZTo0YTI3MDNjOGY5NjRhNTIwNjY4NTFmZTM=</id>
    <result></result>
</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.

▲ Return to top

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.
  • 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.

▲ Return to top

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>

▲ Return to top

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.

▲ Return to top