Docs
  • Solver
  • Models
    • Field Service Routing
    • Employee Shift Scheduling
  • Platform
Try models
  • Timefold Platform
  • How-tos
  • Using the maps service

Timefold Platform

    • Introduction
    • Planning AI concepts
    • Getting started with the Timefold Platform
    • Platform concepts
    • Models
      • Model catalog and documentation
      • Model versioning and maturity
      • Trialing Timefold models
    • How-tos
      • Interpreting model run results
      • Configuration parameters and profiles
      • Searching and categorizing runs for auditability
      • Member management and roles
      • Using the maps service
    • Job-oriented guides
      • Balancing different optimization goals
      • Validating an optimized plan with Explainable AI
      • Uncovering inefficiencies in operational planning
      • Responding to disruptions with real-time replanning
      • Designing better routing plans with (just enough) traffic awareness
    • API integration
      • API usage
      • Webhooks
    • Changelog
    • Feature requests
    • Self-Hosted
      • Self-Hosted vs. Timefold Cloud Platform
      • Installation instructions
      • Self-hosting the maps service
      • Troubleshooting
    • Trust
      • Risk profile
      • Product security
      • Data security
      • Legal and privacy
      • AI legislation compliance

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

It’s possible to configure the map provider and map location via Configuration parameters and profiles.

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.

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

Bicycle maps

The available maps for bicycle traffic include:

Map Description

US Georgia

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

If your region is included in multiple available maps, using the smallest fitting region will speed up the solving process.
  • © 2025 Timefold BV
  • Timefold.ai
  • Documentation
  • Changelog
  • Send feedback
  • Privacy
  • Legal
    • Light mode
    • Dark mode
    • System default