API docs by Redocly

Targomo REST API

Developer Center: developers@targomo.com URL: https://www.targomo.com/developers Terms of Service

Introduction

This is the REST documentation for all service provided by Targomo GmbH. This ranges from the Isochrone API service to Travel Time API as well as Fleet API. For more information and detailed examples please have a look at targomo.com/developers.

If you are developing client side applications, or with Node.js, you might consider using our TypeScript/JavaScript library as a convenience, and to enable certain cartographic features.

Authentication

The Targomo API uses API keys to authenticate requests, and you therefore need an API key to use the API - see our pricing page to sign up for your API key. You can view and manage your API keys at dashboard.targomo.com. API keys are provided to a request as a query parameter or in the POST body, depending on the request - Each request's documentation will indicate the specific way the API key should be referenced.

Basemaps API

GL style json

Returns Vector Tile GL-style json

path Parameters
style
required
string
Example: osm-bright-gl-style

Name of style.

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Responses

Raw vector tile (MVT)

Returns raw MVT-format map tile.

path Parameters
dataset
required
string
Enum: "openmaptiles" "germanypostal"

Name of source dataset.

z
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

TileJSON file

Returns style TileJSON file

path Parameters
style
required
string
Example: osm-bright-gl-style

Name of style.

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Responses

Rendered map tile (PNG)

Returns PNG map tile

path Parameters
style
required
string
Example: osm-bright-gl-style

Name of style.

z
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

r
string
Enum: "@2x" "@3x"
Example: @2x

Optional multiplier for rendering HiDPI (retina) tiles

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Responses

Places Layers API

Provides detailed analysis of Points of Interest (POIs). Retrieve metadata about POIs (Such as types, tags, service keys or hierarchy), or create visualizations (.mvt or geojson) to enhance your maps.

Tiled POIs as mvt

This request retrieves an mvt tile of the POIs that match the requested POI groups or OSM types. The POIs can be requested as hexagons or nodes.
For the tile format (google) see here.

Response type is "application/octet-stream".

path Parameters
zoom
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

group
Array of strings
Example: group=g_education&group=g_electro

Group id(s) of the POI hierarchy.

clusters
object
Example: c_1=g_education&c_2=g_electro&c_3=amenity=bar

List of cluster definitions. Only supported for node requests. With node requests, when zoomed far out, some POIs that are close to each other are clustered to be displayed as a single geometry. With this parameter, one can define different cluster groups. Each cluster name must start with c_, and its value corresponds to one osmType or one POIGroup that this cluster group contains. It is possible to define a cluster group for several POIGroups or osmTypes via the request string "c_1=g_food&c_1=g_electro" for example. This cluster definition enables then to know how many POI of the different cluster definitions are contained in each cluster geometry. If some POIs belong to no clusters definition, they will be counted in c_other.

exclude
Array of strings
Example: exclude=computer&exclude=amenity=kindergarten

List of OSM tags (separated by =) or group id of the POI hierarchy (for example g_electro or computer) that must not appear in the response.

match
string
Enum: "any" "all"

Type of match for the combination of tags. match=any (by default if not specified) means that the service will retrieve all POIs that contain at least one tag of the request. match=all means that it will retrieve all POIs that contain all tags of the request.

layerType
string
Enum: "node" "hexagon"

Desired layer type for the tiles

loadAllTags
boolean
Default: false

Whether or not to retrieve all tags of the POIs.

layerGeometryDetailPerTile
integer
Example: layerGeometryDetailPerTile=7

Difference between the zoom level of the map and the one used to build the geometries.

layerMinGeometryDetailLevel
integer
Example: layerMinGeometryDetailLevel=7

Minimum zoom level used to build the geometries.

layerMaxGeometryDetailLevel
integer
Example: layerMaxGeometryDetailLevel=28

Maximum zoom level used to build the geometries.

maxGeometryCount
integer
Example: maxGeometryCount=100000

Maximum number of geometries in a tile.

Responses

Tiled POI as GeoJSON

This request retrieves a GeoJSON tile of the POIs that match the requested POI groups or OSM types. The POIs can be requested as hexagons or nodes.

Response type is "application/json".

path Parameters
zoom
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

group
Array of strings
Example: group=g_education&group=g_electro

Group id(s) of the POI hierarchy.

clusters
object
Example: c_1=g_education&c_2=g_electro&c_3=amenity=bar

List of cluster definitions. Only supported for node requests. With node requests, when zoomed far out, some POIs that are close to each other are clustered to be displayed as a single geometry. With this parameter, one can define different cluster groups. Each cluster name must start with c_, and its value corresponds to one osmType or one POIGroup that this cluster group contains. It is possible to define a cluster group for several POIGroups or osmTypes via the request string "c_1=g_food&c_1=g_electro" for example. This cluster definition enables then to know how many POI of the different cluster definitions are contained in each cluster geometry. If some POIs belong to no clusters definition, they will be counted in c_other.

exclude
Array of strings
Example: exclude=computer&exclude=amenity=kindergarten

List of OSM tags (separated by =) or group id of the POI hierarchy (for example g_electro or computer) that must not appear in the response.

match
string
Enum: "any" "all"

Type of match for the combination of tags. match=any (by default if not specified) means that the service will retrieve all POIs that contain at least one tag of the request. match=all means that it will retrieve all POIs that contain all tags of the request.

layerType
string
Enum: "node" "hexagon"

Desired layer type for the tiles

loadAllTags
boolean
Default: false

Whether or not to retrieve all tags of the POIs.

layerGeometryDetailPerTile
integer
Example: layerGeometryDetailPerTile=7

Difference between the zoom level of the map and the one used to build the geometries.

layerMinGeometryDetailLevel
integer
Example: layerMinGeometryDetailLevel=7

Minimum zoom level used to build the geometries.

layerMaxGeometryDetailLevel
integer
Example: layerMaxGeometryDetailLevel=28

Maximum zoom level used to build the geometries.

maxGeometryCount
integer
Example: maxGeometryCount=100000

Maximum number of geometries in a tile.

Responses

Register POI Configuration

This service registers a POI request configuration and returns a uuid that can be used to request the same POIs as mvt tile.

Request Body schema: application/json
required

Necessary for this service:

  • serviceUrl & serviceKey
  • One or more osmType
serviceKey
required
string

This is the Targomo APi key (serviceKey) that you receive once you are registered at targomo.com/developers.
For other requests this is specified as query parameter.

serviceUrl
required
string

This is the service URL to which the other dependant Targomo requests are dispatched (e.g Targomo Time or Routing requestrs). The endpoint has to correspond to the addresses, e.g. if you want to execute Vehicle Routing in France you need to point to an Targomo Endpoint that includes France geographically.

required
Array of OsmType (object) or PoiGroup (object)

List of osm types or POI groups to request.

Array of OsmType (object) or PoiGroup (object)

List of osm types or POI groups to exclude from the response.

match
string (MatchType)
Enum: "any" "all"

Type of match for the combination of tags. match=any (by default if not specified) means that the service will retrieve all POIs that contain at least one tag of the request. match=all means that it will retrieve all POIs that contain all tags of the request.

format
string (POIFormat)
Default: "json"
Enum: "json" "geojson"

This optional parameter is currently only used for the Places Context APIs.

Possible values are json, where results will be returned in a single JSON object with the OSM Ids as keys and the properties as values, or GeoJSON.

object (Filter Geometry)

Geometry with a closed shape. All the POIs returned in the response will be contained in this filter geometry (also known as clip geometry). This geometry can be used for both /reachability and /geometry endpoints.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
text/plain
230ef01e-7701-41d1-8340-aa9848f97620

POIs From Configuration as mvt

This service returns an mvt tile of points of interest (POIs) for a given uuid corresponding to an already registered POI configuration (/register). The POIs can be requested as hexagons or nodes.
This interface allows easy integration into MapboxGL. For the tile format (google) see here.

Response type is "application/octet-stream".

Necessary for this service: uuid + apiKey

path Parameters
zoom
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

uuid
required
string
Example: c4cc1624-5baf-48d2-b284-d2d5718d80c9

Uuid of a registered request

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

loadAllTags
boolean
Default: false

Whether or not to retrieve all tags of the POIs.

layerType
string
Enum: "node" "hexagon"

Desired layer type for the tiles

layerGeometryDetailPerTile
integer
Example: layerGeometryDetailPerTile=7

Difference between the zoom level of the map and the one used to build the geometries.

layerMinGeometryDetailLevel
integer
Example: layerMinGeometryDetailLevel=7

Minimum zoom level used to build the geometries.

layerMaxGeometryDetailLevel
integer
Example: layerMaxGeometryDetailLevel=28

Maximum zoom level used to build the geometries.

maxGeometryCount
integer
Example: maxGeometryCount=100000

Maximum number of geometries in a tile.

Responses

POIs From Configuration as GeoJSON

This service returns an mvt tile of reachable points of interest (POIs) for an already registered configuration. The POIs can be requested as hexagons or nodes.
This interface allows easy integration into MapboxGL. For the tile format (google) see here.

Response type is "application/json".

Necessary for this service: uuid + apiKey

path Parameters
zoom
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

uuid
required
string
Example: c4cc1624-5baf-48d2-b284-d2d5718d80c9

Uuid of a registered request

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

loadAllTags
boolean
Default: false

Whether or not to retrieve all tags of the POIs.

layerType
string
Enum: "node" "hexagon"

Desired layer type for the tiles

layerGeometryDetailPerTile
integer
Example: layerGeometryDetailPerTile=7

Difference between the zoom level of the map and the one used to build the geometries.

layerMinGeometryDetailLevel
integer
Example: layerMinGeometryDetailLevel=7

Minimum zoom level used to build the geometries.

layerMaxGeometryDetailLevel
integer
Example: layerMaxGeometryDetailLevel=28

Maximum zoom level used to build the geometries.

maxGeometryCount
integer
Example: maxGeometryCount=100000

Maximum number of geometries in a tile.

Responses

Bounding Box POIs

This request retrieves all POIs that match the requested POI groups or OSM types inside a bounding box.

Response type is "application/json".

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

northEastX
required
number
Example: northEastX=13.4247584

The North East X (longitude) coordinate of the desired bounding box.

northEastY
required
number
Example: northEastY=52.4895795

The North East Y (latitude) coordinate of the desired bounding box.

southWestX
required
number
Example: southWestX=13.4347586

The South West X (longitude) coordinate of the desired bounding box.

southWestY
required
number
Example: southWestY=52.4995797

The South West Y (latitude) coordinate of the desired bounding box.

group
Array of strings
Example: group=g_education&group=g_electro

Group id(s) of the POI hierarchy.

osmType
object
Example: amenity=bar&cuisine=*

OSM tags key-value pair(s). See OSM map features for a complete list of features. A wildcard (*) can also be used to retrieve all POIs that contain one key. For example, "cuisine=*"

exclude
Array of strings
Example: exclude=computer&exclude=amenity=kindergarten

List of OSM tags (separated by =) or group id of the POI hierarchy (for example g_electro or computer) that must not appear in the response.

match
string
Enum: "any" "all"

Type of match for the combination of tags. match=any (by default if not specified) means that the service will retrieve all POIs that contain at least one tag of the request. match=all means that it will retrieve all POIs that contain all tags of the request.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

POIs Information

This request retrieves the info of a list of POIs from their Ids.

Nomenclature of the ids:
0_ means that the requested POI is a node.
1_ means that the requested POI is a way (a line or a polygon).
Theses prefixes are followed by the id of the object in the OSM database.
If the id is negative, it means that the node or the way derives from a relation.

Response type is "application/json".

path Parameters
poiIds
required
Array of strings
Example: 0_502545685,1_23971045,1_-2925020

List of POI Ids

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Responses

POI Service OSM Keys

This request returns a list of OSM keys that the service accepts in its requests.

Response type is "application/json".

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Responses

Response samples

Content type
application/json
[
  • "shop",
  • "amenity",
  • "historic"
]

OSM Tags

This request returns all OSM tag values of the requested tagKey that exist in the Places Layers and Places Context API database.

Response type is "application/json".

path Parameters
tagKey
required
string
Example: shop

OSM key that is supported by the service.

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

text
string
Example: text=b

A suggested term to which the results will be similar.

limit
integer
Example: limit=20

Maximum number of results retrieved by the service.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

POI Service Hierarchy

This request returns the POI hierarchy supported by the service. The POI Hierarchy is a tree of POI groups that one can use to request groups of POI by their ids.

Response type is "application/json".

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Responses

Response samples

Content type
application/json
{
  • "id": "g_shop",
  • "type": "CATEGORY",
  • "name": "Shopping",
  • "description": "Places where to shop",
  • "contents": [
    ]
}

Statistics Layers API

The Statistics Layers API provides detailed information about available statistics data for Statistic Collections or groups. Collections are generally sets of statistical data (such as the Berlin census) while groups within an collection provide that data at different resolutions (e.g. 500m or 200m per cell).

Statistic Collection mvt

Returns Statistics Layers (mvt tiles) of the statistic collection via statistic group with the highest resolution by given collection id.

path Parameters
collection
required
integer
Example: 100

statistic collection for layer

z
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

statistics
string
Example: statistics=statistics=0&statistics=1&statistics=2

Statistics id list to return in the response.

sumStatistics
boolean
Default: false

If true also return the sum of all given statistics values. The default is false.

useDb
string
Default: false

If true, generate result from db, else use in memory data. If false, serviceUrl parameter must be used. The default is false.

Responses

Statistic Collection GeoJSON

Returns Statistics Layers (GeoJSON) of the statistic collection via statistic group with the highest resolution by given collection id.

path Parameters
collection
required
integer
Example: 100

statistic collection for layer

z
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

statistics
string
Example: statistics=statistics=0&statistics=1&statistics=2

Statistics id list to return in the response.

sumStatistics
boolean
Default: false

If true also return the sum of all given statistics values. The default is false.

useDb
string
Default: false

If true, generate result from db, else use in memory data. If false, serviceUrl parameter must be used. The default is false.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "code": "ok",
  • "message": "",
  • "requestTime": "79"
}

List Statistic Collections

Returns a list of Statistic Collections with metadata and component groups

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

collections
string
Example: collections=1&collections=2&collections=3

Specific collections as string

endpoint
string

Specific endpoint name

locale
string
Default: "en"
Example: locale=de

The two letter language code for the name and description language.

Responses

Response samples

Content type
application/json
{
  • "5": {
    }
}

Statistic Collection Overview by Country

Returns a list of Statistic Collections with overview metadata grouped by country (using the alpha-3 code).

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Responses

Response samples

Content type
application/json
{
  • "SWE": [
    ]
}

Statistic Collections Overview for a specific Country

Returns a list of Statistic Collections for a specific country (using the alpha-3 code).

path Parameters
code
required
string
Example: SWE

the Alpha-3 Three letter code of the country to be retrieved. Case insensitive

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Statistic Collections Overview

Returns a list of Statistic Collections in the overview format.

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Statistic Collection Overview for a specific Country

Returns a specified of Statistic Collection in the overview format.

path Parameters
collection
required
integer
Example: 5

The id of the Statistic Collection to be retrieved

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Statistic Collection Overview by Region

Returns a list of Statistic Collections with overview metadata grouped by collection region.

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Responses

Response samples

Content type
application/json
{
  • "sweden": [
    ]
}

Statistic Collection Overview for a specific Region

Returns a list of Statistic Collections for a specific region.

path Parameters
region
required
string
Example: sweden

The Statistic Collection region to retrieve collections for. Case insensitive

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Isochrone API

Create sets of polygons that represent the reachable areas from a list of sources.

Polygons Reachability

This API returns a list of polygons that visualize the reachability boundaries of given sources, e.g. a polygon for what is reachable within 10, 20, or 30 minutes.

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Request Body schema: application/json
required

Necessary for this API:

  • One or more source elements. These can be either sources (coordinates), sourceGeometries (GeoJSON Linestrings, Polygons or Multipolygon) or a mix of both.
  • edgeWeight
  • The specification of the polygon(s)

Ignored parameters:

  • targets
  • maxEdgeWeight (edgeWeight thresholds are defined in polygon.values instead)
required
object (Polygon)

Specifies the polygon that is requested

Array of objects (TargetCore)
showSnapInformation
boolean
Default: false

display information on snap distances in the response. Currently only available for Route, Time and reachability APIs

Array of objects (SourceCore)
Array of objects (SourceGeometry)
edgeWeight
string
Default: "time"
Enum: "time" "distance"

Determines the dimension of the edges' weight, i.e. time (distance in seconds) or distance (distance in meters). distance Will optimize for distance and search for the shortest path, time will optimize for time and will search for the fastest path. Distance cannot be used in concert with travelType transit.

maxEdgeWeight
integer <int32>
Default: 1800

The maximum distance "depth" of the built network in seconds (for edgeWeight = time) or meters (for edgeWeight = distance). lower max edge weights limit the size of the networked and the area covered, while greater values will increase the time taken to process the request. The upper limit of this variable is based on your subscription plan and differs between distance and time.

elevation
boolean
Default: true

Whether or not the an elevation heuristic will be used (e.g. downhill with bike quicker than uphill).

reverse
boolean
Default: false

If the reverse flag is set to true, the routing algorithm will invert direction restrictions (one way roads, turning restrictions, ect) to simulate a to the source(s). For polygon routing this can be used to calculate the polygon/area that could reach the source(s).

object

Specifies factors with which the travel times of the edges are adjusted. This may be necessary in certain areas where the travel time calculation is almost always off by a certain factor, e.g. Paris rush hour.

"travelTimeFactors" : { "all":0.5, "motorway":1.5, .... (other specific edge classes possible) },..

Further specifics about the TravelTimeFactors:

  • travel time factor of 1.5 means 50% more time is needed
  • travel time factor 'all' is applied to ALL edge classes (on top of a specified one, e.g. for the example above 1.5*0.5=0.75 - the final applied travel time factor for 'motorway' edges)
  • all elements are optional, min allowed cumulative travel time factor is 0.5; maximum allowed cumulative travel time factor is 100.0
  • elements that are not recognized are ignored
  • transit travel times are not affected by the travelTimeFactors
maxSnapDistance
integer
Default: "Endpoint Specific"

This defines the maximum distance allowed (in meters) between a defined source/target and the nearest point in the network it will connect. Any point that has a distance exceeding maxSnapDistance is treated like a point that exceeds maxEdgeWeight.
If set too low points will be unable to snap to any nearby edges, if set too high points set outside the network or where lat/long have been accidentally inverted will be able to snap to the outer edge of the network.

object

The exclusion geometry describes a GeoJSON object that should not be traveled through during the routing calculation. Any edges That intersect with the described geometry will be excluded from the routing. This can be used to simulate temporarily impassible routes or to deliberatley exclude certain ways. Both 'data' and 'crs' must be defined and do not have default values.

Responses

Request samples

Content type
application/json
{
  • "sources": [
    ],
  • "edgeWeight": "time",
  • "polygon": {
    }
}

Response samples

Content type
application/json
Example
{
  • "area": 783650.4006168544,
  • "polygons": {
    }
}

Polygons Reachability

The Isochrone API can also be called as get request, where the Configuration Model is the query parameter cfg.

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

cfg
required
string
Default: "{\n \"sources\":[\n {\n \"lat\":52.51042282571668,\n \"lng\":13.38984489440918,\n \"id\":\"U Stadtmitte Berlin\",\n \"tm\":{\"bike\":{}}\n },\n {\n \"lat\":52.50956088985956,\n \"lng\":13.377184867858887,\n \"id\":\"S Potsdamer Platz\",\n \"tm\":{\"bike\":{}}\n }\n ],\n \"edgeWeight\":\"time\",\n \"polygon\":{\n \"values\":[100,300,600],\n \"intersectionMode\":\"union\",\n \"serializer\":\"json\"\n }\n}"

JSON Configuration as query parameter.
Please keep in mind that for compatibility, the GET URL recommended maximum size is 2000 chars

Responses

Response samples

Content type
application/json
Example
{
  • "area": 783650.4006168544,
  • "polygons": {
    }
}

Tiled Polygons Reachability as MVT

The Isochrone API can be called with tile and serialization specified as path parameters. This is only available for MVT. The tile and serialization in the request body will be overwritten.

This interface allows for easy integration with MapboxGL. For tile format (google) see here.

The Configuration Model is the query parameter cfg.

Response type is "application/octet-stream".

path Parameters
zoom
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

cfg
required
string
Default: "{\n \"sources\":[\n {\n \"lat\":52.51042282571668,\n \"lng\":13.38984489440918,\n \"id\":\"U Stadtmitte Berlin\",\n \"tm\":{\"bike\":{}}\n },\n {\n \"lat\":52.50956088985956,\n \"lng\":13.377184867858887,\n \"id\":\"S Potsdamer Platz\",\n \"tm\":{\"bike\":{}}\n }\n ],\n \"edgeWeight\":\"time\",\n \"polygon\":{\n \"values\":[100,300,600],\n \"intersectionMode\":\"union\",\n \"serializer\":\"json\"\n }\n}"

JSON Configuration as query parameter.
Please keep in mind that for compatibility, the GET URL recommended maximum size is 2000 chars

Responses

Travel Times API

Retrieve the travel time (in seconds) and the travel distance (in meters) between lists of sources and targets. If multiple sources and targets are set a result will be returned for each unique source-target pair.

Travel Times

Calculates the shortest travel times and lengths from all sources to all targets.
The run-time is mostly dependent on the number of sources and the maximum allowed edgeWeight.

Note: Despite the name the Travel Time API can also return the distance between sources and target in meters if "edgeWeight": "distance" is specified.

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Request Body schema: application/json
required

Necessary for this API:

  • One or more source elements. These can be either sources (coordinates), sourceGeometries (GeoJSON Linestrings, Polygons or Multipolygon) or a mix of both.
  • One or more target elements
  • edgeWeight & maxEdgeWeight
required
Array of objects (TargetCore)
showSnapInformation
boolean
Default: false

display information on snap distances in the response. Currently only available for Route, Time and reachability APIs

Array of objects (SourceCore)
Array of objects (SourceGeometry)
edgeWeight
string
Default: "time"
Enum: "time" "distance"

Determines the dimension of the edges' weight, i.e. time (distance in seconds) or distance (distance in meters). distance Will optimize for distance and search for the shortest path, time will optimize for time and will search for the fastest path. Distance cannot be used in concert with travelType transit.

maxEdgeWeight
integer <int32>
Default: 1800

The maximum distance "depth" of the built network in seconds (for edgeWeight = time) or meters (for edgeWeight = distance). lower max edge weights limit the size of the networked and the area covered, while greater values will increase the time taken to process the request. The upper limit of this variable is based on your subscription plan and differs between distance and time.

elevation
boolean
Default: true

Whether or not the an elevation heuristic will be used (e.g. downhill with bike quicker than uphill).

reverse
boolean
Default: false

If the reverse flag is set to true, the routing algorithm will invert direction restrictions (one way roads, turning restrictions, ect) to simulate a to the source(s). For polygon routing this can be used to calculate the polygon/area that could reach the source(s).

object

Specifies factors with which the travel times of the edges are adjusted. This may be necessary in certain areas where the travel time calculation is almost always off by a certain factor, e.g. Paris rush hour.

"travelTimeFactors" : { "all":0.5, "motorway":1.5, .... (other specific edge classes possible) },..

Further specifics about the TravelTimeFactors:

  • travel time factor of 1.5 means 50% more time is needed
  • travel time factor 'all' is applied to ALL edge classes (on top of a specified one, e.g. for the example above 1.5*0.5=0.75 - the final applied travel time factor for 'motorway' edges)
  • all elements are optional, min allowed cumulative travel time factor is 0.5; maximum allowed cumulative travel time factor is 100.0
  • elements that are not recognized are ignored
  • transit travel times are not affected by the travelTimeFactors
maxSnapDistance
integer
Default: "Endpoint Specific"

This defines the maximum distance allowed (in meters) between a defined source/target and the nearest point in the network it will connect. Any point that has a distance exceeding maxSnapDistance is treated like a point that exceeds maxEdgeWeight.
If set too low points will be unable to snap to any nearby edges, if set too high points set outside the network or where lat/long have been accidentally inverted will be able to snap to the outer edge of the network.

object

The exclusion geometry describes a GeoJSON object that should not be traveled through during the routing calculation. Any edges That intersect with the described geometry will be excluded from the routing. This can be used to simulate temporarily impassible routes or to deliberatley exclude certain ways. Both 'data' and 'crs' must be defined and do not have default values.

Responses

Request samples

Content type
application/json
{
  • "edgeWeight": "time",
  • "maxEdgeWeight": "2000",
  • "sources": [
    ],
  • "targets": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "code": "ok",
  • "message": "",
  • "requestTime": "2"
}

Transit Travel Times

Calculates all optimal connections in a time frame for each source-target combination if the travel type is transit or the shortest travel time for other travel types. A connection is not optimal if it departs earlier and arrives later than another connection. The connections are returned as pairs of departure and arrival times, sorted by departure time. In addition the travel time for walking to the target (without using transit) is returned. This travel time may be "-1" in case the target is not reachable within maxEdgeWeight by walking. If the travel type is not transit, the response is the same as for the Travel Time API.
The run-time is mostly dependent on the number of sources and maxEdgeWeight.

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Request Body schema: application/json
required

Necessary for this API:

  • One or more source elements. These can be either sources (coordinates), sourceGeometries (GeoJSON Linestrings, Polygons or Multipolygon) or a mix of both.
  • One or more target elements
  • edgeWeight & maxEdgeWeight
required
Array of objects (TargetCore)
showSnapInformation
boolean
Default: false

display information on snap distances in the response. Currently only available for Route, Time and reachability APIs

Array of objects (SourceCore)
Array of objects (SourceGeometry)
edgeWeight
string
Default: "time"
Enum: "time" "distance"

Determines the dimension of the edges' weight, i.e. time (distance in seconds) or distance (distance in meters). distance Will optimize for distance and search for the shortest path, time will optimize for time and will search for the fastest path. Distance cannot be used in concert with travelType transit.

maxEdgeWeight
integer <int32>
Default: 1800

The maximum distance "depth" of the built network in seconds (for edgeWeight = time) or meters (for edgeWeight = distance). lower max edge weights limit the size of the networked and the area covered, while greater values will increase the time taken to process the request. The upper limit of this variable is based on your subscription plan and differs between distance and time.

elevation
boolean
Default: true

Whether or not the an elevation heuristic will be used (e.g. downhill with bike quicker than uphill).

reverse
boolean
Default: false

If the reverse flag is set to true, the routing algorithm will invert direction restrictions (one way roads, turning restrictions, ect) to simulate a to the source(s). For polygon routing this can be used to calculate the polygon/area that could reach the source(s).

object

Specifies factors with which the travel times of the edges are adjusted. This may be necessary in certain areas where the travel time calculation is almost always off by a certain factor, e.g. Paris rush hour.

"travelTimeFactors" : { "all":0.5, "motorway":1.5, .... (other specific edge classes possible) },..

Further specifics about the TravelTimeFactors:

  • travel time factor of 1.5 means 50% more time is needed
  • travel time factor 'all' is applied to ALL edge classes (on top of a specified one, e.g. for the example above 1.5*0.5=0.75 - the final applied travel time factor for 'motorway' edges)
  • all elements are optional, min allowed cumulative travel time factor is 0.5; maximum allowed cumulative travel time factor is 100.0
  • elements that are not recognized are ignored
  • transit travel times are not affected by the travelTimeFactors
maxSnapDistance
integer
Default: "Endpoint Specific"

This defines the maximum distance allowed (in meters) between a defined source/target and the nearest point in the network it will connect. Any point that has a distance exceeding maxSnapDistance is treated like a point that exceeds maxEdgeWeight.
If set too low points will be unable to snap to any nearby edges, if set too high points set outside the network or where lat/long have been accidentally inverted will be able to snap to the outer edge of the network.

object

The exclusion geometry describes a GeoJSON object that should not be traveled through during the routing calculation. Any edges That intersect with the described geometry will be excluded from the routing. This can be used to simulate temporarily impassible routes or to deliberatley exclude certain ways. Both 'data' and 'crs' must be defined and do not have default values.

Responses

Request samples

Content type
application/json
{
  • "edgeWeight": "time",
  • "maxEdgeWeight": "2000",
  • "sources": [
    ],
  • "targets": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "code": "ok",
  • "message": "",
  • "requestTime": "2"
}

MultiGraph API

Perform reachability based aggregations for a number of sources to perform fine tuned analyse of highly complex scenarios.

MultiGraph Calculation

This API returns a MultiGraph representing a specified aggregation based on travel times or distances from the sources. You can answer questions like:

  1. How does my current shop network (or public transportation network) cover a given area and where are gaps in my network?
  2. Where should I locate my office so that my employees will spend the least time traveling to and from work?
  3. How should I split up the delivery zones between my shops if I want to minimize the delivery times?

The resulting graph contains spatial information equivalent to the underlying map, i.e. roads, crossings, etc. Other heatmap types are possible, e.g. displaying the result in tiles.
Possible formats are GeoJSON, mvt and json.

It can be seen as a different visualization of the Isochrone API which allows for more customization with regards to the source aggregation/intersection as well as the serialization formats.

Response type is dependent on the chosen serialization type:

  • "application/json" for json or geojson
  • "application/octet-stream for mvt
query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Request Body schema: application/json
required

Necessary for this API:

  • One or more source elements. These can be either sources (coordinates), sourceGeometries (GeoJSON Linestrings, Polygons or Multipolygon) or a mix of both.
  • edgeWeight & maxEdgeWeight
  • definition of the MultiGraph aggregation

Ignored parameters:

  • targets
required
object (MultiGraph)

MultiGraph-specific options are defined in this parent object. For most parameters a default value exists such that mostly only the main configurations, i.e. aggregation.type, serialization.format, and layerType, should be consciously chosen according to requirements.

The underlying process for the MultiGraph calculation is the following:

  1. Routing for each source points (exception: routing_union)
  2. Aggregation of the resulting information (grouped by edges or nodes depending on the layer type) according to the specified aggregation type (and pre- and post-filter configuration).
  3. Serialization of the MultiGraph: The MultiGraph consisting of nodes (and edges) is serialized into the specified form (layerType), e.g. 'edge', 'tile', conforming to the specified format, e.g. 'GeoJSON', 'mvt'.

Array of objects (TargetCore)
showSnapInformation
boolean
Default: false

display information on snap distances in the response. Currently only available for Route, Time and reachability APIs

Array of objects (SourceCore)
Array of objects (SourceGeometry)
edgeWeight
required
string
Default: "time"
Enum: "time" "distance"

Determines the dimension of the edges' weight, i.e. time (distance in seconds) or distance (distance in meters). distance Will optimize for distance and search for the shortest path, time will optimize for time and will search for the fastest path. Distance cannot be used in concert with travelType transit.

maxEdgeWeight
required
integer <int32>
Default: 1800

The maximum distance "depth" of the built network in seconds (for edgeWeight = time) or meters (for edgeWeight = distance). lower max edge weights limit the size of the networked and the area covered, while greater values will increase the time taken to process the request. The upper limit of this variable is based on your subscription plan and differs between distance and time.

elevation
boolean
Default: true

Whether or not the an elevation heuristic will be used (e.g. downhill with bike quicker than uphill).

reverse
boolean
Default: false

If the reverse flag is set to true, the routing algorithm will invert direction restrictions (one way roads, turning restrictions, ect) to simulate a to the source(s). For polygon routing this can be used to calculate the polygon/area that could reach the source(s).

object

Specifies factors with which the travel times of the edges are adjusted. This may be necessary in certain areas where the travel time calculation is almost always off by a certain factor, e.g. Paris rush hour.

"travelTimeFactors" : { "all":0.5, "motorway":1.5, .... (other specific edge classes possible) },..

Further specifics about the TravelTimeFactors:

  • travel time factor of 1.5 means 50% more time is needed
  • travel time factor 'all' is applied to ALL edge classes (on top of a specified one, e.g. for the example above 1.5*0.5=0.75 - the final applied travel time factor for 'motorway' edges)
  • all elements are optional, min allowed cumulative travel time factor is 0.5; maximum allowed cumulative travel time factor is 100.0
  • elements that are not recognized are ignored
  • transit travel times are not affected by the travelTimeFactors
maxSnapDistance
integer
Default: "Endpoint Specific"

This defines the maximum distance allowed (in meters) between a defined source/target and the nearest point in the network it will connect. Any point that has a distance exceeding maxSnapDistance is treated like a point that exceeds maxEdgeWeight.
If set too low points will be unable to snap to any nearby edges, if set too high points set outside the network or where lat/long have been accidentally inverted will be able to snap to the outer edge of the network.

object

The exclusion geometry describes a GeoJSON object that should not be traveled through during the routing calculation. Any edges That intersect with the described geometry will be excluded from the routing. This can be used to simulate temporarily impassible routes or to deliberatley exclude certain ways. Both 'data' and 'crs' must be defined and do not have default values.

Responses

Request samples

Content type
application/json
{
  • "edgeWeight": "time",
  • "maxEdgeWeight": 100,
  • "multigraph": {
    },
  • "sources": [
    ]
}

MultiGraph calculation

This API returns a MultiGraph representing a specified aggregation based on travel times or distances from the sources. You can answer questions like:

  1. How does my current shop network (or public transportation network) cover a given area and where are gaps in my network?
  2. Where should I locate my office so that my employees will spend the least time traveling to and from work?
  3. How should I split up the delivery zones between my shops if I want to minimize the delivery times?

The resulting graph contains spatial information equivalent to the underlying map, i.e. roads, crossings, etc. Other heatmap types are possible, e.g. displaying the result in tiles.
Possible formats are GeoJSON, mvt and json.

It can be seen as a different visualization of the Isochrone API which allows for more customization with regards to the source aggregation/intersection as well as the serialization formats.

The MultiGraphRequestConfiguration is URL encoded a query parameter.

Response type is dependent on the chosen serialization type:

  • "application/json" for json or geojson
  • "application/octet-stream for mvt
query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

cfg
required
string
Default: "{\n \"sources\":[\n {\n \"lat\":52.51042282571668,\n \"lng\":13.38984489440918,\n \"id\":\"U Stadtmitte Berlin\",\n \"tm\":{\"bike\":{}}\n },\n {\n \"lat\":52.50956088985956,\n \"lng\":13.377184867858887,\n \"id\":\"S Potsdamer Platz\",\n \"tm\":{\"bike\":{}}\n }\n ],\n \"edgeWeight\":\"time\",\n \"maxEdgeWeight\":\"100\",\n \"multigraph\":{\n \"aggregation\":{\"type\":\"min\"},\n \"serialization\":{\"format\":\"geojson\"}}\n }\n}"

JSON Configuration as query parameter
Please keep in mind that for compatibility, the GET URL recommended maximum size is 2000 chars

Responses

Tiled MultiGraph as mvt

The MultiGraph request but with the tile and serialization (mvt) already specified as a path parameter (the tile and serialization format in the request body are overwritten).

This interface allows an easy integration into MapboxGL. For the tile format (google) see here.

Response type is "application/octet-stream".

path Parameters
zoom
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Request Body schema: application/json
required
required
object (MultiGraph)

MultiGraph-specific options are defined in this parent object. For most parameters a default value exists such that mostly only the main configurations, i.e. aggregation.type, serialization.format, and layerType, should be consciously chosen according to requirements.

The underlying process for the MultiGraph calculation is the following:

  1. Routing for each source points (exception: routing_union)
  2. Aggregation of the resulting information (grouped by edges or nodes depending on the layer type) according to the specified aggregation type (and pre- and post-filter configuration).
  3. Serialization of the MultiGraph: The MultiGraph consisting of nodes (and edges) is serialized into the specified form (layerType), e.g. 'edge', 'tile', conforming to the specified format, e.g. 'GeoJSON', 'mvt'.

Array of objects (TargetCore)
showSnapInformation
boolean
Default: false

display information on snap distances in the response. Currently only available for Route, Time and reachability APIs

Array of objects (SourceCore)
Array of objects (SourceGeometry)
edgeWeight
required
string
Default: "time"
Enum: "time" "distance"

Determines the dimension of the edges' weight, i.e. time (distance in seconds) or distance (distance in meters). distance Will optimize for distance and search for the shortest path, time will optimize for time and will search for the fastest path. Distance cannot be used in concert with travelType transit.

maxEdgeWeight
required
integer <int32>
Default: 1800

The maximum distance "depth" of the built network in seconds (for edgeWeight = time) or meters (for edgeWeight = distance). lower max edge weights limit the size of the networked and the area covered, while greater values will increase the time taken to process the request. The upper limit of this variable is based on your subscription plan and differs between distance and time.

elevation
boolean
Default: true

Whether or not the an elevation heuristic will be used (e.g. downhill with bike quicker than uphill).

reverse
boolean
Default: false

If the reverse flag is set to true, the routing algorithm will invert direction restrictions (one way roads, turning restrictions, ect) to simulate a to the source(s). For polygon routing this can be used to calculate the polygon/area that could reach the source(s).

object

Specifies factors with which the travel times of the edges are adjusted. This may be necessary in certain areas where the travel time calculation is almost always off by a certain factor, e.g. Paris rush hour.

"travelTimeFactors" : { "all":0.5, "motorway":1.5, .... (other specific edge classes possible) },..

Further specifics about the TravelTimeFactors:

  • travel time factor of 1.5 means 50% more time is needed
  • travel time factor 'all' is applied to ALL edge classes (on top of a specified one, e.g. for the example above 1.5*0.5=0.75 - the final applied travel time factor for 'motorway' edges)
  • all elements are optional, min allowed cumulative travel time factor is 0.5; maximum allowed cumulative travel time factor is 100.0
  • elements that are not recognized are ignored
  • transit travel times are not affected by the travelTimeFactors
maxSnapDistance
integer
Default: "Endpoint Specific"

This defines the maximum distance allowed (in meters) between a defined source/target and the nearest point in the network it will connect. Any point that has a distance exceeding maxSnapDistance is treated like a point that exceeds maxEdgeWeight.
If set too low points will be unable to snap to any nearby edges, if set too high points set outside the network or where lat/long have been accidentally inverted will be able to snap to the outer edge of the network.

object

The exclusion geometry describes a GeoJSON object that should not be traveled through during the routing calculation. Any edges That intersect with the described geometry will be excluded from the routing. This can be used to simulate temporarily impassible routes or to deliberatley exclude certain ways. Both 'data' and 'crs' must be defined and do not have default values.

Responses

Request samples

Content type
application/json
{
  • "edgeWeight": "time",
  • "maxEdgeWeight": 100,
  • "multigraph": {
    },
  • "sources": [
    ]
}

Tiled MultiGraph as mvt

The MultiGraph request but with the tile and serialization (mvt) already specified as a path parameter (the tile and serialization format in the request body are overwritten).

This interface allows an easy integration into MapboxGL. For the tile format (google) see here.

The MultiGraphRequestConfiguration is URL encoded a query parameter.

Response type is "application/octet-stream".

path Parameters
zoom
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

cfg
required
string
Default: "{\n \"sources\":[\n {\n \"lat\":52.450411,\n \"lng\":13.4375,\n \"id\":\"1\",\n \"tm\":{\"car\":{}}\n },\n {\n \"lat\":52.451,\n \"lng\":13.437,\n \"id\":\"2\",\n \"tm\":{\"car\":{}}\n }\n ],\n \"edgeWeight\":\"time\",\n \"maxEdgeWeight\":\"100\",\n \"multigraph\":{\n \"aggregation\":{\"type\":\"routing_union\"}}\n }"

JSON Configuration as query parameter
Please keep in mind that for compatibility, the GET URL recommended maximum size is 2000 chars

Responses

Tiled MultiGraph as GeoJSON

The MultiGraph request but with the tile and serialization (GeoJSON) already specified as a path parameter (the tile and serialization format in the request body are overwritten).
For the tile format (google) see here.

Response type is "application/json".

path Parameters
zoom
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Request Body schema: application/json
required
required
object (MultiGraph)

MultiGraph-specific options are defined in this parent object. For most parameters a default value exists such that mostly only the main configurations, i.e. aggregation.type, serialization.format, and layerType, should be consciously chosen according to requirements.

The underlying process for the MultiGraph calculation is the following:

  1. Routing for each source points (exception: routing_union)
  2. Aggregation of the resulting information (grouped by edges or nodes depending on the layer type) according to the specified aggregation type (and pre- and post-filter configuration).
  3. Serialization of the MultiGraph: The MultiGraph consisting of nodes (and edges) is serialized into the specified form (layerType), e.g. 'edge', 'tile', conforming to the specified format, e.g. 'GeoJSON', 'mvt'.

Array of objects (TargetCore)
showSnapInformation
boolean
Default: false

display information on snap distances in the response. Currently only available for Route, Time and reachability APIs

Array of objects (SourceCore)
Array of objects (SourceGeometry)
edgeWeight
required
string
Default: "time"
Enum: "time" "distance"

Determines the dimension of the edges' weight, i.e. time (distance in seconds) or distance (distance in meters). distance Will optimize for distance and search for the shortest path, time will optimize for time and will search for the fastest path. Distance cannot be used in concert with travelType transit.

maxEdgeWeight
required
integer <int32>
Default: 1800

The maximum distance "depth" of the built network in seconds (for edgeWeight = time) or meters (for edgeWeight = distance). lower max edge weights limit the size of the networked and the area covered, while greater values will increase the time taken to process the request. The upper limit of this variable is based on your subscription plan and differs between distance and time.

elevation
boolean
Default: true

Whether or not the an elevation heuristic will be used (e.g. downhill with bike quicker than uphill).

reverse
boolean
Default: false

If the reverse flag is set to true, the routing algorithm will invert direction restrictions (one way roads, turning restrictions, ect) to simulate a to the source(s). For polygon routing this can be used to calculate the polygon/area that could reach the source(s).

object

Specifies factors with which the travel times of the edges are adjusted. This may be necessary in certain areas where the travel time calculation is almost always off by a certain factor, e.g. Paris rush hour.

"travelTimeFactors" : { "all":0.5, "motorway":1.5, .... (other specific edge classes possible) },..

Further specifics about the TravelTimeFactors:

  • travel time factor of 1.5 means 50% more time is needed
  • travel time factor 'all' is applied to ALL edge classes (on top of a specified one, e.g. for the example above 1.5*0.5=0.75 - the final applied travel time factor for 'motorway' edges)
  • all elements are optional, min allowed cumulative travel time factor is 0.5; maximum allowed cumulative travel time factor is 100.0
  • elements that are not recognized are ignored
  • transit travel times are not affected by the travelTimeFactors
maxSnapDistance
integer
Default: "Endpoint Specific"

This defines the maximum distance allowed (in meters) between a defined source/target and the nearest point in the network it will connect. Any point that has a distance exceeding maxSnapDistance is treated like a point that exceeds maxEdgeWeight.
If set too low points will be unable to snap to any nearby edges, if set too high points set outside the network or where lat/long have been accidentally inverted will be able to snap to the outer edge of the network.

object

The exclusion geometry describes a GeoJSON object that should not be traveled through during the routing calculation. Any edges That intersect with the described geometry will be excluded from the routing. This can be used to simulate temporarily impassible routes or to deliberatley exclude certain ways. Both 'data' and 'crs' must be defined and do not have default values.

Responses

Request samples

Content type
application/json
{
  • "edgeWeight": "time",
  • "maxEdgeWeight": 100,
  • "multigraph": {
    },
  • "sources": [
    ]
}

Tiled MultiGraph as GeoJSON

The MultiGraph request but with the tile and serialization (GeoJSON) already specified as a path parameter (the tile and serialization format in the request body are overwritten).


For the tile format (google) see here.

The MultiGraphRequestConfiguration is URL encoded a query parameter. Response type is "application/json".

path Parameters
zoom
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

cfg
required
string
Default: "{\n \"sources\":[\n {\n \"lat\":52.450411,\n \"lng\":13.4375,\n \"id\":\"1\",\n \"tm\":{\"car\":{}}\n },{\n \"lat\":52.451,\n \"lng\":13.437,\n \"id\":\"2\",\n \"tm\":{\"car\":{}}\n }\n ],\n \"edgeWeight\":\"time\",\n \"maxEdgeWeight\":\"100\",\n \"multigraph\":{\n \"aggregation\":{\"type\":\"routing_union\"}}\n }"

JSON Configuration as query parameter
Please keep in mind that for compatibility, the GET URL recommended maximum size is 2000 chars

Responses

MultiGraph Overview

This method returns overview information for a MultiGraph request:

  • minimal and maximal occurring value
  • result geometry boundaries: southWest and northEast coordinates

This is of interest for (tiled) geometry requests (mvt,geojson). Response type is "application/json".

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Request Body schema: application/json
required
required
object (MultiGraph)

MultiGraph-specific options are defined in this parent object. For most parameters a default value exists such that mostly only the main configurations, i.e. aggregation.type, serialization.format, and layerType, should be consciously chosen according to requirements.

The underlying process for the MultiGraph calculation is the following:

  1. Routing for each source points (exception: routing_union)
  2. Aggregation of the resulting information (grouped by edges or nodes depending on the layer type) according to the specified aggregation type (and pre- and post-filter configuration).
  3. Serialization of the MultiGraph: The MultiGraph consisting of nodes (and edges) is serialized into the specified form (layerType), e.g. 'edge', 'tile', conforming to the specified format, e.g. 'GeoJSON', 'mvt'.

Array of objects (TargetCore)
showSnapInformation
boolean
Default: false

display information on snap distances in the response. Currently only available for Route, Time and reachability APIs

Array of objects (SourceCore)
Array of objects (SourceGeometry)
edgeWeight
required
string
Default: "time"
Enum: "time" "distance"

Determines the dimension of the edges' weight, i.e. time (distance in seconds) or distance (distance in meters). distance Will optimize for distance and search for the shortest path, time will optimize for time and will search for the fastest path. Distance cannot be used in concert with travelType transit.

maxEdgeWeight
required
integer <int32>
Default: 1800

The maximum distance "depth" of the built network in seconds (for edgeWeight = time) or meters (for edgeWeight = distance). lower max edge weights limit the size of the networked and the area covered, while greater values will increase the time taken to process the request. The upper limit of this variable is based on your subscription plan and differs between distance and time.

elevation
boolean
Default: true

Whether or not the an elevation heuristic will be used (e.g. downhill with bike quicker than uphill).

reverse
boolean
Default: false

If the reverse flag is set to true, the routing algorithm will invert direction restrictions (one way roads, turning restrictions, ect) to simulate a to the source(s). For polygon routing this can be used to calculate the polygon/area that could reach the source(s).

object

Specifies factors with which the travel times of the edges are adjusted. This may be necessary in certain areas where the travel time calculation is almost always off by a certain factor, e.g. Paris rush hour.

"travelTimeFactors" : { "all":0.5, "motorway":1.5, .... (other specific edge classes possible) },..

Further specifics about the TravelTimeFactors:

  • travel time factor of 1.5 means 50% more time is needed
  • travel time factor 'all' is applied to ALL edge classes (on top of a specified one, e.g. for the example above 1.5*0.5=0.75 - the final applied travel time factor for 'motorway' edges)
  • all elements are optional, min allowed cumulative travel time factor is 0.5; maximum allowed cumulative travel time factor is 100.0
  • elements that are not recognized are ignored
  • transit travel times are not affected by the travelTimeFactors
maxSnapDistance
integer
Default: "Endpoint Specific"

This defines the maximum distance allowed (in meters) between a defined source/target and the nearest point in the network it will connect. Any point that has a distance exceeding maxSnapDistance is treated like a point that exceeds maxEdgeWeight.
If set too low points will be unable to snap to any nearby edges, if set too high points set outside the network or where lat/long have been accidentally inverted will be able to snap to the outer edge of the network.

object

The exclusion geometry describes a GeoJSON object that should not be traveled through during the routing calculation. Any edges That intersect with the described geometry will be excluded from the routing. This can be used to simulate temporarily impassible routes or to deliberatley exclude certain ways. Both 'data' and 'crs' must be defined and do not have default values.

Responses

Request samples

Content type
application/json
{
  • "edgeWeight": "time",
  • "maxEdgeWeight": 100,
  • "multigraph": {
    },
  • "sources": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "code": "ok",
  • "message": "",
  • "requestTime": "109"
}

MultiGraph Overview

This method returns overview information for a MultiGraph request:

  • minimal and maximal occurring value
  • result geometry boundaries: southWest and northEast coordinates

This is of interest for (tiled) geometry requests (mvt,geojson). Response type is "application/json".

The MultiGraphRequestConfiguration is URL encoded a query parameter.

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

cfg
required
string
Default: "{\n \"sources\":[\n {\n \"lat\":52.450411,\n \"lng\":13.4375,\n \"id\":\"1\",\n \"tm\":{\"car\":{}}\n },\n {\n \"lat\":52.451,\n \"lng\":13.437,\n \"id\":\"2\",\n \"tm\":{\"car\":{}}\n }\n ],\n \"edgeWeight\":\"time\",\n \"maxEdgeWeight\":\"100\",\n \"multigraph\":{\n \"aggregation\":{\"type\":\"routing_union\"}\n }\n}"

JSON Configuration as query parameter
Please keep in mind that for compatibility, the GET URL recommended maximum size is 2000 chars

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "code": "ok",
  • "message": "",
  • "requestTime": "109"
}

Register MultiGraph Requests

When using HTTP GET requests, we are limited by the header length. That length is server and client dependant, (i.e., every HTTP server and client implementation has it's own limits and some allow it to be changed). By convention, the recommendation is a maximum 2000 char GET request, as it is the limit for some web browser implementations.

To permit using Targomo API GET requests with long content inputs, there is the objectcache tool to store the Request Configuration beforehand as a POST request. As response you get an unique id to be used on further GET requests that links the stored request parameters with the request being made.

Object Cache default parameters:
maxEntriesLocalHeap="100000",
timeToIdleSeconds="1800",
timeToLiveSeconds="3600"

This method allows storing on server a Request Configuration

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Request Body schema: application/json
required
One of
serviceKey
required
string

This is the Targomo APi key (serviceKey) that you receive once you are registered at targomo.com/developers.
For other requests this is specified as query parameter.

serviceUrl
required
string

This is the service URL to which the other dependant Targomo requests are dispatched (e.g Targomo Time or Routing requestrs). The endpoint has to correspond to the addresses, e.g. if you want to execute Vehicle Routing in France you need to point to an Targomo Endpoint that includes France geographically.

required
Array of objects (OsmType)
format
string (POIFormat)
Default: "json"
Enum: "json" "geojson"

This optional parameter is currently only used for the Places Context APIs.

Possible values are json, where results will be returned in a single JSON object with the OSM Ids as keys and the properties as values, or GeoJSON.

Array of objects (TargetCore)
showSnapInformation
boolean
Default: false

display information on snap distances in the response. Currently only available for Route, Time and reachability APIs

Array of objects (SourceCore)
Array of objects (SourceGeometry)
edgeWeight
string
Default: "time"
Enum: "time" "distance"

Determines the dimension of the edges' weight, i.e. time (distance in seconds) or distance (distance in meters). distance Will optimize for distance and search for the shortest path, time will optimize for time and will search for the fastest path. Distance cannot be used in concert with travelType transit.

maxEdgeWeight
integer <int32>
Default: 1800

The maximum distance "depth" of the built network in seconds (for edgeWeight = time) or meters (for edgeWeight = distance). lower max edge weights limit the size of the networked and the area covered, while greater values will increase the time taken to process the request. The upper limit of this variable is based on your subscription plan and differs between distance and time.

elevation
boolean
Default: true

Whether or not the an elevation heuristic will be used (e.g. downhill with bike quicker than uphill).

reverse
boolean
Default: false

If the reverse flag is set to true, the routing algorithm will invert direction restrictions (one way roads, turning restrictions, ect) to simulate a to the source(s). For polygon routing this can be used to calculate the polygon/area that could reach the source(s).

object

Specifies factors with which the travel times of the edges are adjusted. This may be necessary in certain areas where the travel time calculation is almost always off by a certain factor, e.g. Paris rush hour.

"travelTimeFactors" : { "all":0.5, "motorway":1.5, .... (other specific edge classes possible) },..

Further specifics about the TravelTimeFactors:

  • travel time factor of 1.5 means 50% more time is needed
  • travel time factor 'all' is applied to ALL edge classes (on top of a specified one, e.g. for the example above 1.5*0.5=0.75 - the final applied travel time factor for 'motorway' edges)
  • all elements are optional, min allowed cumulative travel time factor is 0.5; maximum allowed cumulative travel time factor is 100.0
  • elements that are not recognized are ignored
  • transit travel times are not affected by the travelTimeFactors
maxSnapDistance
integer
Default: "Endpoint Specific"

This defines the maximum distance allowed (in meters) between a defined source/target and the nearest point in the network it will connect. Any point that has a distance exceeding maxSnapDistance is treated like a point that exceeds maxEdgeWeight.
If set too low points will be unable to snap to any nearby edges, if set too high points set outside the network or where lat/long have been accidentally inverted will be able to snap to the outer edge of the network.

object

The exclusion geometry describes a GeoJSON object that should not be traveled through during the routing calculation. Any edges That intersect with the described geometry will be excluded from the routing. This can be used to simulate temporarily impassible routes or to deliberatley exclude certain ways. Both 'data' and 'crs' must be defined and do not have default values.

Responses

Request samples

Content type
application/json
{
  • "edgeWeight": "time",
  • "maxEdgeWeight": 100,
  • "multigraph": {
    },
  • "sources": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 95,
  • "created": 1539193545407,
  • "modified": 1539193545407,
  • "validFor": 3600,
  • "clazz": "com.targomo.core.config.RequestConfiguration",
  • "uuid": "b5050f2c-6a4b-4360-b08b-8b6451f7f733"
}

Places Context API

Analyse the reachability of Points of Interest (POIs) from lists of sources or within geometries and return the resulting visualizations as .mvt or geojson.

POI Reachability

This service returns a list of reachable points of interest (POIs) for a given list of sources coordinates.

Request Body schema: application/json
required

Necessary for this service:

  • One or several sources
  • edgeWeight & maxEdgeWeight
  • serviceUrl & serviceKey
  • One or more osmType
required
Array of objects (Source)
edgeWeight
required
string
Default: "time"
Enum: "time" "distance"

Determines the dimension of the edges' weight, i.e. time (distance in seconds) or distance (distance in meters). distance Will optimize for distance and search for the shortest path, time will optimize for time and will search for the fastest path. Distance cannot be used in concert with travelType transit.

maxEdgeWeight
required
integer <int32>
Default: 1800

The maximum distance "depth" of the built network in seconds (for edgeWeight = time) or meters (for edgeWeight = distance). lower max edge weights limit the size of the networked and the area covered, while greater values will increase the time taken to process the request. The upper limit of this variable is based on your subscription plan and differs between distance and time.

elevation
boolean
Default: true

Whether or not the an elevation heuristic will be used (e.g. downhill with bike quicker than uphill).

object

Specifies factors with which the travel times of the edges are adjusted. This may be necessary in certain areas where the travel time calculation is almost always off by a certain factor, e.g. Paris rush hour.

"travelTimeFactors" : { "all":0.5, "motorway":1.5, .... (other specific edge classes possible) },..

Further specifics about the TravelTimeFactors:

  • travel time factor of 1.5 means 50% more time is needed
  • travel time factor 'all' is applied to ALL edge classes (on top of a specified one, e.g. for the example above 1.5*0.5=0.75 - the final applied travel time factor for 'motorway' edges)
  • all elements are optional, min allowed cumulative travel time factor is 0.5; maximum allowed cumulative travel time factor is 100.0
  • elements that are not recognized are ignored
  • transit travel times are not affected by the travelTimeFactors
reverse
boolean
Default: false

If the reverse flag is set to true, the routing algorithm will invert direction restrictions (one way roads, turning restrictions, ect) to simulate a to the source(s). For polygon routing this can be used to calculate the polygon/area that could reach the source(s).

serviceKey
required
string

This is the Targomo APi key (serviceKey) that you receive once you are registered at targomo.com/developers.
For other requests this is specified as query parameter.

serviceUrl
required
string

This is the service URL to which the other dependant Targomo requests are dispatched (e.g Targomo Time or Routing requestrs). The endpoint has to correspond to the addresses, e.g. if you want to execute Vehicle Routing in France you need to point to an Targomo Endpoint that includes France geographically.

required
Array of OsmType (object) or PoiGroup (object)

List of osm types or POI groups to request.

Array of OsmType (object) or PoiGroup (object)

List of osm types or POI groups to exclude from the response.

match
string (MatchType)
Enum: "any" "all"

Type of match for the combination of tags. match=any (by default if not specified) means that the service will retrieve all POIs that contain at least one tag of the request. match=all means that it will retrieve all POIs that contain all tags of the request.

format
string (POIFormat)
Default: "json"
Enum: "json" "geojson"

This optional parameter is currently only used for the Places Context APIs.

Possible values are json, where results will be returned in a single JSON object with the OSM Ids as keys and the properties as values, or GeoJSON.

object (Filter Geometry)

Geometry with a closed shape. All the POIs returned in the response will be contained in this filter geometry (also known as clip geometry). This geometry can be used for both /reachability and /geometry endpoints.

Responses

Request samples

Content type
application/json
{
  • "sources": [
    ],
  • "elevation": true,
  • "maxEdgeWeight": 200,
  • "edgeWeight": "time",
  • "osmTypes": [
    ],
  • "format": "geojson",
  • "serviceUrl": "https://api.targomo.com/westcentraleurope/",
  • "serviceKey": "__targomo_key_here__"
}

Response samples

Content type
application/json
{
  • "type": "FeatureCollection",
  • "features": [
    ]
}

Register POI Reachability Requests

This service calculates a list of reachable points of interest (POIs) for a given list of source coordinates and returns a uuid that can be used to request the same POIs as mvt tile.

Request Body schema: application/json
required

Necessary for this service:

  • One or several sources
  • edgeWeight & maxEdgeWeight
  • serviceUrl & serviceKey
  • One or more osmType
required
Array of objects (Source)
edgeWeight
required
string
Default: "time"
Enum: "time" "distance"

Determines the dimension of the edges' weight, i.e. time (distance in seconds) or distance (distance in meters). distance Will optimize for distance and search for the shortest path, time will optimize for time and will search for the fastest path. Distance cannot be used in concert with travelType transit.

maxEdgeWeight
required
integer <int32>
Default: 1800

The maximum distance "depth" of the built network in seconds (for edgeWeight = time) or meters (for edgeWeight = distance). lower max edge weights limit the size of the networked and the area covered, while greater values will increase the time taken to process the request. The upper limit of this variable is based on your subscription plan and differs between distance and time.

elevation
boolean
Default: true

Whether or not the an elevation heuristic will be used (e.g. downhill with bike quicker than uphill).

object

Specifies factors with which the travel times of the edges are adjusted. This may be necessary in certain areas where the travel time calculation is almost always off by a certain factor, e.g. Paris rush hour.

"travelTimeFactors" : { "all":0.5, "motorway":1.5, .... (other specific edge classes possible) },..

Further specifics about the TravelTimeFactors:

  • travel time factor of 1.5 means 50% more time is needed
  • travel time factor 'all' is applied to ALL edge classes (on top of a specified one, e.g. for the example above 1.5*0.5=0.75 - the final applied travel time factor for 'motorway' edges)
  • all elements are optional, min allowed cumulative travel time factor is 0.5; maximum allowed cumulative travel time factor is 100.0
  • elements that are not recognized are ignored
  • transit travel times are not affected by the travelTimeFactors
reverse
boolean
Default: false

If the reverse flag is set to true, the routing algorithm will invert direction restrictions (one way roads, turning restrictions, ect) to simulate a to the source(s). For polygon routing this can be used to calculate the polygon/area that could reach the source(s).

serviceKey
required
string

This is the Targomo APi key (serviceKey) that you receive once you are registered at targomo.com/developers.
For other requests this is specified as query parameter.

serviceUrl
required
string

This is the service URL to which the other dependant Targomo requests are dispatched (e.g Targomo Time or Routing requestrs). The endpoint has to correspond to the addresses, e.g. if you want to execute Vehicle Routing in France you need to point to an Targomo Endpoint that includes France geographically.

required
Array of OsmType (object) or PoiGroup (object)

List of osm types or POI groups to request.

Array of OsmType (object) or PoiGroup (object)

List of osm types or POI groups to exclude from the response.

match
string (MatchType)
Enum: "any" "all"

Type of match for the combination of tags. match=any (by default if not specified) means that the service will retrieve all POIs that contain at least one tag of the request. match=all means that it will retrieve all POIs that contain all tags of the request.

format
string (POIFormat)
Default: "json"
Enum: "json" "geojson"

This optional parameter is currently only used for the Places Context APIs.

Possible values are json, where results will be returned in a single JSON object with the OSM Ids as keys and the properties as values, or GeoJSON.

object (Filter Geometry)

Geometry with a closed shape. All the POIs returned in the response will be contained in this filter geometry (also known as clip geometry). This geometry can be used for both /reachability and /geometry endpoints.

Responses

Request samples

Content type
application/json
{
  • "sources": [
    ],
  • "elevation": true,
  • "maxEdgeWeight": 200,
  • "edgeWeight": "time",
  • "osmTypes": [
    ],
  • "format": "geojson",
  • "serviceUrl": "https://api.targomo.com/westcentraleurope/",
  • "serviceKey": "__targomo_key_here__"
}

Response samples

Content type
text/plain
230ef01e-7701-41d1-8340-aa9848f97620

POI Reachability as MVT from UUID

This service returns an MVT of reachable points of interest (POIs) for a given uuid corresponding to an already registered reachability configuration (reachability/register). The POIs can be requested as nodes.
This interface allows easy integration into MapboxGL. For the tile format (google) see here.

Response type is "application/octet-stream".

Necessary for this service: uuid + apiKey

path Parameters
zoom
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

uuid
required
string
Example: c4cc1624-5baf-48d2-b284-d2d5718d80c9

Uuid of a registered request

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

loadAllTags
boolean
Default: false

Whether or not to retrieve all tags of the POIs.

layerGeometryDetailPerTile
integer
Example: layerGeometryDetailPerTile=7

Difference between the zoom level of the map and the one used to build the geometries.

layerMinGeometryDetailLevel
integer
Example: layerMinGeometryDetailLevel=7

Minimum zoom level used to build the geometries.

layerMaxGeometryDetailLevel
integer
Example: layerMaxGeometryDetailLevel=28

Maximum zoom level used to build the geometries.

maxGeometryCount
integer
Example: maxGeometryCount=100000

Maximum number of geometries in a tile.

Responses

POI Reachability as GeoJSON from UUID

This service returns an mvt tile of reachable points of interest (POIs) of an already registered reachability configuration. The POIs can be requested as nodes.
This interface allows easy integration into MapboxGL. For the tile format (google) see here.

Response type is "application/json".

Necessary for this service: uuid + apiKey

path Parameters
zoom
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

uuid
required
string
Example: c4cc1624-5baf-48d2-b284-d2d5718d80c9

Uuid of a registered request

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

loadAllTags
boolean
Default: false

Whether or not to retrieve all tags of the POIs.

layerGeometryDetailPerTile
integer
Example: layerGeometryDetailPerTile=7

Difference between the zoom level of the map and the one used to build the geometries.

layerMinGeometryDetailLevel
integer
Example: layerMinGeometryDetailLevel=7

Minimum zoom level used to build the geometries.

layerMaxGeometryDetailLevel
integer
Example: layerMaxGeometryDetailLevel=28

Maximum zoom level used to build the geometries.

maxGeometryCount
integer
Example: maxGeometryCount=100000

Maximum number of geometries in a tile.

Responses

POI Reachability as MVT

This service returns an MVT tile of reachable points of interest (POIs) for a given list of source coordinates. The POIs can be requested as nodes.
This interface allows easy integration into MapboxGL. For the tile format (google) see here.

Response type is "application/octet-stream".

Necessary for this service: cfg

path Parameters
zoom
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

query Parameters
cfg
required
string
Example: cfg={ "sources": [ { "id": "1", "lat": 52.531156, "lng": 13.422760, "tm": { "bike": {} } }, { "lat":52.518388, "lng":13.400917, "id":"2", "tm":{ "bike":{} } } ], "elevation": true, "maxEdgeWeight": 500, "edgeWeight": "time", "osmTypes": [ { "key": "amenity", "value": "bar" }, { "key": "group", "value": "g_electro" } ], "format": "geojson", "serviceUrl": "https://api.targomo.com/westcentraleurope/", "serviceKey": "__targomo_key_here__", "filterGeometry": { "crs": 4326, "type": "geojson", "data": "{\"type\":\"Polygon\",\"coordinates\":[[[13.4108,52.5140],[13.3951,52.5297],[13.4379,52.525],[13.4358,52.5089],[13.4108,52.5140]]]}" } }

JSON Configuration as query parameter. Should follow ReachabilityRequestConfiguration format (See here) or GeometryRequestConfiguration format (See here).

loadAllTags
boolean
Default: false

Whether or not to retrieve all tags of the POIs.

layerGeometryDetailPerTile
integer
Example: layerGeometryDetailPerTile=7

Difference between the zoom level of the map and the one used to build the geometries.

layerMinGeometryDetailLevel
integer
Example: layerMinGeometryDetailLevel=7

Minimum zoom level used to build the geometries.

layerMaxGeometryDetailLevel
integer
Example: layerMaxGeometryDetailLevel=28

Maximum zoom level used to build the geometries.

maxGeometryCount
integer
Example: maxGeometryCount=100000

Maximum number of geometries in a tile.

Responses

POI Reachability as GeoJSON

This service returns an mvt tile of reachable points of interest (POIs) for a given list of source coordinates. The POIs can be requested as nodes.
This interface allows easy integration into MapboxGL. For the tile format (google) see here.

Response type is "application/json".

Necessary for this service: cfg

path Parameters
zoom
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

query Parameters
cfg
required
string
Example: cfg={ "sources": [ { "id": "1", "lat": 52.531156, "lng": 13.422760, "tm": { "bike": {} } }, { "lat":52.518388, "lng":13.400917, "id":"2", "tm":{ "bike":{} } } ], "elevation": true, "maxEdgeWeight": 500, "edgeWeight": "time", "osmTypes": [ { "key": "amenity", "value": "bar" }, { "key": "group", "value": "g_electro" } ], "format": "geojson", "serviceUrl": "https://api.targomo.com/westcentraleurope/", "serviceKey": "__targomo_key_here__", "filterGeometry": { "crs": 4326, "type": "geojson", "data": "{\"type\":\"Polygon\",\"coordinates\":[[[13.4108,52.5140],[13.3951,52.5297],[13.4379,52.525],[13.4358,52.5089],[13.4108,52.5140]]]}" } }

JSON Configuration as query parameter. Should follow ReachabilityRequestConfiguration format (See here) or GeometryRequestConfiguration format (See here).

loadAllTags
boolean
Default: false

Whether or not to retrieve all tags of the POIs.

layerGeometryDetailPerTile
integer
Example: layerGeometryDetailPerTile=7

Difference between the zoom level of the map and the one used to build the geometries.

layerMinGeometryDetailLevel
integer
Example: layerMinGeometryDetailLevel=7

Minimum zoom level used to build the geometries.

layerMaxGeometryDetailLevel
integer
Example: layerMaxGeometryDetailLevel=28

Maximum zoom level used to build the geometries.

maxGeometryCount
integer
Example: maxGeometryCount=100000

Maximum number of geometries in a tile.

Responses

POI Reachability Summary

This service returns a summary of the reachable points of interest (POIs) for a given list of sources coordinates.

Request Body schema: application/json
required

Necessary for this service:

  • One or several sources
  • edgeWeight & maxEdgeWeight
  • serviceUrl & serviceKey
  • One or more osmType
required
Array of objects (Source)
edgeWeight
required
string
Default: "time"
Enum: "time" "distance"

Determines the dimension of the edges' weight, i.e. time (distance in seconds) or distance (distance in meters). distance Will optimize for distance and search for the shortest path, time will optimize for time and will search for the fastest path. Distance cannot be used in concert with travelType transit.

maxEdgeWeight
required
integer <int32>
Default: 1800

The maximum distance "depth" of the built network in seconds (for edgeWeight = time) or meters (for edgeWeight = distance). lower max edge weights limit the size of the networked and the area covered, while greater values will increase the time taken to process the request. The upper limit of this variable is based on your subscription plan and differs between distance and time.

elevation
boolean
Default: true

Whether or not the an elevation heuristic will be used (e.g. downhill with bike quicker than uphill).

object

Specifies factors with which the travel times of the edges are adjusted. This may be necessary in certain areas where the travel time calculation is almost always off by a certain factor, e.g. Paris rush hour.

"travelTimeFactors" : { "all":0.5, "motorway":1.5, .... (other specific edge classes possible) },..

Further specifics about the TravelTimeFactors:

  • travel time factor of 1.5 means 50% more time is needed
  • travel time factor 'all' is applied to ALL edge classes (on top of a specified one, e.g. for the example above 1.5*0.5=0.75 - the final applied travel time factor for 'motorway' edges)
  • all elements are optional, min allowed cumulative travel time factor is 0.5; maximum allowed cumulative travel time factor is 100.0
  • elements that are not recognized are ignored
  • transit travel times are not affected by the travelTimeFactors
reverse
boolean
Default: false

If the reverse flag is set to true, the routing algorithm will invert direction restrictions (one way roads, turning restrictions, ect) to simulate a to the source(s). For polygon routing this can be used to calculate the polygon/area that could reach the source(s).

serviceKey
required
string

This is the Targomo APi key (serviceKey) that you receive once you are registered at targomo.com/developers.
For other requests this is specified as query parameter.

serviceUrl
required
string

This is the service URL to which the other dependant Targomo requests are dispatched (e.g Targomo Time or Routing requestrs). The endpoint has to correspond to the addresses, e.g. if you want to execute Vehicle Routing in France you need to point to an Targomo Endpoint that includes France geographically.

required
Array of OsmType (object) or PoiGroup (object)

List of osm types or POI groups to request.

Array of OsmType (object) or PoiGroup (object)

List of osm types or POI groups to exclude from the response.

match
string (MatchType)
Enum: "any" "all"

Type of match for the combination of tags. match=any (by default if not specified) means that the service will retrieve all POIs that contain at least one tag of the request. match=all means that it will retrieve all POIs that contain all tags of the request.

format
string (POIFormat)
Default: "json"
Enum: "json" "geojson"

This optional parameter is currently only used for the Places Context APIs.

Possible values are json, where results will be returned in a single JSON object with the OSM Ids as keys and the properties as values, or GeoJSON.

object (Filter Geometry)

Geometry with a closed shape. All the POIs returned in the response will be contained in this filter geometry (also known as clip geometry). This geometry can be used for both /reachability and /geometry endpoints.

Responses

Request samples

Content type
application/json
{
  • "sources": [
    ],
  • "elevation": true,
  • "maxEdgeWeight": 200,
  • "edgeWeight": "time",
  • "osmTypes": [
    ],
  • "format": "geojson",
  • "serviceUrl": "https://api.targomo.com/westcentraleurope/",
  • "serviceKey": "__targomo_key_here__"
}

Response samples

Content type
application/json
{
  • "totalPoi": 17,
  • "osmTypeCount": {
    },
  • "groupIdCount": {
    },
  • "clusterIdCount": {
    }
}

Registered POI Summary

This service returns a summary of the reachable points of interest (POIs) for an already registered reachability request.

path Parameters
uuid
required
string
Example: c4cc1624-5baf-48d2-b284-d2d5718d80c9

Uuid of a registered request

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Responses

Response samples

Content type
application/json
{
  • "totalPoi": 17,
  • "osmTypeCount": {
    },
  • "groupIdCount": {
    },
  • "clusterIdCount": {
    }
}

POIs Within Geometry

This service returns a list of reachable points of interest (POIs) within a given geometry.

Request Body schema: application/json
required

Necessary for this service:

  • One closed shape geometry
  • One or more osmType
serviceKey
required
string

This is the Targomo APi key (serviceKey) that you receive once you are registered at targomo.com/developers.
For other requests this is specified as query parameter.

serviceUrl
required
string

This is the service URL to which the other dependant Targomo requests are dispatched (e.g Targomo Time or Routing requestrs). The endpoint has to correspond to the addresses, e.g. if you want to execute Vehicle Routing in France you need to point to an Targomo Endpoint that includes France geographically.

required
Array of OsmType (object) or PoiGroup (object)

List of osm types or POI groups to request.

Array of OsmType (object) or PoiGroup (object)

List of osm types or POI groups to exclude from the response.

match
string (MatchType)
Enum: "any" "all"

Type of match for the combination of tags. match=any (by default if not specified) means that the service will retrieve all POIs that contain at least one tag of the request. match=all means that it will retrieve all POIs that contain all tags of the request.

format
string (POIFormat)
Default: "json"
Enum: "json" "geojson"

This optional parameter is currently only used for the Places Context APIs.

Possible values are json, where results will be returned in a single JSON object with the OSM Ids as keys and the properties as values, or GeoJSON.

required
object (Filter Geometry)

Geometry with a closed shape. All the POIs returned in the response will be contained in this filter geometry (also known as clip geometry). This geometry can be used for both /reachability and /geometry endpoints.

Responses

Request samples

Content type
application/json
{
  • "osmTypes": [
    ],
  • "format": "geojson",
  • "filterGeometry": {
    }
}

Response samples

Content type
application/json
{
  • "type": "FeatureCollection",
  • "features": [
    ]
}

Register POI Within Geometry Requests

This service calculates a list of reachable points of interest (POIs) within a given geometry and returns a uuid that can be used to request the same POIs as mvt tile.

Request Body schema: application/json
required

Necessary for this service:

  • One closed shape geometry
  • One or more osmType
serviceKey
required
string

This is the Targomo APi key (serviceKey) that you receive once you are registered at targomo.com/developers.
For other requests this is specified as query parameter.

serviceUrl
required
string

This is the service URL to which the other dependant Targomo requests are dispatched (e.g Targomo Time or Routing requestrs). The endpoint has to correspond to the addresses, e.g. if you want to execute Vehicle Routing in France you need to point to an Targomo Endpoint that includes France geographically.

required
Array of OsmType (object) or PoiGroup (object)

List of osm types or POI groups to request.

Array of OsmType (object) or PoiGroup (object)

List of osm types or POI groups to exclude from the response.

match
string (MatchType)
Enum: "any" "all"

Type of match for the combination of tags. match=any (by default if not specified) means that the service will retrieve all POIs that contain at least one tag of the request. match=all means that it will retrieve all POIs that contain all tags of the request.

format
string (POIFormat)
Default: "json"
Enum: "json" "geojson"

This optional parameter is currently only used for the Places Context APIs.

Possible values are json, where results will be returned in a single JSON object with the OSM Ids as keys and the properties as values, or GeoJSON.

required
object (Filter Geometry)

Geometry with a closed shape. All the POIs returned in the response will be contained in this filter geometry (also known as clip geometry). This geometry can be used for both /reachability and /geometry endpoints.

Responses

Request samples

Content type
application/json
{
  • "osmTypes": [
    ],
  • "format": "geojson",
  • "filterGeometry": {
    }
}

Response samples

Content type
text/plain
230ef01e-7701-41d1-8340-aa9848f97620

POIs Within Geometry as MVT

This service returns an MVT tile of points of interest (POIs) for a given uuid corresponding to an already registered geometry configuration (geometry/register). The POIs can be requested as nodes.
This interface allows easy integration into MapboxGL. For the tile format (google) see here.

Response type is "application/octet-stream".

Necessary for this service: uuid + apiKey

path Parameters
zoom
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

uuid
required
string
Example: c4cc1624-5baf-48d2-b284-d2d5718d80c9

Uuid of a registered request

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

loadAllTags
boolean
Default: false

Whether or not to retrieve all tags of the POIs.

layerGeometryDetailPerTile
integer
Example: layerGeometryDetailPerTile=7

Difference between the zoom level of the map and the one used to build the geometries.

layerMinGeometryDetailLevel
integer
Example: layerMinGeometryDetailLevel=7

Minimum zoom level used to build the geometries.

layerMaxGeometryDetailLevel
integer
Example: layerMaxGeometryDetailLevel=28

Maximum zoom level used to build the geometries.

maxGeometryCount
integer
Example: maxGeometryCount=100000

Maximum number of geometries in a tile.

Responses

POIs Within Geometry as GeoJSON

This service returns an mvt tile of reachable points of interest (POIs) an already registered geometry configuration. The POIs can be requested as nodes.
This interface allows easy integration into MapboxGL. For the tile format (google) see here.

Response type is "application/json".

Necessary for this service: uuid + apiKey

path Parameters
zoom
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

uuid
required
string
Example: c4cc1624-5baf-48d2-b284-d2d5718d80c9

Uuid of a registered request

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

loadAllTags
boolean
Default: false

Whether or not to retrieve all tags of the POIs.

layerGeometryDetailPerTile
integer
Example: layerGeometryDetailPerTile=7

Difference between the zoom level of the map and the one used to build the geometries.

layerMinGeometryDetailLevel
integer
Example: layerMinGeometryDetailLevel=7

Minimum zoom level used to build the geometries.

layerMaxGeometryDetailLevel
integer
Example: layerMaxGeometryDetailLevel=28

Maximum zoom level used to build the geometries.

maxGeometryCount
integer
Example: maxGeometryCount=100000

Maximum number of geometries in a tile.

Responses

POIs From Geometry as mvt

This service returns an mvt tile of points of interest (POIs) within a given geometry. The POIs can be requested as nodes.
This interface allows easy integration into MapboxGL. For the tile format (google) see here.

Response type is "application/octet-stream".

Necessary for this service: cfg

path Parameters
zoom
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

query Parameters
cfg
required
string
Example: cfg={ "sources": [ { "id": "1", "lat": 52.531156, "lng": 13.422760, "tm": { "bike": {} } }, { "lat":52.518388, "lng":13.400917, "id":"2", "tm":{ "bike":{} } } ], "elevation": true, "maxEdgeWeight": 500, "edgeWeight": "time", "osmTypes": [ { "key": "amenity", "value": "bar" }, { "key": "group", "value": "g_electro" } ], "format": "geojson", "serviceUrl": "https://api.targomo.com/westcentraleurope/", "serviceKey": "__targomo_key_here__", "filterGeometry": { "crs": 4326, "type": "geojson", "data": "{\"type\":\"Polygon\",\"coordinates\":[[[13.4108,52.5140],[13.3951,52.5297],[13.4379,52.525],[13.4358,52.5089],[13.4108,52.5140]]]}" } }

JSON Configuration as query parameter. Should follow ReachabilityRequestConfiguration format (See here) or GeometryRequestConfiguration format (See here).

loadAllTags
boolean
Default: false

Whether or not to retrieve all tags of the POIs.

layerGeometryDetailPerTile
integer
Example: layerGeometryDetailPerTile=7

Difference between the zoom level of the map and the one used to build the geometries.

layerMinGeometryDetailLevel
integer
Example: layerMinGeometryDetailLevel=7

Minimum zoom level used to build the geometries.

layerMaxGeometryDetailLevel
integer
Example: layerMaxGeometryDetailLevel=28

Maximum zoom level used to build the geometries.

maxGeometryCount
integer
Example: maxGeometryCount=100000

Maximum number of geometries in a tile.

Responses

POIs From Geometry as GeoJSON

This service returns an mvt tile of points of interest (POIs) within a given geometry. The POIs can be requested as nodes.
This interface allows easy integration into MapboxGL. For the tile format (google) see here.

Response type is "application/json".

Necessary for this service: cfg

path Parameters
zoom
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

query Parameters
cfg
required
string
Example: cfg={ "sources": [ { "id": "1", "lat": 52.531156, "lng": 13.422760, "tm": { "bike": {} } }, { "lat":52.518388, "lng":13.400917, "id":"2", "tm":{ "bike":{} } } ], "elevation": true, "maxEdgeWeight": 500, "edgeWeight": "time", "osmTypes": [ { "key": "amenity", "value": "bar" }, { "key": "group", "value": "g_electro" } ], "format": "geojson", "serviceUrl": "https://api.targomo.com/westcentraleurope/", "serviceKey": "__targomo_key_here__", "filterGeometry": { "crs": 4326, "type": "geojson", "data": "{\"type\":\"Polygon\",\"coordinates\":[[[13.4108,52.5140],[13.3951,52.5297],[13.4379,52.525],[13.4358,52.5089],[13.4108,52.5140]]]}" } }

JSON Configuration as query parameter. Should follow ReachabilityRequestConfiguration format (See here) or GeometryRequestConfiguration format (See here).

loadAllTags
boolean
Default: false

Whether or not to retrieve all tags of the POIs.

layerGeometryDetailPerTile
integer
Example: layerGeometryDetailPerTile=7

Difference between the zoom level of the map and the one used to build the geometries.

layerMinGeometryDetailLevel
integer
Example: layerMinGeometryDetailLevel=7

Minimum zoom level used to build the geometries.

layerMaxGeometryDetailLevel
integer
Example: layerMaxGeometryDetailLevel=28

Maximum zoom level used to build the geometries.

maxGeometryCount
integer
Example: maxGeometryCount=100000

Maximum number of geometries in a tile.

Responses

POIs From Geometry Summary

This service returns a summary of the points of interest (POIs) within a given geometry.

Request Body schema: application/json
required

Necessary for this service:

  • One closed shape geometry
  • One or more osmType
serviceKey
required
string

This is the Targomo APi key (serviceKey) that you receive once you are registered at targomo.com/developers.
For other requests this is specified as query parameter.

serviceUrl
required
string

This is the service URL to which the other dependant Targomo requests are dispatched (e.g Targomo Time or Routing requestrs). The endpoint has to correspond to the addresses, e.g. if you want to execute Vehicle Routing in France you need to point to an Targomo Endpoint that includes France geographically.

required
Array of OsmType (object) or PoiGroup (object)

List of osm types or POI groups to request.

Array of OsmType (object) or PoiGroup (object)

List of osm types or POI groups to exclude from the response.

match
string (MatchType)
Enum: "any" "all"

Type of match for the combination of tags. match=any (by default if not specified) means that the service will retrieve all POIs that contain at least one tag of the request. match=all means that it will retrieve all POIs that contain all tags of the request.

format
string (POIFormat)
Default: "json"
Enum: "json" "geojson"

This optional parameter is currently only used for the Places Context APIs.

Possible values are json, where results will be returned in a single JSON object with the OSM Ids as keys and the properties as values, or GeoJSON.

required
object (Filter Geometry)

Geometry with a closed shape. All the POIs returned in the response will be contained in this filter geometry (also known as clip geometry). This geometry can be used for both /reachability and /geometry endpoints.

Responses

Request samples

Content type
application/json
{
  • "osmTypes": [
    ],
  • "format": "geojson",
  • "filterGeometry": {
    }
}

Response samples

Content type
application/json
{
  • "totalPoi": 17,
  • "osmTypeCount": {
    },
  • "groupIdCount": {
    },
  • "clusterIdCount": {
    }
}

POIs From Geometry Summary

This service returns a summary of the reachable points of interest (POIs) for an already registered geometry request.

path Parameters
uuid
required
string
Example: c4cc1624-5baf-48d2-b284-d2d5718d80c9

Uuid of a registered request

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Responses

Response samples

Content type
application/json
{
  • "totalPoi": 17,
  • "osmTypeCount": {
    },
  • "groupIdCount": {
    },
  • "clusterIdCount": {
    }
}

POIs Information

This request retrieves the info of a list of POIs from their Ids.

Nomenclature of the ids:
0_ means that the requested POI is a node.
1_ means that the requested POI is a way (a line or a polygon).
Theses prefixes are followed by the id of the object in the OSM database.
If the id is negative, it means that the node or the way derives from a relation.

Response type is "application/json".

path Parameters
poiIds
required
Array of strings
Example: 0_502545685,1_23971045,1_-2925020

List of POI Ids

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Responses

POI Service OSM Keys

This request returns a list of OSM keys that the service accepts in its requests.

Response type is "application/json".

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Responses

Response samples

Content type
application/json
[
  • "shop",
  • "amenity",
  • "historic"
]

OSM Tags

This request returns all OSM tag values of the requested tagKey that exist in the Places Layers and Places Context API database.

Response type is "application/json".

path Parameters
tagKey
required
string
Example: shop

OSM key that is supported by the service.

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

text
string
Example: text=b

A suggested term to which the results will be similar.

limit
integer
Example: limit=20

Maximum number of results retrieved by the service.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

POI Service Hierarchy

This request returns the POI hierarchy supported by the service. The POI Hierarchy is a tree of POI groups that one can use to request groups of POI by their ids.

Response type is "application/json".

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Responses

Response samples

Content type
application/json
{
  • "id": "g_shop",
  • "type": "CATEGORY",
  • "name": "Shopping",
  • "description": "Places where to shop",
  • "contents": [
    ]
}

Statistics Context API

Retrieve information on available statistics such as basic metadata and simple aggregations or perform statistics based reachability requests.

Charts Dependent

This method takes as input a list of sources, a statisticColllectionId and a list of statisticIds. With the points derived from the statistics data representing the "targets", the API calculates the reachability according to statistics considered.

For example, if the input statistic is total population, the API will calculate the population that would be reached for incremental travel times (e.g. population reachable within 5, 10 and 15 minutes).

This service is characterized by choosing for each statistic point the closest source to assign the statistic data, which makes the returned charts source dependent.

query Parameters
serviceUrl
string
Example: serviceUrl=https://api.targomo.com/westcentraleurope

defines the core api server address to be used

apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Request Body schema: application/json
statisticCollectionId
integer

The Statistic Collection to be used as data source

statisticIds
Array of integers

List with statistic ids used for reachability calculation

edgeWeight
string
Default: "time"
Enum: "time" "distance"

Determines the dimension of the edges' weight, i.e. time (distance in seconds) or distance (distance in meters). distance Will optimize for distance and search for the shortest path, time will optimize for time and will search for the fastest path. Distance cannot be used in concert with travelType transit.

maxEdgeWeight
integer <int32>
Default: 1800

The maximum distance "depth" of the built network in seconds (for edgeWeight = time) or meters (for edgeWeight = distance). lower max edge weights limit the size of the networked and the area covered, while greater values will increase the time taken to process the request. The upper limit of this variable is based on your subscription plan and differs between distance and time.

travelType
string
Enum: "walk" "bike" "car" "fly"

The Mode of Transportation used by the Targomo API

bikeSpeed
number <double>
Default: 18

Assumed speed in km/h

bikeUphill
number <double>
Default: 20

Uphill penalty specifies by how much a distance is enhanced per one meter increase in elevation.

E.g. an uphill penalty of 20 means that per one meter increase in elevation the distance is increased by 20 meters.

bikeDownhill
number <double>
Default: -10

Same like uphill but for downhill (might be negative because the distance can be closed quicker when downhill)

walkSpeed
number <double>
Default: 5

Assumed speed in km/h

walkUphill
number <double>
Default: 10

Uphill penalty specifies by how much a distance is enhanced per one meter increase in elevation.

E.g. an uphill penalty of 20 means that per one meter increase in elevation the distance is increased by 20 meters.

walkDownhill
number <double>
Default: 0

Same like uphill but for downhill (might be negative because the distance can be closed quicker when downhill)

rushHour
boolean

Enable the rush hour mode to simulate a more crowded street.
Warning this is a paid feature so not all plans are allowed to enable it.
If at least one of the parameters date and time is set, the driving speed will be adjusted according to the time and the day of the week. In this case the rushHour flag will be ignored.

trafficJunctionPenalty
integer
Default: 4

Penalty (in seconds) for routing over a junction. All penalties are halved when staying on the main road.

trafficSignalPenalty
integer
Default: 11

Penalty (in seconds) for routing over a signal. All penalties are halved when staying on the main road.

trafficLeftTurnPenalty
integer
Default: 7

Penalty (in seconds) for turning left. All penalties are halved when staying on the main road.
The default is 4 for the endpoints britishisles, australia, africa_middle_east, and asia.

trafficRightTurnPenalty
integer
Default: 4

Penalty (in seconds) for turning right. All penalties are halved when staying on the main road.
The default is 7 for the endpoints britishisles and australia.

reverse
boolean
Default: false

If the reverse flag is set to true, the routing algorithm will invert direction restrictions (one way roads, turning restrictions, ect) to simulate a to the source(s). For polygon routing this can be used to calculate the polygon/area that could reach the source(s).

elevationEnabled
boolean
Default: true

Whether or not the an elevation heuristic will be used (e.g. downhill with bike quicker than uphill).

allowPrivateAndServiceRoads
boolean
Default: false

If true, this will allow the core service to route on edges marked as private or on service roads (which are normally blocked for cars).

arrivalOrDepartureDuration
integer
Default: 0

If set to a value >0 the entering of the transit at the first stop (if reverse is false) will be limited to the time frame between time and time+arrivalOrDepartureDuration. If reverse is true, leaving of the transit at the last stop will be limited instead (between time and time-arrivalOrDepartureDuration).

iFeelLucky
boolean
Default: false
getClosestSources
boolean
Default: false
omitIndividualStatistics
boolean
Default: false

if true, omits the individualStatistics response section

serviceKey
string

This is the Targomo APi key (serviceKey) that you receive once you are registered at targomo.com/developers.
For other requests this is specified as query parameter.

serviceUrl
string

This is the service URL to which the other dependant Targomo requests are dispatched (e.g Targomo Time or Routing requestrs). The endpoint has to correspond to the addresses, e.g. if you want to execute Vehicle Routing in France you need to point to an Targomo Endpoint that includes France geographically.

Array of objects (sourceWithTravelType)
Array of objects (sourceGeometryWithTravelType)
Array of objects (targets)
Array of objects (sourceWithTravelType)
object (ClipGeometry)

Define a geometry (Polygon/MultiPolygon) to clip the charts, multigraph and reachability responses.

Responses

Request samples

Content type
application/json
{
  • "statisticIds": [
    ],
  • "serviceUrl": "https://api.targomo.com/westcentraleurope",
  • "serviceKey": "__targomo_key_here__",
  • "statisticCollectionId": 100,
  • "edgeWeight": "distance",
  • "travelType": "car",
  • "maxEdgeWeight": 100,
  • "iFeelLucky": false,
  • "getClosestSources": false,
  • "omitIndividualStatistics": false,
  • "sources": [
    ]
}

Response samples

Content type
application/json
{
  • "statistics": {
    },
  • "reachableTargets": {
    },
  • "closestSourceIds": { },
  • "individualStatistics": {
    }
}

Charts Independent

This method takes as input a list of sources, a statisticColllectionId and a list of statisticIds. With the points derived from the statistics data representing the "targets", the API calculates the reachability according to statistics considered.

For example, if the input statistic is total population, the API will calculate the population that would be reached for incremental travel times (e.g. population reachable within 5, 10 and 15 minutes).

Unlike the charts/dependent service, this services calculates statistics independently for each source. Thus, if a statistic coordinate is reachable by two or more source points, it will be accounted for both.

query Parameters
serviceUrl
string
Example: serviceUrl=https://api.targomo.com/westcentraleurope

defines the core api server address to be used

apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Request Body schema: application/json
statisticCollectionId
integer

The Statistic Collection to be used as data source

statisticIds
Array of integers

List with statistic ids used for reachability calculation

edgeWeight
string
Default: "time"
Enum: "time" "distance"

Determines the dimension of the edges' weight, i.e. time (distance in seconds) or distance (distance in meters). distance Will optimize for distance and search for the shortest path, time will optimize for time and will search for the fastest path. Distance cannot be used in concert with travelType transit.

maxEdgeWeight
integer <int32>
Default: 1800

The maximum distance "depth" of the built network in seconds (for edgeWeight = time) or meters (for edgeWeight = distance). lower max edge weights limit the size of the networked and the area covered, while greater values will increase the time taken to process the request. The upper limit of this variable is based on your subscription plan and differs between distance and time.

travelType
string
Enum: "walk" "bike" "car" "fly"

The Mode of Transportation used by the Targomo API

bikeSpeed
number <double>
Default: 18

Assumed speed in km/h

bikeUphill
number <double>
Default: 20

Uphill penalty specifies by how much a distance is enhanced per one meter increase in elevation.

E.g. an uphill penalty of 20 means that per one meter increase in elevation the distance is increased by 20 meters.

bikeDownhill
number <double>
Default: -10

Same like uphill but for downhill (might be negative because the distance can be closed quicker when downhill)

walkSpeed
number <double>
Default: 5

Assumed speed in km/h

walkUphill
number <double>
Default: 10

Uphill penalty specifies by how much a distance is enhanced per one meter increase in elevation.

E.g. an uphill penalty of 20 means that per one meter increase in elevation the distance is increased by 20 meters.

walkDownhill
number <double>
Default: 0

Same like uphill but for downhill (might be negative because the distance can be closed quicker when downhill)

rushHour
boolean

Enable the rush hour mode to simulate a more crowded street.
Warning this is a paid feature so not all plans are allowed to enable it.
If at least one of the parameters date and time is set, the driving speed will be adjusted according to the time and the day of the week. In this case the rushHour flag will be ignored.

trafficJunctionPenalty
integer
Default: 4

Penalty (in seconds) for routing over a junction. All penalties are halved when staying on the main road.

trafficSignalPenalty
integer
Default: 11

Penalty (in seconds) for routing over a signal. All penalties are halved when staying on the main road.

trafficLeftTurnPenalty
integer
Default: 7

Penalty (in seconds) for turning left. All penalties are halved when staying on the main road.
The default is 4 for the endpoints britishisles, australia, africa_middle_east, and asia.

trafficRightTurnPenalty
integer
Default: 4

Penalty (in seconds) for turning right. All penalties are halved when staying on the main road.
The default is 7 for the endpoints britishisles and australia.

reverse
boolean
Default: false

If the reverse flag is set to true, the routing algorithm will invert direction restrictions (one way roads, turning restrictions, ect) to simulate a to the source(s). For polygon routing this can be used to calculate the polygon/area that could reach the source(s).

elevationEnabled
boolean
Default: true

Whether or not the an elevation heuristic will be used (e.g. downhill with bike quicker than uphill).

allowPrivateAndServiceRoads
boolean
Default: false

If true, this will allow the core service to route on edges marked as private or on service roads (which are normally blocked for cars).

arrivalOrDepartureDuration
integer
Default: 0

If set to a value >0 the entering of the transit at the first stop (if reverse is false) will be limited to the time frame between time and time+arrivalOrDepartureDuration. If reverse is true, leaving of the transit at the last stop will be limited instead (between time and time-arrivalOrDepartureDuration).

iFeelLucky
boolean
Default: false
getClosestSources
boolean
Default: false
omitIndividualStatistics
boolean
Default: false

if true, omits the individualStatistics response section

serviceKey
string

This is the Targomo APi key (serviceKey) that you receive once you are registered at targomo.com/developers.
For other requests this is specified as query parameter.

serviceUrl
string

This is the service URL to which the other dependant Targomo requests are dispatched (e.g Targomo Time or Routing requestrs). The endpoint has to correspond to the addresses, e.g. if you want to execute Vehicle Routing in France you need to point to an Targomo Endpoint that includes France geographically.

Array of objects (sourceWithTravelType)
Array of objects (sourceGeometryWithTravelType)
Array of objects (targets)
Array of objects (sourceWithTravelType)
object (ClipGeometry)

Define a geometry (Polygon/MultiPolygon) to clip the charts, multigraph and reachability responses.

Responses

Request samples

Content type
application/json
{
  • "statisticIds": [
    ],
  • "serviceUrl": "https://api.targomo.com/westcentraleurope",
  • "serviceKey": "__targomo_key_here__",
  • "statisticCollectionId": 100,
  • "edgeWeight": "distance",
  • "travelType": "car",
  • "maxEdgeWeight": 100,
  • "iFeelLucky": false,
  • "getClosestSources": false,
  • "omitIndividualStatistics": false,
  • "sources": [
    ]
}

Response samples

Content type
application/json
{
  • "statistics": {
    },
  • "reachableTargets": {
    },
  • "closestSourceIds": { },
  • "individualStatistics": {
    }
}

Geometry Statistic Values

This service retrieves a list of statistic data aggregated by one of the following functions:

  • Min value (min)
  • Max value (max)
  • Average (avg)
  • Sum (sum)
  • Count (count)
  • Standard deviation (stddev)
  • Variance (variance)

As result, this service calculates the response using the given aggregation function from all statistic points inside the given geometry. If no aggregation function is given, the sum function is used as default.

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

aggregations
Array of strings

If provided, this parameter must contain one aggregation per StatisticId The parameter value should be formatted as:

statisticId-[min|max|avg|sum|count|stddev|variance]
PS.: The statisticId must be provided in same order it was inserted in requestbody list

Example: For a request with two statisticIds (0 and 1) using min and max aggregations respectively
https://server:port/values/geometry?aggregations=0-min&aggregations=1-max

Request Body schema: application/json
statisticIds
Array of integers
statisticCollectionId
integer
serviceKey
string

This is the Targomo APi key (serviceKey) that you receive once you are registered at targomo.com/developers.
For other requests this is specified as query parameter.

serviceUrl
any

defines the core api server address to be used

object

Responses

Request samples

Content type
application/json
{
  • "statisticCollectionId": 100,
  • "serviceUrl": "https://api.targomo.com/westcentraleurope",
  • "serviceKey": "__targomo_key_here__",
  • "statisticIds": [
    ],
  • "intersectionGeometry": {
    }
}

Response samples

Content type
application/json
{
  • "0-SUM": {
    },
  • "1-SUM": {
    }
}

Statistic Travel Times

This service calculates travel times between sources and statistic cells via statistic group with the highest resolution by given collection id.

query Parameters
serviceUrl
string
Example: serviceUrl=https://api.targomo.com/westcentraleurope

defines the core api server address to be used

apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Request Body schema: application/json
statisticCollectionId
integer

The Statistic Collection to be used as data source

statisticIds
Array of integers

List with statistic ids used for reachability calculation

edgeWeight
string
Default: "time"
Enum: "time" "distance"

Determines the dimension of the edges' weight, i.e. time (distance in seconds) or distance (distance in meters). distance Will optimize for distance and search for the shortest path, time will optimize for time and will search for the fastest path. Distance cannot be used in concert with travelType transit.

maxEdgeWeight
integer <int32>
Default: 1800

The maximum distance "depth" of the built network in seconds (for edgeWeight = time) or meters (for edgeWeight = distance). lower max edge weights limit the size of the networked and the area covered, while greater values will increase the time taken to process the request. The upper limit of this variable is based on your subscription plan and differs between distance and time.

travelType
string
Enum: "walk" "bike" "car" "fly"

The Mode of Transportation used by the Targomo API

useCache
boolean
Default: true

Flag to set if results must be cached for future requests

iFeelLucky
boolean
Default: false
getClosestSources
boolean
Default: false
omitIndividualStatistics
boolean
Default: false

if true, omits the individualStatistics response section

serviceKey
string

This is the Targomo APi key (serviceKey) that you receive once you are registered at targomo.com/developers.
For other requests this is specified as query parameter.

serviceUrl
string

This is the service URL to which the other dependant Targomo requests are dispatched (e.g Targomo Time or Routing requestrs). The endpoint has to correspond to the addresses, e.g. if you want to execute Vehicle Routing in France you need to point to an Targomo Endpoint that includes France geographically.

Array of objects (source)
Array of objects (sourceGeometry)
Array of objects (source)

Responses

Request samples

Content type
application/json
{
  • "statisticIds": [
    ],
  • "serviceUrl": "https://api.targomo.com/westcentraleurope",
  • "serviceKey": "__targomo_key_here__",
  • "statisticCollectionId": 100,
  • "edgeWeight": "distance",
  • "travelType": "car",
  • "maxEdgeWeight": 200,
  • "useCache": false,
  • "iFeelLucky": false,
  • "getClosestSources": false,
  • "omitIndividualStatistics": false,
  • "sources": [
    ]
}

Response samples

Content type
application/json
{
  • "416499": 120
}

Statistics Context Groups

List Registered Statistic Groups Metadata

This service lists all the Statistics Groups registered on Statistics Server and attributes provided by each group.

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

serviceUrl
string
Example: serviceUrl=https://api.targomo.com/westcentraleurope

defines the core api server address to be used

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Registered Statistic Group Metadata

Retrieves the Statistic Group list of statistics

A Statistic Group may have a list with one or more statistics (e.g. male and female population, distribution by age and so forth). This method lists the statistics available for a specific Statistic Group.

Each group has it's own statistics set, defined by the institution that obtained and organized the data.

path Parameters
groupId
required
integer

The Group Id to be registered

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

serviceUrl
string
Example: serviceUrl=https://api.targomo.com/westcentraleurope

defines the core api server address to be used

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Registered Statistic Metadata

A Statistic Group may have a list with one or more statistics (e.g. male and female population, distribution by age and so forth). This method retrieves the properties of a specific statistic from the Statistic Group.

Each group has it's own statistics set, defined by the institution that obtained and organized the data.

path Parameters
groupId
required
integer

The Group Id to be registered

statistics
required
integer

the statistic id from statistic group

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

serviceUrl
string
Example: serviceUrl=https://api.targomo.com/westcentraleurope

defines the core api server address to be used

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Statistic Group Cell

A Statistic Group may have one or more sets of statistics data. For each statistic, there must be a list of points or geometries geographically distributed with the values of that enclosing area. The purpose of this method is retrieve the all statistics data of a given Statistics Group for a coordinate.

The query parameter is not the geographic coordinate, but it's id on database. So, to use that service is necessary to know the desired id in values_of_statistic_group table.

path Parameters
groupId
required
integer

The Group Id to be registered

id
required
integer

the statistics data id ( values_of_statistic_group table id)

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

serviceUrl
string
Example: serviceUrl=https://api.targomo.com/westcentraleurope

defines the core api server address to be used

Responses

Response samples

Content type
application/json
{
  • "id": "143978",
  • "x": 14.2004447208689,
  • "y": 52.7824316270722,
  • "values": {
    },
  • "statisticValues": {
    }
}

List All Statistic Groups

Returns a list of statistic groups with base metadata from Database.

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

locale
string
Default: "en"
Example: locale=de

The two letter language code for the name and description language.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Statistic Group Metadata from Database

Returns an object with detailed metadata for a specific statistic group.

path Parameters
group
required
integer
Example: 100

statistic group for layer

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

fields
integer
Example: fields=stats

Specific fields as comma separated string to request

statsFields
integer
Example: statsFields=sum,topic

Specific statistic fields as comma separated string to request

Responses

Response samples

Content type
application/json
{
  • "id": 100,
  • "created": "2020-04-20T00:00:00.000Z",
  • "license": "Public Use",
  • "attribution": "© Statistische Ämter des Bundes und der Länder",
  • "modified": "2020-04-20T00:00:00.000Z",
  • "numberofpoints": 3206540,
  • "srid": 4326,
  • "type": "GRID,",
  • "version": 0.2,
  • "min_zoom": 10,
  • "privacy_level": "public",
  • "bounding_box": {
    },
  • "names": {
    },
  • "descriptions": {
    },
  • "ignorevalues": [
    ],
  • "topics": [
    ],
  • "stats": [
    ],
  • "collectionId": 100,
  • "topic": {
    },
  • "name": "German census 2011 (100mx100m): Demographics, families, households, buildings, apartments.",
  • "description": "This dataset contains information about demograhpics, families, households, buildings, and apartments in Germany in 2011. The raster consists of 100mx100m tiles."
}

Statistic Group mvt

Returns Statistics Layers (mvt tiles) of the statistic group from Database.

path Parameters
group
required
integer
Example: 100

statistic group for layer

z
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

statistics
string
Example: statistics=statistics=0&statistics=1&statistics=2

Statistics id list to return in the response.

sumStatistics
boolean
Default: false

If true also return the sum of all given statistics values. The default is false.

useDb
string
Default: false

If true, generate result from db, else use in memory data. If false, serviceUrl parameter must be used. The default is false.

Responses

Statistic Group GeoJSON

Returns Statistics Layers (GeoJSON) of the statistic group from Database.

path Parameters
group
required
integer
Example: 100

statistic group for layer

z
required
integer
Example: 14

zoom level - must be >= 0 and < 32

x
required
integer
Example: 8803

must be >= 0 and < 2^zoom

y
required
integer
Example: 5378

must be >= 0 and < 2^zoom

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

statistics
string
Example: statistics=statistics=0&statistics=1&statistics=2

Statistics id list to return in the response.

sumStatistics
boolean
Default: false

If true also return the sum of all given statistics values. The default is false.

useDb
string
Default: false

If true, generate result from db, else use in memory data. If false, serviceUrl parameter must be used. The default is false.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "code": "ok",
  • "message": "",
  • "requestTime": "79"
}

Location Scoring API

Analyse the quality of a given list of location according to different metrics.

It enables you to combine the features of many of Targomo's APIs into one single request!

You can define different criteria (POI reachability, statistics reachability, gravitational model requests) and can request those criteria for a list of locations. The Scoring API will calculate and combine all results into a single response.

Scores

This service returns the results/scores of a given list of criteria for a given list of locations.

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

showDetails
boolean

Ask for the details about the geographical elements that were used to calculate a score (for example: closest POIs...)

Request Body schema: application/json
required

Necessary for this service:

  • One or several locations
  • One or more criteria
required
Array of Point (object) or Geometry (object) (Location)

List of locations

required
object

Criterion definitions

For each criterion, a key must be set to be able to identify the different criteria in the response.

Array of Point (object) or Geometry (object) (Location)

List of locations that will be taken as competitors for all locations. This field is optional and will only have an influence on gravitational criteria.

If this list is null or empty, the gravitational scores for each location is calculated with the other locations as competitors.

Responses

Request samples

Content type
application/json
{
  • "locations": [
    ],
  • "criteria": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "Scores calculated",
  • "errors": [],
  • "timestamp": "03-03-2021 04:00:00"
}

Rating

This service returns the results/scores/ratings of a given rating for a given list of locations.

Only available on demand.

path Parameters
Rating Id
required
string
Example: rating1

Id of an existing rating definition.

query Parameters
apiKey
required
string
Example: apiKey=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

showDetails
boolean

Ask for the details about the geographical elements that were used to calculate a score (for example: closest POIs...)

Request Body schema: application/json
required

Necessary for this service:

  • One or several locations
required
Array of Point (object) or Geometry (object) (Location)

List of locations

criteriaGroups
object

Weights of each single criteria in all criteria groups. The average rating of each criteria group will calculated according to those weights.

criteriaGroupWeights
object

Weights of each criteria group. The average global rating will calculated according to those weights.

Responses

Request samples

Content type
application/json
{
  • "locations": [
    ],
  • "criteriaGroups": {
    },
  • "criteriaGroupWeights": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "Scores calculated",
  • "errors": [],
  • "timestamp": "03-03-2021 04:00:00"
}

Route API

Constructs routes between lists of sources and targets. If multiple sources and targets are set a result will be returned for each unique source-target pair.

Route

Calculates the routes between provided sources targets. This will result in one route per source/target pair (e.g. 2 sources and 3 targets returns 6 routes). If more than one source is provided in the request each one can have a separate travel type (tm tag on schema) specified.

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Request Body schema: application/json
required
pathSerializer
Array of strings
Items Enum: "compact" "geojson"
Array of objects (Route Source)
required
Array of objects (TargetCore)
edgeWeight
string
Default: "time"
Enum: "time" "distance"

Determines the dimension of the edges' weight, i.e. time (distance in seconds) or distance (distance in meters). distance Will optimize for distance and search for the shortest path, time will optimize for time and will search for the fastest path. Distance cannot be used in concert with travelType transit.

maxEdgeWeight
integer <int32>
Default: 1800

The maximum distance "depth" of the built network in seconds (for edgeWeight = time) or meters (for edgeWeight = distance). lower max edge weights limit the size of the networked and the area covered, while greater values will increase the time taken to process the request. The upper limit of this variable is based on your subscription plan and differs between distance and time.

elevation
boolean
Default: true

Whether or not the an elevation heuristic will be used (e.g. downhill with bike quicker than uphill).

reverse
boolean
Default: false

If the reverse flag is set to true, the routing algorithm will invert direction restrictions (one way roads, turning restrictions, ect) to simulate a to the source(s). For polygon routing this can be used to calculate the polygon/area that could reach the source(s).

object

Specifies factors with which the travel times of the edges are adjusted. This may be necessary in certain areas where the travel time calculation is almost always off by a certain factor, e.g. Paris rush hour.

"travelTimeFactors" : { "all":0.5, "motorway":1.5, .... (other specific edge classes possible) },..

Further specifics about the TravelTimeFactors:

  • travel time factor of 1.5 means 50% more time is needed
  • travel time factor 'all' is applied to ALL edge classes (on top of a specified one, e.g. for the example above 1.5*0.5=0.75 - the final applied travel time factor for 'motorway' edges)
  • all elements are optional, min allowed cumulative travel time factor is 0.5; maximum allowed cumulative travel time factor is 100.0
  • elements that are not recognized are ignored
  • transit travel times are not affected by the travelTimeFactors
maxSnapDistance
integer
Default: "Endpoint Specific"

This defines the maximum distance allowed (in meters) between a defined source/target and the nearest point in the network it will connect. Any point that has a distance exceeding maxSnapDistance is treated like a point that exceeds maxEdgeWeight.
If set too low points will be unable to snap to any nearby edges, if set too high points set outside the network or where lat/long have been accidentally inverted will be able to snap to the outer edge of the network.

showSnapInformation
boolean
Default: false

display information on snap distances in the response. Currently only available for Route, Time and reachability APIs

object

The exclusion geometry describes a GeoJSON object that should not be traveled through during the routing calculation. Any edges That intersect with the described geometry will be excluded from the routing. This can be used to simulate temporarily impassible routes or to deliberatley exclude certain ways. Both 'data' and 'crs' must be defined and do not have default values.

Responses

Request samples

Content type
application/json
{
  • "edgeWeight": "time",
  • "maxEdgeWeight": "2000",
  • "sources": [
    ],
  • "targets": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "data": {
    },
  • "errors": [ ],
  • "code": "ok",
  • "message": "",
  • "requestTime": "38"
}

Route

Calculates the routes between provided sources targets. This will result in one route per source/target pair (e.g. 2 sources and 3 targets returns 6 routes). If more than one source is provided in the request each one can have a separate travel type (tm tag on schema) specified.

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

cfg
required
string
Default: "{\n \"pathSerializer\": compact\n \"edgeWeight\": \"time\"\n \"sources\": [\n {\n \"id\": \"POI:0\",\n \"lat\": 52.5494892,\n \"lng\": 13.42883045,\n \"tm\": {\n \"car\": {}\n }\n }],\n \"targets\": [\n {\n \"id\": \"Home 1\",\n \"lat\": 52.53068102,\n \"lng\": 13.50658456\n }\n ]}"

JSON Configuration as query parameter
Please keep in mind that for compatibility, the GET URL recommended maximum size is 2000 chars

Responses

Response samples

Content type
application/json
Example
{
  • "data": {
    },
  • "errors": [ ],
  • "code": "ok",
  • "message": "",
  • "requestTime": "38"
}

Fleet API

Orders with deadlines, priorities, and certain loads have to be delivered by several vehicles (with certain load capacities) from several depots. The Fleet API optimizes the distribution of orders onto vehicles and their routes such that the total tour length is minimized while fulfilling all constraints. For more information and detailed examples please have a look at targomo.com/developers.

1. Vehicle Routing as Optimization Problem

The Vehicle Routing Problem (VRP) is an NP-hard problem - a concept from complexity theory. NP-hard problems have in common that solutions to the problem are easy to check, but there is no algorithm for finding the optimal solutions that needs less than exponential effort (depending on the problem size). If you were to solve the problem for 10 locations and 1 vehicle you would have to check all 10! = 3, 628, 800 possible combinations of the visiting order. To find the optimal solution for realistic problem sizes are thus not possible in a practical time because they have an exponential effort in relation to their problem size. Instead, the problem is modelled as a Constraint Satisfaction Problem with hard and soft constraints. Hard constraints such as the loading limits of the vehicles must never be exceeded for a valid solution. Soft constraints such as meeting the delivery deadline should be optimized, but can also be ignored if otherwise no solution is possible. This is achieved by applying a general optimization algorithm which attempts to find better solutions starting from a basic solution by recombination. The core of this approach is an evaluation function, which expresses the quality of a solution as a numerical value. This method has the advantage that it can find quickly a valid solution, which is not yet optimal. The optimization can be cancelled at any time because there is always a "best solution" if and only if a valid start-up solution was found. The disadvantage is that you do not know when the best possible solution is reached or how far the current solution is from the optimum.

Formalization as Optimization Problem

The optimization problem to be solved consists of:

  • fixed facts that do not change during the optimization,
  • variables, that need to be optimized by the algorithm,
  • constraints that make certain combinations of variable assignments impossible,
  • a score function which evaluates the quality of a solution into a numerical value, which needs to be maximized/minimizes, as well as
  • the final result: a fleet plan (tours for all vehicles).

Facts of the Optimization Problem

Facts are:

  • List of depots/branches from which the orders are to be served, each with:
    • unique ID, which is referenced by other objects, as well as
    • Address with geo coordinates.
  • Available vehicles, each with
    • home depot (the depot to which this vehicle is assigned)
    • starting point (starting coordinate - this is usually the home depot),
    • no, one, or multiple possible end destinations (start = end = home depot is possible and the normal case, but if several targets are available finding the best end destination will become part of the optimization)
    • the earliest possible departure time,
    • a latest possible arrival time,
    • interruption times in which the vehicle can neither travel nor service an order,
    • its fixed travel costs (an amount that is added to the travel time if this vehicle is used),
    • certain competences that qualifies it to service special demands of orders,
    • priority (vehicles with higher priority are favoured to finish within their working hours), and
    • load restrictions, e.g. maximum weight and volume capacity.
  • List of orders, each with
    • depot that is associated to that order (mapping to the possible delivery vehicles),
    • address with geo-coordinates,
    • use case specific load, e.g. weight, volume, length,
    • visiting times or delivery deadline,
    • special competence requirements that need to be met to carry out the service on-site (demands),
    • resources or entities that are involved in the service and are shared between orders (i.e. shared resources cannot be visited in parallel),
    • priority (orders with a higher priority a preferably treated), as well as
    • time for handling on site (e.g. parking, transporting freight, carrying out the service).
  • (Temporal) distance between all combinations of order locations or start/target coordinates. These are provided by the Route API.

At the end of the tour, each vehicle needs to return to one of its possible endpoints (if they have been specified). Typically, the end point would be equal to the starting point.

Variables of the Optimization Problem

  • Assignment of orders to vehicle. (The totals of the orders' load should not exceed the respective capacity of the vehicle - see constraints).
  • The order in which the orders are to be delivered.
  • Selection of the optimal tour end point of each vehicle (if potential end points have been specified for the vehicle).

Constraints of the Optimization Problem

  • Each order must be delivered exactly once. An order is placed in exactly one vehicle and can not be split.
  • Each used vehicle makes a single fully connected tour to its destinations and does not return to the depot to be "unloaded"/"reloaded".
  • The sums of the orders' load (e.g. weight, volume) per vehicle shall not exceed the respective capacity of the vehicle.
  • The visiting times or deadlines of orders should be adhered to as far as possible (soft constraint). Meeting the deadlines of high-priority orders should be preferred.
  • The valid working hours (from earliest departure to latest arrival excluding interruption times) should be adhered to if this is possible. Vehicles with a higher priority should be favoured in staying within their valid working hours.
  • The demands required to carry out an order should be matched by the available competences of the servicing vehicle.
  • If multiple orders share the same external entity they cannot be serviced in parallel (since this character/entity cannot be on two places at once).

Goal of the Optimization Problem

The goal is to minimize the total travel-time of all tours. It may occur that not all available vehicles are used. If possible, all deadlines (or latest visiting times) should be met. Otherwise, the number of deadlines that have been exceeded must be minimized, while deadlines of high-priority orders will be treated preferably (see 'priority'). Similarly, the optimization tries to keep exceeding the valid working hours of vehicles to a minimum (if even needed).

Result of the Optimization Problem

The result of the optimization is a suggested tour plan, which specifies what vehicle should deliver which order (and in which order they should be delivered). The fleet/tour plan consists of multiple tours and each tour has the following information:

  • List of orders ordered by their place in the tour, each with:
    • Address / coordinate,
    • Expected arrival time,
    • Expected departure time, as well
    • Driving time from the last tour point (can be other order or home depot).
  • Start address and start time (of the tour)
  • Address and travel time of the optimum tour end point (if specified)
  • Expected time of arrival at destination
  • Total load per tour, e.g. for weight, volume
  • Total time handling (i.e., on-site handling of orders, e.g., parking, transporting goods, carrying out service)
  • Total travel time (total travel time + total time handling = total time of tour)
  • Total travel distance (optional)
  • Detailed geo-data of the complete tour (optional)

2. Error Handling

This section explains possible exceptions and their handling in the vehicle routing API. The programming interface returns machine-readable information on errors and the affected data sets - e.g. not accepted orders. There are three classes of optimization errors:

  • Technical errors that make it impossible to process the request at all. These include, for example, JSON syntax errors, incorrect data types, or missing mandatory parameters. These are answered with the HTTP status code 400 Bad Request.
  • There are too many content errors that no optimization can be carried out. These requests are answered with the corresponding HTTP status code 422 Un-processable Entity. An example is if all addresses are invalid or inaccessible.
  • Some content errors occur, but through mitigation an optimization can still be carried out with the remainder of the query. In this case, the request is successfully answered with the HTTP status code 202 Accepted and the errors including the mitigation strategy are part of the response (in ).

Whenever possible, at least partial solutions are offered (i.e., HTTP status code 202 Accepted). The optimization is not blocked by individual errors such as incorrect order addresses. If there is no solution that can meet the constraints, at least a partial solution is offered. If at all possible, the optimization is not denied.

Fleet Optimization

Finds the optimal tours/routes for your fleet to service all your customers.

query Parameters
key
required
string
Example: key=__targomo_key_here__

This is the Targomo API (service) key that you receive once you are registered at targomo.com/developers.

Request Body schema: application/json
required
optimizationTime
integer <int32> >= 1
Default: 1

optimizationTime specifies the desired maximum run time in seconds this request can use for the optimization. The actual run time can be lower if a solution is found quicker, or exceeded when, for example other parts of the routing request, e.g. routing, parsing, serializing of the request response, take longer.

optimizationAlgorithm
required
string
Enum: "NO_OPTIMIZATION" "GREEDY_TSP" "BRUTE_FORCE_TSP" "CONSTRAINT_SATISFACTION"

optimizationAlgorithm specifies which optimization algorithm is to be used. The following options are available:

  • NO_OPTIMIZATION – no optimization is carried out, i.e. the algorithm will generate a tour for one vehicle per depot without carrying out routing and without trying to fulfil the constraints
  • GREEDY_TSP – Greedy Algorithm: A route is created, by always travelling to the closest order from the current point of view until all orders have been served. This does not consider order or vehicle priorities.
  • BRUTE_FORCE_TSP – All delivery order and transport combinations are generated and the one with the least consumed travel time is selected. This does not consider order or vehicle priorities.
  • CONSTRAINT_SATISFACTION – Powerful Algorithm based on constraint solving that tries to find an optimal solution that meets all the soft/hard constraints and optimizes for the travel time that is used for the routes. This algorithm should preferably be used.
required
object (OptimizationMetadata)

Metadata that is required for the optimization.

required
Array of objects (Store)
required
Array of objects (Transport)
required
Array of objects (Order)

Responses

Request samples

Content type
application/json
{
  • "optimizationTime": 2,
  • "optimizationAlgorithm": "CONSTRAINT_SATISFACTION",
  • "stores": [
    ],
  • "orders": [
    ],
  • "transports": [
    ],
  • "optimizationMetadata": {
    }
}

Response samples

Content type
application/json
{
  • "optimizationTime": 2,
  • "optimizationAlgorithm": "CONSTRAINT_SATISFACTION",
  • "stores": [
    ],
  • "orders": [
    ],
  • "transports": [
    ],
  • "optimizationMetadata": {
    },
  • "tours": [
    ],
  • "resultStatus": {
    }
}

Developer?

Get your free API Key!
Targomo GmbH
Potsdam Office
August-Bebel-Straße 26-53
14482 Potsdam
Contact us
Imprint
Privacy Policy

© 2021 Targomo GmbH