Points of Interest Photos

Service version: 1

Last edit: 2024.11.28

TomTom Orbis Maps

PUBLIC PREVIEW

Public Preview Notice

Important notes:

This TomTom Orbis Maps Search API document collection is in Public Preview. Go to the Public Preview - what is it? page to see what this means.

This API is powered by TomTom Orbis Maps.

See the TomTom Orbis Maps documentation for more information.

This API will be discontinued as of the 24th of June 2022.

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

get

Request curl command format

curl 'https://{baseURL}/maps/orbis/places/poiPhoto?key={Your_API_Key}&apiVersion={apiVersion}&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`
`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 service. Example: `f32882c6-825b-3429-8445-f6a72bbcf3ac`

Optional parameters Description

Optional parameters	Description
`apiVersion` string	Service version. If the `TomTom-Api-Version` header is not present the `apiVersion` parameter is required. Value: A service version value. The current value is `1`.
`width` integer `height` integer	The maximum height/width of the image. If only one of them is provided, the image will be scaled according to that dimension. If none of them are provided, the service will return the original sized image. If both of them are provided, the service will fit, center, and crop the image to fill the desired dimensions. If the values provided are bigger than the original image dimensions, the service will return the original image.

apiVersion
string

Service version. If the TomTom-Api-Version header is not present the apiVersion parameter is required.
Value: A service version value. The current value is 1.

width
integer
height
integer

The maximum height/width of the image.

If only one of them is provided, the image will be scaled according to that dimension.
If none of them are provided, the service will return the original sized image.
If both of them are provided, the service will fit, center, and crop the image to fill the desired dimensions.
If the values provided are bigger than the original image dimensions, the service will return the original image.

Request headers

The following table describes HTTP request headers.

Optional headers Description

TomTom-Api-Version

Optional headers	Description
TomTom-Api-Version	Service version. If the `apiVersion` parameter is not present the `TomTom-Api-Version` header is required. Value: A service version value. The current value is `1`.
If-None-Match	Specifies a previously fetched Etag value for a refresh request. Value: Etag string 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.

Service version. If the apiVersion parameter is not present the TomTom-Api-Version header is required.
Value: A service version value. The current value is 1.

If-None-Match

Specifies a previously fetched Etag value for a refresh request.
Value: Etag string 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

Note: The response body is a photo of the POI.

Usage of Points of Interest Photos data

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

You shall attribute all results delivered by the Extended Search Points of Interest Details API and Points of Interest Photos API as being "powered by Foursquare".
You shall not use any results delivered by the Extended Search Points of Interest Details API and Points of Interest Photos API to create, improve, or edit a venue or point of interest database.
You shall not cache any results delivered by the Extended Search-Points of Interest Details API and Points of Interest Photos API for more than 30 days.
See the Terms and Conditions 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: The HTTP method (`GET`, `POST`, etc.) is not supported for this request.
`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.
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: `public, max-age=2592000, immutable`
Expires	Expiration date information which is set to 30 days later. Cache-Control header takes precedence. Example value: `Fri, 04 Sep 2020 21:30:03 GMT`
Content-Type	Indicates the format of the response. Format: `image/subtype` Value: `type/subtype`: `image/jpg` `image/gif` `image/png` `image/bmp` `image/tiff`
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.