Developer

Fetch sprite

Service version: 1
Last edit: 2024.05.29
TomTom Orbis Maps

Important notes:

  • Orbis Maps Assets API is currently in public preview.
  • This API is powered by the TomTom Orbis Maps.
  • See the TomTom Orbis Maps documentation for more information on Orbis Maps.
  • See the Orbis Maps Assets API Migration page page for information on how to migrate and use the new Orbis Maps Assets API.
  • Use of the Orbis Maps Assets API requires an API Key with access rights to Assets API and, depending on the requested assets, Map Display API and/or Traffic API.

Purpose

  • The fetch sprite endpoint functionality provides the user with the selected sprites, adhering to the MapLibre specification.
  • Sprites from different asset categories can be downloaded individually with the URLs provided when listing sprites list sprites.
  • Users can combine multiple sprites by submitting multiple parameters associated with available asset categories for sprites: map, trafficFlow, and trafficIncidents. See the asset_category parameter in list sprites.
  • When a user is using a high-resolution screen, this must be reflected in the sprite request by the scale factor, see.
    • The scale factor refers to the resolution at which the icons are rendered.
    • The scale factor adjusts the size of the icons to accommodate different screen resolutions and pixel densities, ensuring that the icons look sharp and crisp on various devices.
    • Two scale factors are supported - for standard resolution screens and for high-resolution screens like Retina displays on Apple devices.
    • For a higher scale factor, the sprite icons are rendered at larger sizes to maintain their visual quality at different zoom levels and screen resolutions.

Request data

HTTPS method: GET

  • 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
Generic URL request format
https://{baseURL}/maps/orbis/assets/sprites/{assetVersion}/{spriteScaleFactor}.{format}?key={Your_API_Key}&apiVersion={API_Version}&map={Map}&trafficFlow={Traffic_Flow}&trafficIncidents={Traffic_Incidents}
get
URL request example
https://api.tomtom.com/maps/orbis/assets/sprites/0.0.0-0/sprite@2x.json?key={Your_API_Key}&apiVersion=1&map=basic_street-light&trafficFlow=flow_relative-light&trafficIncidents=incidents_light
get
URL request example - asset version with wildcards
https://api.tomtom.com/maps/orbis/assets/sprites/0.*/sprite@2x.json?key={Your_API_Key}&apiVersion=1&map=basic_street-light&trafficFlow=flow_relative-light&trafficIncidents=incidents_light
get
curl command request format
curl 'https://api.tomtom.com/maps/orbis/assets/sprites/0.0.0-0/sprite@2x.json?key={Your_API_Key}&apiVersion=1&map=basic_street-light&trafficFlow=flow_relative-light&trafficIncidents=incidents_light'
get
curl command request format - asset version with wildcards 
curl 'https://api.tomtom.com/maps/orbis/assets/sprites/0.*/sprite@2x.json?key={Your_API_Key}&apiVersion=1&map=basic_street-light&trafficFlow=flow_relative-light&trafficIncidents=incidents_light'

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.
  • Optional parameters may be used.

Required parameters

Description

baseURL
string

The base URL for calling TomTom services.
Value: api.tomtom.com: The default global API endpoint.

assetVersion
string

The chosen version of the asset.
Versions with wildcards can be used; more information is available at Assets versioning.
Value: string

spriteScaleFactor
string

The sprite's scale factor. It can be one of the predefined values.
Values:

  • sprite
    • (standard)
  • sprite@2x
    • (for high-resolution displays)

format
string

The format of the sprite. It can be one of the predefined values.
Values:

  • json
  • png

apiVersion
string

The API version of the service to call.
This can be omitted if the version is already provided as a request header for the particular service, see HTTP request headers.
If the version is given both as a query parameter and as a header value, the one from the query parameter takes precedence.
Value: The current value is 1.

key
string

An API Key valid for the requested service.
Value: Your valid API Key.

At least one of the following optional parameters must be provided, or the call fails.

Optional parameters

Description

map
string

The map sprite sheet. It can be one of the following values.
Values:

  • basic_street-light
  • basic_street-dark
  • basic_street-light-driving
  • basic_street-dark-driving
  • basic_mono-light
  • basic_mono-dark
  • basic_street-satellite
  • hybrid_mono-dark
    • ,
  • hybrid_mono-light
    • ,
  • hybrid_street-light
  • hybrid_street-dark
  • hybrid_street-light-driving
  • hybrid_street-dark-driving
  • hybrid_street-satellite
  • labels_mono-dark
    • ,
  • labels_mono-light
    • ,
  • labels_street-light
  • labels_street-dark
  • labels_street-light-driving
  • labels_street-dark-driving
  • labels_street-satellite

trafficFlow
string

The traffic flow sprite sheet. It can be one of the following values.
Values:

  • flow_relative-light
  • flow_relative-dark

trafficIncidents
string

The traffic incidents sprite sheet. It can be one of the following values.
Values:

  • incidents_light
  • incidents_dark

Request headers

HTTP request headers are common in the Assets API service. For details, see HTTP request headers.

Response data

Successful response

For a single request, the service returns its response body in either JSON or PNG format. Refer to the MapLibre style specification to understand the content.

Response codes

HTTP response codes are common in the Assets API service. For details, see HTTP response codes.

Response headers

HTTP response headers are common in the Assets API service. For details, see HTTP response headers.