Using the maps service
For models that involve routing and thus require maps data, a maps service is part of the Timefold Platform.
The maps service supports integrations with maps providers to calculate distance and travel matrices. These matrices are used to calculate the distance between locations and optimize their routes accordingly.
Features of the maps service
In addition to making travel times and distances available, the maps service adds the following features:
-
Pre-calculation and caching of matrices, to avoid calculating matrices on the fly while solving.
-
Incremental updates, to avoid recalculating matrices every time they are used and only download updates to the matrix instead of the entire matrix.
-
Throttling based on the capacity of each maps provider, to avoid overloading the provider with requests.
-
Concurrency guarding, to prevent similar requests to the same provider from being done simultaneously.
Distance and travel matrices
The maps service is used to calculate a distance matrix and a travel matrix for a list of locations.
-
The distance matrix is used to calculate the distance between two locations.
-
The travel matrix is used to calculate the travel time between two locations.
Each matrix is a 2D array of size n * n
, where n
is the number of locations in the list.
The matrices are calculated by sending requests to the maps provider with the coordinates of the locations.
The request is done during the "Started" phase of a run (SOLVING_STARTED
).
Available map providers
The maps service supports the following map providers:
-
haversine
: calculates the matrices using the Haversine formula. -
osrm
: calculates the matrices using an OSRM service for a specific location.
If you’re using the Timefold Cloud Platform, the map provider and map location are configured via Configuration parameters and profiles. In this case, it’s possible to configure your own external provider via the platform API.
If you’re using the Self-Hosted version, you can define the map provider in the helm properties for self-hosted installations.
You can define an external
maps provider or use your own OSRM service.
For users with a Trial tenant plan, only the map provider haversine is available.
|
Available maps
In the Timefold Cloud Platform UI, you can create a configuration profile and choose a maps provider (e.g. OSRM) to see a full list of available maps.
Not all map locations are loaded by default. If you want to use a map that is currently not available, you can contact us. |
Vehicle maps
The available maps for typical vehicle traffic include (but are not limited to):
Map | Description |
---|---|
Australia |
This is the OSRM map for the country of Australia. |
Belgium |
This is the OSRM map for the country of Belgium. |
Dach |
This is the OSRM map for the DACH region, covering the countries of Germany, Austria and Switzerland. |
Mexico |
This is the OSRM map for the country of Mexico. |
Netherlands |
This is the OSRM map for the country of Netherlands. |
Ontario |
This is the OSRM map for the region of Ontario in Canada. |
Sweden |
This is the OSRM map for the country of Sweden. |
UK |
This is the OSRM map for the country of the United Kingdom. |
US |
This is the OSRM map for the United States. |
US Georgia |
This is the OSRM map for the state of Georgia in the United States. |
US Midwest |
This is the OSRM map for the Midwest region of the United States, covering the states of North Dakota, South Dakota, Nebraska, Kansas, Missouri, Iowa, Minnesota, Wisconsin, Illinois, Indiana, Michigan, and Ohio. |
US North-east |
This is the OSRM map for the North-east region of the United States, covering the states of Pennsylvania, New York, Connecticut, New Jersey, Massachusetts, and Main. |
US Pacific |
This is the OSRM map for the Pacific region of the United States, covering the states of Hawaii and Alaska. |
US South |
This is the OSRM map for the Southern region of the United States, covering the states of Texas, Oklahoma, Arkansas, Lousiana, Alabama, Tennessee, Kentucky, Georgia, Florida, West Virginia, Virginia, North Carolina, South Carolina, and Washington DC. |
US West |
This is the OSRM map for the Western region of the United States, covering the states of Washington, Oregon, Idaho, Montana, Wyoming, Denver, Utah, New Mexico, Arizona, California, and Nevada. |
Implementing an external map provider
It’s possible to create an external map provider and configure the platform to use it.
The map provider must implement two endpoints:
-
POST
/v1/travelDistanceMatrix
to calculate the distance and travel time between locations. -
POST
/v1/waypoints
to calculate the waypoints for a list of locations.
A query parameter, options
, is also sent, with additional information about the request, namely the location, provider name, tenant id, and model.
The OpenAPI specification can be found below.
Details
---
openapi: 3.0.3
info:
title: External Maps Provider API
description: External Maps Provider API
contact:
name: Timefold BV
url: https://timefold.ai
email: [email protected]
version: ""
servers:
- url: http://localhost:8180
description: Auto generated value
- url: http://0.0.0.0:8180
description: Auto generated value
paths:
/test/v1/travelDistanceMatrix:
post:
summary: Calculates travel time and distance matrix
parameters:
- name: options
in: query
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/LocationsDTO"
required: true
responses:
"400":
description: In case request given does not meet expectations
"500":
description: In case of processing errors
content:
application/json:
schema: {}
"200":
description: Travel and distance matrices
content:
application/octet-stream:
schema:
$ref: "#/components/schemas/TravelTimeAndDistanceDTO"
application/json:
schema:
$ref: "#/components/schemas/TravelTimeAndDistanceDTO"
tags:
- External Provider Resource
/test/v1/waypoints:
post:
summary: Calculates waypoints
parameters:
- name: options
in: query
schema:
type: string
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Location"
required: true
responses:
"400":
description: In case request given does not meet expectations
"500":
description: In case of processing errors
content:
application/json:
schema: {}
"200":
description: List of waypoints
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Location"
tags:
- External Provider Resource
/v1/distances:
get:
parameters:
- name: matrix-hash
in: query
schema:
type: string
- name: options
in: query
schema:
type: string
responses:
"200":
description: OK
summary: Get Travel Time And Distance Updates
tags:
- Maps Service Resource
post:
parameters:
- name: options
in: query
schema:
type: string
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Location"
required: true
responses:
"200":
description: OK
"400":
description: Bad Request
summary: Get Travel Time And Distance
tags:
- Maps Service Resource
/v1/management/location-sets:
post:
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/LocationSet"
required: true
responses:
"201":
description: Created
"400":
description: Bad Request
summary: Save Location Set
tags:
- Maps Management Resource
patch:
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/PatchLocationSet"
required: true
responses:
"204":
description: No Content
summary: Patch Location Set
tags:
- Maps Management Resource
delete:
responses:
"204":
description: No Content
summary: Clear Location Sets
tags:
- Maps Management Resource
/v1/management/location-sets/{tenant}:
delete:
parameters:
- name: tenant
in: path
required: true
schema:
$ref: "#/components/schemas/UUID"
responses:
"204":
description: No Content
summary: Clear Location Sets By Tenant
tags:
- Maps Management Resource
/v1/management/location-sets/{tenant}/{provider}:
delete:
parameters:
- name: provider
in: path
required: true
schema:
type: string
- name: tenant
in: path
required: true
schema:
$ref: "#/components/schemas/UUID"
responses:
"204":
description: No Content
summary: Clean Location Sets By Provider
tags:
- Maps Management Resource
/v1/management/location-sets/{tenant}/{provider}/{locationSetName}:
delete:
parameters:
- name: locationSetName
in: path
required: true
schema:
type: string
- name: provider
in: path
required: true
schema:
type: string
- name: tenant
in: path
required: true
schema:
$ref: "#/components/schemas/UUID"
responses:
"204":
description: No Content
summary: Clean Location Sets By Id
tags:
- Maps Management Resource
/v1/management/location-sets/{tenant}/{provider}/{locationSetName}/status:
get:
parameters:
- name: locationSetName
in: path
required: true
schema:
type: string
- name: provider
in: path
required: true
schema:
type: string
- name: tenant
in: path
required: true
schema:
$ref: "#/components/schemas/UUID"
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/LocationSetStatus"
summary: Get Location Set Status
tags:
- Maps Management Resource
/v1/waypoints:
post:
parameters:
- name: options
in: query
schema:
type: string
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Location"
required: true
responses:
"200":
description: OK
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Location"
"400":
description: Bad Request
summary: Get Waypoints
tags:
- Maps Service Resource
components:
schemas:
Location:
description: "Array of two elements: latitude and longitude, in that order."
maxItems: 2
minItems: 2
type: array
items:
format: double
type: number
example:
- 40.5044403760272
- -76.37894009358867
LocationSet:
type: object
properties:
locations:
type: array
items:
$ref: "#/components/schemas/Location"
options:
type: string
LocationSetStatus:
enum:
- PROCESSING
- COMPLETED
- NOT_FOUND
type: string
LocationsDTO:
type: object
properties:
source:
type: array
items:
$ref: "#/components/schemas/Location"
destination:
type: array
items:
$ref: "#/components/schemas/Location"
PatchLocationSet:
type: object
properties:
previous:
type: array
items:
$ref: "#/components/schemas/Location"
update:
type: array
items:
$ref: "#/components/schemas/Location"
options:
type: string
TravelTimeAndDistanceDTO:
type: object
properties:
travelTime:
type: array
items:
type: array
items:
format: double
type: number
distance:
type: array
items:
type: array
items:
format: double
type: number
UUID:
format: uuid
pattern: "[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}"
type: string
travelDistanceMatrix endpoint
A typical request and response for the travelDistanceMatrix
endpoint are shown below.
-
Request
-
Response
The source and destination locations to calculate the distance and travel time are sent as separate lists in the body of the request. Each location is represented in an array with two elements, latitude and longitude, in that order
curl --location 'localhost:8480/v1/travelDistanceMatrix?options=provider:external-provider,tenantId:af7c1fe6-d669-414e-b066-e9733f0de7a8,location:us-northeast,model:employee-scheduling-v1' \
--header 'Content-Type: application/json' \
--data '{
"source": [
[
-71.1017,
42.3813
],
[
-89.6030,
41.5509
],
[
-2.1,
1.1
]
],
"destination": [
[
-71.1017,
42.3813
],
[
-89.6030,
41.5509
],
[
-2.1,
1.1
]
]
}'
The response includes two fields: travelTime
and distance
. Each field contains a list of lists, representing a matrix of the travel time (in seconds) and distances (in meters).
The outer list must be the size of the number of source locations in the map, and each inner list must be the size of the number of destination locations in the map.
The values must be represented in numerical format, with no negative numbers.
If a location is not in the map, it must be removed from the matrices, and the index of the location in the list must be added to one of the headers X-MAPS-LOCATIONS-NOT-IN-MAP-SOURCE
or X-MAPS-LOCATIONS-NOT-IN-MAP-DESTINATION
, depending on if the location is in the source or destination list.
The list of locations not in the map is a comma separated list (eg. X-MAPS-LOCATIONS-NOT-IN-MAP-SOURCE=0,2,10,200
).
{
"travelTime": [
[
0.0,
148123.0,
591366.0
],
[
148123.0,
0.0,
701312.0
],
[
591366.0,
701312.0,
0.0
]
],
"distance": [
[
0.0,
2057259.0,
8213422.0
],
[
2057259.0,
0.0,
9740451.0
],
[
8213422.0,
9740451.0,
0.0
]
]
}
waypoints endpoint
A typical request and response for the waypoints
endpoint are shown below.
-
Request
-
Response
The list of locations to calculate the waypoints is sent as the body of the request.
curl --location 'localhost:8480/v1/waypoints?options=provider:external-provider,tenantId:af7c1fe6-d669-414e-b066-e9733f0de7a8,location:us-northeast,model:employee-scheduling-v1' \
--header 'Content-Type: application/json' \
--data '
[
[
-71.1017,
42.3813
],
[
-89.6030,
41.5509
],
[
-2.1,
1.1
]
]'
The response contains a list with the location of the waypoints.
[
[
-71.1017,
42.3813
],
[
-89.603,
41.5509
],
[
-2.1,
1.1
]
]
Location sets configuration
To avoid having to recalculate the distance matrix for the same locations, it’s possible to configure the precalculation of a location set. A location set is identified by its name and can be used by the models to avoid calculating an already cached distance matrix.
It’s possible to precalculate and cache a location set using the Location Sets Management API.
The API is available at /api/admin/v1/tenants/{tenantId}/maps/location-sets
, and it allows a user to configure location sets for a tenant.
Each location set, besides the name and the list of locations, must also be configured with a region (the region of the map used, eg. osrm-britain-and-ireland
)
and a map provider (eg. osrm
), so that it’s possible to create location sets for different regions and providers.
curl --location '{TIMEFOLD_PLATFORM_URL}/api/admin/v1/tenants/{TENANT_ID}/maps/location-sets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {TOKEN}' \
--data '{
"name": "{LOCATION_SET_NAME}",
"locations": [
[
40.5044403760272,
-76.37894009358867
],
[
41.5044403760272,
-75.37894009358867
]
],
"region": "{MAP_REGION}",
"provider": "{MAP_PROVIDER}"
}'
After the creation of a location set, its status will be PROCESSING
. After the matrix is calculated, the location set can be in one of two states: COMPLETED
or FAILED
.
If the status is COMPLETED
, the distance matrix of the location set was successfully calculated and cached.
Otherwise, when the status is FAILED
, the distance matrix was not stored in the cache.
-
Request
-
Response
curl --location '{TIMEFOLD_PLATFORM_URL}/api/admin/v1/tenants/{TENANT_ID}/maps/location-sets/{LOCATION_SET_NAME}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {TOKEN}'
{
"name": "{LOCATION_SET_NAME}",
"locations": [
[
40.5044403760272,
-76.37894009358867
],
[
41.5044403760272,
-75.37894009358867
]
],
"region": "{MAP_REGION}",
"provider": "{MAP_PROVIDER}",
"status": "COMPLETED"
}
When the location set is deleted, the distance matrix is also deleted and removed from the cache.
curl --location --request DELETE '{TIMEFOLD_PLATFORM_URL}/api/admin/v1/tenants/{TENANT_ID}/maps/location-sets/{LOCATION_SET_NAME}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {TOKEN}' \
It’s also possible to add a list of locations to a location set, using the PATCH operation. In this case the new locations will be added at the end of the location set.
curl --location --request PATCH '{TIMEFOLD_PLATFORM_URL}/api/admin/v1/tenants/{TENANT_ID}/maps/location-sets/{LOCATION_SET_NAME}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {TOKEN}' \
--data '[
[
43.5044403760272,
-76.37894009358867
]
]'
All requests to the Location Sets Management API require a bearer token based on the oauth2 platform configuration.
For example, for the field-service-routing model, you can configure a location setting the field locationSetName
of the modelInput
with the name of the location set.
{
"modelInput": {
"locationSetName": "{LOCATION_SET_NAME}",
...
},
...
}