Points of Interest Photos

Service version: 2

Last edit: 2023.09.29

Automotive only

Purpose

The Points of Interest (POI) Photos service provides photos of the POI.

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}/poiPhoto?key={Your_API_Key}&id={id}&height={height}&width={width}

get

Request curl command format

curl 'https://{baseURL}/search/{versionNumber}/poiPhoto?key={Your_API_Key}&id={id}&height={height}&width={width}'

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
`baseURL` string	The base URL for calling the API. Value: `api.tomtom.com`
`versionNumber` string	The service version. Value: The current value is `2`.
`key` string	An API Key valid for the requested service. Value: Your valid `API Key`.
`id` string	Photo id which is previously retrieved from the Points of Interest Details API service. Example: `f32882c6-825b-3429-8445-f6a72bbcf3ac`

Optional parameters Description

Optional parameters	Description
`width` integer `height` integer	The maximum height/width of the image. If none of them is provided, the service will return the original-sized image. If only one of them is provided and smaller than the original image dimension, the image will be scaled according to that dimension. If both of them are provided and are smaller than the original image dimension, the service will create a new scaled image which respects the original aspect ratio, and then it will center and crop the scaled image to fill the desired dimensions. If one of the provided dimensions is bigger than the original and the other one is smaller, it will not scale the image but it will center and crop the original image to fill the desired dimensions. If the value(s) provided are bigger than the original image dimensions, the service will return the original image. The maximum allowed values for width and height are 4096. The maximum allowed values for width and height are 4096.

width
integer
height
integer

The maximum height/width of the image.

If none of them is provided, the service will return the original-sized image.
If only one of them is provided and smaller than the original image dimension, the image will be scaled according to that dimension.
If both of them are provided and are smaller than the original image dimension, the service will create a new scaled image which respects the original aspect ratio, and then it will center and crop the scaled image to fill the desired dimensions.
If one of the provided dimensions is bigger than the original and the other one is smaller, it will not scale the image but it will center and crop the original image to fill the desired dimensions.
If the value(s) provided are bigger than the original image dimensions, the service will return the original image.
The maximum allowed values for width and height are 4096.
The maximum allowed values for width and height are 4096.

Request headers

The following table describes HTTP request headers.

Optional headers Description

Optional headers	Description
If-None-Match string	Specifies a previously fetched Etag value for a refresh request. Value: Etag value returned with the previous request.
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.

If-None-Match
string

Specifies a previously fetched Etag value for a refresh request.
Value: Etag value returned with the previous request.

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

Photo of the POI.

Usage of Points of Interest Photos data

With respect to the Points of Interest Photos 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 codes

Code	Meaning & possible causes
`200`	OK: If the requested photo was provided successfully.
`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

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-Type	Indicates the format of the response. Format: image/subtype Value: type/subtype: `image/jpg` `image/png`
Content-Length	Optional content length information (in number of bytes).
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.
Etag	Etag value of the photo.

Error response

The error response content type depends on the ext parameter.

Error 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}

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