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 dataset (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.

Automatic map selection

Choose "Auto-select" as "Maps location" and the maps service automatically selects the most suitable vehicle map based on the coordinates provided in the dataset input.

All coordinates (for example, vehicle start locations and visit locations) are evaluated and matched against the available map regions (see below). From the regions that fully cover all coordinates, the service selects the smallest possible map.

The selected map is determined once per problem and remains fixed for the entire optimization run.

Automatic map selection provides the following advantages:

Reduced configuration overhead: You no longer need to create and maintain multiple configuration profiles for different geographic regions.
Improved performance: Smaller maps lead to faster distance matrix calculations and typically shorter solver runtimes.
Safer defaults: The maps service always selects the most appropriate map based on the provided coordinates.

We strongly recommend using automatic map selection as the default setting.

If no map is found that fully covers all provided locations, the maps service falls back to selecting the map that covers the highest number of locations. The request only fails if none of the available maps cover any of the provided coordinates, in which case the service responds with a clear error message.

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.
Benelux-France	This is the OSRM map for Belgium, Luxembourg, the Netherlands and France.
Benelux-Germany	This is the OSRM map for Belgium, Luxembourg, the Netherlands and Germany.
Britain and Ireland	This is the OSRM map for the region of Britain and Ireland.
Canada	This is the OSRM map for the country of Canada.
DACH	This is the OSRM map for the DACH region, covering the countries of Germany, Austria and Switzerland.
France	This is the OSRM map for the country of France.
GCC States	This is the OSRM map for the GCC states, covering the Kingdom of Bahrain, the State of Kuwait, the Sultanate of Oman, the State of Qatar, the Kingdom of Saudi Arabia and the United Arab Emirates.
Germany	This is the OSRM map for the country of Germany.
Italy	This is the OSRM map for the country of Italy.
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 Alabama	This is the OSRM map for the state of Alabama in the United States.
US Alaska	This is the OSRM map for the state of Alaska in the United States.
US Arizona	This is the OSRM map for the state of Arizona in the United States.
US Arkansas	This is the OSRM map for the state of Arkansas in the United States.
US California	This is the OSRM map for the state of California in the United States.
US Colorado	This is the OSRM map for the state of Colorado in the United States.
US Connecticut	This is the OSRM map for the state of Connecticut in the United States.
US Delaware	This is the OSRM map for the state of Delaware in the United States.
US District of Columbia	This is the OSRM map for the District of Columbia of the United States.
US Florida	This is the OSRM map for the state of Florida in the United States.
US Georgia	This is the OSRM map for the state of Georgia in the United States.
US Hawaii	This is the OSRM map for the state of Hawaii in the United States.
US Idaho	This is the OSRM map for the state of Idaho in the United States.
US Illinois	This is the OSRM map for the state of Illinois in the United States.
US Indiana	This is the OSRM map for the state of Indiana in the United States.
US Iowa	This is the OSRM map for the state of Iowa in the United States.
US Kansas	This is the OSRM map for the state of Kansas in the United States.
US Kentucky	This is the OSRM map for the state of Kentucky in the United States.
US Louisiana	This is the OSRM map for the state of Louisiana in the United States.
US Maine	This is the OSRM map for the state of Maine in the United States.
US Maryland	This is the OSRM map for the state of Maryland in the United States.
US Massachusetts	This is the OSRM map for the state of Massachusetts in the United States.
US Michigan	This is the OSRM map for the state of Michigan in the United States.
US Minnesota	This is the OSRM map for the state of Minnesota in the United States.
US Mississippi	This is the OSRM map for the state of Mississippi in the United States.
US Missouri	This is the OSRM map for the state of Missouri in the United States.
US Montana	This is the OSRM map for the state of Montana in the United States.
US Nebraska	This is the OSRM map for the state of Nebraska in the United States.
US New Hampshire	This is the OSRM map for the state of New Hampshire in the United States.
US New Jersey	This is the OSRM map for the state of New Jersey in the United States.
US New Mexico	This is the OSRM map for the state of New Mexico in the United States.
US New York	This is the OSRM map for the state of New York in the United States.
US North Carolina	This is the OSRM map for the state of North Carolina in the United States.
US North Dakota	This is the OSRM map for the state of North Dakota in the United States.
US Northeast	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 Maine.
US Ohio	This is the OSRM map for the state of Ohio in the United States.
US Oklahoma	This is the OSRM map for the state of Oklahoma in the United States.
US Oregon	This is the OSRM map for the state of Oregon in the United States.
US Pennsylvania	This is the OSRM map for the state of Pennsylvania in the United States.
US Puerto Rico	This is the OSRM map for the Puerto Rico region of the United States.
US Rhode Island	This is the OSRM map for the state of Rhode Island in the United States.
US South Carolina	This is the OSRM map for the state of South Carolina in the United States.
US South Dakota	This is the OSRM map for the state of South Dakota in the United States.
US Tennessee	This is the OSRM map for the state of Tennessee in the United States.
US Texas	This is the OSRM map for the state of Texas in the United States.
US Utah	This is the OSRM map for the state of Utah in the United States.
US Vermont	This is the OSRM map for the state of Vermont in the United States.
US Virgin Islands	This is the OSRM map for the Virgin Islands region of the United States.
US Virginia	This is the OSRM map for the state of Virginia in the United States.
US Washington	This is the OSRM map for the state of Washington in the United States.
US West	This is the OSRM map for the Western region of the United States, covering the states of Washington, Oregon, Idaho, Montana, Wyoming, Colorado, Utah, New Mexico, Arizona, California and Nevada.
US West Virginia	This is the OSRM map for the state of West Virginia in the United States.
US Wisconsin	This is the OSRM map for the state of Wisconsin in the United States.
US Wyoming	This is the OSRM map for the state of Wyoming in the United States.
Vietnam	This is the OSRM map for the country of Vietnam.

Map

Description

Australia

This is the OSRM map for the country of Australia.

Belgium

This is the OSRM map for the country of Belgium.

Benelux-France

This is the OSRM map for Belgium, Luxembourg, the Netherlands and France.

Benelux-Germany

This is the OSRM map for Belgium, Luxembourg, the Netherlands and Germany.

Britain and Ireland

This is the OSRM map for the region of Britain and Ireland.

Canada

This is the OSRM map for the country of Canada.

DACH

This is the OSRM map for the DACH region, covering the countries of Germany, Austria and Switzerland.

France

This is the OSRM map for the country of France.

GCC States

This is the OSRM map for the GCC states, covering the Kingdom of Bahrain, the State of Kuwait, the Sultanate of Oman, the State of Qatar, the Kingdom of Saudi Arabia and the United Arab Emirates.

Germany

This is the OSRM map for the country of Germany.

Italy

This is the OSRM map for the country of Italy.

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.

This is the OSRM map for the country of the United Kingdom.

This is the OSRM map for the United States.

US Alabama

This is the OSRM map for the state of Alabama in the United States.

US Alaska

This is the OSRM map for the state of Alaska in the United States.

US Arizona

This is the OSRM map for the state of Arizona in the United States.

US Arkansas

This is the OSRM map for the state of Arkansas in the United States.

US California

This is the OSRM map for the state of California in the United States.

US Colorado

This is the OSRM map for the state of Colorado in the United States.

US Connecticut

This is the OSRM map for the state of Connecticut in the United States.

US Delaware

This is the OSRM map for the state of Delaware in the United States.

US District of Columbia

This is the OSRM map for the District of Columbia of the United States.

US Florida

This is the OSRM map for the state of Florida in the United States.

US Georgia

This is the OSRM map for the state of Georgia in the United States.

US Hawaii

This is the OSRM map for the state of Hawaii in the United States.

US Idaho

This is the OSRM map for the state of Idaho in the United States.

US Illinois

This is the OSRM map for the state of Illinois in the United States.

US Indiana

This is the OSRM map for the state of Indiana in the United States.

US Iowa

This is the OSRM map for the state of Iowa in the United States.

US Kansas

This is the OSRM map for the state of Kansas in the United States.

US Kentucky

This is the OSRM map for the state of Kentucky in the United States.

US Louisiana

This is the OSRM map for the state of Louisiana in the United States.

US Maine

This is the OSRM map for the state of Maine in the United States.

US Maryland

This is the OSRM map for the state of Maryland in the United States.

US Massachusetts

This is the OSRM map for the state of Massachusetts in the United States.

US Michigan

This is the OSRM map for the state of Michigan in the United States.

US Minnesota

This is the OSRM map for the state of Minnesota in the United States.

US Mississippi

This is the OSRM map for the state of Mississippi in the United States.

US Missouri

This is the OSRM map for the state of Missouri in the United States.

US Montana

This is the OSRM map for the state of Montana in the United States.

US Nebraska

This is the OSRM map for the state of Nebraska in the United States.

US New Hampshire

This is the OSRM map for the state of New Hampshire in the United States.

US New Jersey

This is the OSRM map for the state of New Jersey in the United States.

US New Mexico

This is the OSRM map for the state of New Mexico in the United States.

US New York

This is the OSRM map for the state of New York in the United States.

US North Carolina

This is the OSRM map for the state of North Carolina in the United States.

US North Dakota

This is the OSRM map for the state of North Dakota in the United States.

US Northeast

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

US Ohio

This is the OSRM map for the state of Ohio in the United States.

US Oklahoma

This is the OSRM map for the state of Oklahoma in the United States.

US Oregon

This is the OSRM map for the state of Oregon in the United States.

US Pennsylvania

This is the OSRM map for the state of Pennsylvania in the United States.

US Puerto Rico

This is the OSRM map for the Puerto Rico region of the United States.

US Rhode Island

This is the OSRM map for the state of Rhode Island in the United States.

US South Carolina

This is the OSRM map for the state of South Carolina in the United States.

US South Dakota

This is the OSRM map for the state of South Dakota in the United States.

US Tennessee

This is the OSRM map for the state of Tennessee in the United States.

US Texas

This is the OSRM map for the state of Texas in the United States.

US Utah

This is the OSRM map for the state of Utah in the United States.

US Vermont

This is the OSRM map for the state of Vermont in the United States.

US Virgin Islands

This is the OSRM map for the Virgin Islands region of the United States.

US Virginia

This is the OSRM map for the state of Virginia in the United States.

US Washington

This is the OSRM map for the state of Washington in the United States.

US West

This is the OSRM map for the Western region of the United States, covering the states of Washington, Oregon, Idaho, Montana, Wyoming, Colorado, Utah, New Mexico, Arizona, California and Nevada.

US West Virginia

This is the OSRM map for the state of West Virginia in the United States.

US Wisconsin

This is the OSRM map for the state of Wisconsin in the United States.

US Wyoming

This is the OSRM map for the state of Wyoming in the United States.

Vietnam

This is the OSRM map for the country of Vietnam.

Bicycle maps

The available maps for bicycle traffic include:

Map	Description
US Georgia	This is the OSRM map with the bicycle transport type for the state of Georgia in the United States.

Map

Description

US Georgia

This is the OSRM map with the bicycle transport type for the state of Georgia in the United States.

Foot maps

The available maps for foot traffic include:

Map	Description
Switzerland	This is the OSRM map with the foot transport type for the country of Switzerland.

Map

Description

Switzerland

This is the OSRM map with the foot transport type for the country of Switzerland.

If your region is included in multiple available maps, using the smallest fitting region will speed up the solving process.

Traffic-aware routing

Traffic-aware routing is currently available in preview. Contact us to enable it for your tenant.

By default, the maps service calculates travel times using static road network data, without accounting for traffic. Historical traffic improves this by using historical average traffic patterns recorded at specific time slices throughout the day, for example, the typical congestion during morning rush hour, or lighter traffic in the afternoon.

Rather than relying on live traffic feeds, historical traffic uses aggregated data to model how travel times typically vary by time of day and day of week. This means the model can produce route plans that are realistic for when the work actually happens, accounting for the fact that a 2km drive may take 10 minutes during morning rush hour, but only 3 minutes at night.

This is particularly valuable for routing models where departure times and task sequences interact with real-world traffic conditions.

Want to track the progress of traffic-aware optimization? Follow the feature request on feedback.timefold.ai to stay informed and share your use case.

Supported models

Traffic-aware routing is currently supported by the following models. See each model’s documentation for how to enable and use it.

Field Service Routing

Using an external map provider

Instead of relying on the built-in haversine or osrm map providers, you can integrate your own external service as a map provider. This is useful when, for example:

your locations aren’t covered by public map data, such as indoor facilities, private road networks, or construction sites.
you have access to real-time or live travel conditions, such as traffic, weather, or road closures, that a static distance calculation can’t account for.
your travel times depend on domain-specific constraints, such as truck routing restrictions or no-fly zones, that a generic road-distance calculation doesn’t model.
you already maintain a trusted distance or ETA engine and want the platform to use it instead of a second, potentially inconsistent source of truth.

Using an external map provider involves two steps: implementing a service with the endpoints the platform expects, and registering that service with your tenant so it can be selected as a map provider.

Implementing an external map provider

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:8480
  description: Auto generated value
- url: http://0.0.0.0:8480
  description: Auto generated value
paths:
  /v1/travelDistanceMatrix:
    post:
      summary: Calculates travel time and distance matrix
      parameters:
      - name: options
        in: query
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
        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:
                type: object
            application/json:
              schema:
                type: object
      tags:
      - Test External Provider Resource
  /v1/waypoints:
    post:
      summary: Calculates waypoints
      parameters:
      - name: options
        in: query
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items: {}
        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: {}
      tags:
      - Test External Provider Resource
components:
  schemas: {}

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": [
        [
            42.3813,
            -71.1017
        ],
        [
            41.5509,
            -89.6030
        ],
        [
            -2.1,
            1.1
        ]
    ],
    "destination": [
        [
            42.3813,
            -71.1017
        ],
        [
            41.5509,
            -89.6030
        ],
        [
            -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 '
    [
        [
            42.3813,
            -71.1017
        ],
        [
            41.5509,
            -89.6030
        ],
        [
            -2.1,
            1.1
        ]
    ]'

The response contains a list with the location of the waypoints.

Registering an external map provider

Once an external map provider implements the travelDistanceMatrix and waypoints endpoints described above, it can be registered with a tenant using the External Providers Management API, available in the Platform API at /api/platform/v1/tenants/{tenantId}/maps/external-providers.

See the Interactive API reference for the full request and response schema of the External Providers Management API, and to try out requests directly in the browser.

Each provider is identified by a generated id and configured with:

name: the name used to reference the provider once registered.
url: the base URL of the external provider.
description (optional): a human-readable description of the provider.
location (optional): the region the provider serves, for example osrm-britain-and-ireland.
headers (optional): a map of HTTP headers sent with every request to the provider, for example an Authorization header if the provider requires its own authentication.

curl --location '{TIMEFOLD_PLATFORM_URL}/api/platform/v1/tenants/{TENANT_ID}/maps/external-providers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {PAT}' \
--data '{
  "name": "{EXTERNAL_PROVIDER_NAME}",
  "description": "{EXTERNAL_PROVIDER_DESCRIPTION}",
  "location": "{MAP_REGION}",
  "url": "{EXTERNAL_PROVIDER_URL}",
  "headers": {
    "Authorization": "Bearer {EXTERNAL_PROVIDER_TOKEN}"
  }
}'

Request
Response

curl --location '{TIMEFOLD_PLATFORM_URL}/api/platform/v1/tenants/{TENANT_ID}/maps/external-providers/{EXTERNAL_PROVIDER_ID}' \
--header 'Authorization: Bearer {PAT}'

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "{EXTERNAL_PROVIDER_NAME}",
  "description": "{EXTERNAL_PROVIDER_DESCRIPTION}",
  "location": "{MAP_REGION}"
}

When a provider is deleted, it can no longer be used to calculate distances or waypoints.

curl --location --request DELETE '{TIMEFOLD_PLATFORM_URL}/api/platform/v1/tenants/{TENANT_ID}/maps/external-providers/{EXTERNAL_PROVIDER_ID}' \
--header 'Authorization: Bearer {PAT}'

Authentication

All requests to the External Providers Management API use a Personal Access Token (PAT). See Generating a Personal Access Token for instructions on how to create one. The token requires the permission for the "External provider of distance and travel time information" resource, with the access level (read, create, update, or delete) matching the operation being performed.

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, available in the Platform API at /api/platform/v1/tenants/{tenantId}/maps/location-sets. 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
  ]
]'

Authentication

All requests to the Location Sets Management API use a Personal Access Token (PAT). See Generating a Personal Access Token for instructions on how to create one. The token requires the MapLocationSet permission.

Using a location set in a model

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}",
    ...
  },
  ...
}