Understanding the API

Each model on the Timefold Platform has its own API which conforms with the OpenAPI standard.

1. Explore the model API in the Timefold Platform UI

You can explore the API in Timefold Platform.

  1. Log in to app.timefold.ai.

  2. Select the model.

  3. Select OpenAPI Spec.

1.1. Model API Endpoints

To understand the API endpoints, select an endpoint to expand it. You will see:

  • Parameters: The parameters required by the API endpoint.

  • Request body: For POST endpoints, you can view example values that are accepted as part of the JSON input and the model schema.

  • Response: The responses the API endpoints will return, example values, and the schema.

The Example Value tab for each endpoint show an example of the JSON for that endpoint:

example values

The Schema tab shows the values, their types, and a description. Each field can be expanded to view related information.

schema

1.2. Testing the model APIs

To test the API functionality in the platform, you first need to authorize the API.

  1. From the drop-down menu next to your username select API Keys.

  2. Copy an API key that has permissions for the model you want to test.

  3. Navigate back to the model you want to test and select OpenAPI Spec.

  4. Click Authorize and paste the API key you just copied.

1.3. Demo datasets

Demo datasets that demonstrate the functionality are available. To view the list of demo datasets:

  1. Expand the POST /v1/demo-data endpoint.

  2. Click Try it out, then click Execute.

You will see the Curl instructions to request the dataset and the request URL.

You will also see the response to the request with the list of available datasets.

To download one of the listed datasets:

  1. Expand the POST /v1/demo-data/{demoDataId} endpoint.

  2. Click Try it out, enter the name of the dataset, for instance, "BASIC", and click Execute.

In the response body, you will see the dataset. Copy the dataset to use with subsequent endpoints.

Alternatively, you can use your own dataset to test the functionality.

1.4. Request a field service routing plan

To request a schedule in the Field Service Routing model:

  1. Expand the POST v1/route-plans endpoint, and click Try it out.

  2. Paste the dataset from the previous call (or use your own dataset) into the request body field over the existing text and click Execute.

Note the ID in the response.

You can view the dataset as it is being solved by navigating back to the top of the page and clicking Runs. Note, it will take a few minutes to provide a solution for the dataset.

1.5. Request the route plan

To request the solution for the dataset:

  1. Expand the GET v1/route-plans/{id} endpoint, and click Try it out.

  2. Paste the ID from the previous POST call into the id field.

In the response body, you will see the route plan. Note, if the route plan is still being generated, the solverStatus will be "SOLVING_ACTIVE". If the final route plan has been generated, the solverStatus will be "SOLVING_COMPLETE".

2. Using the OpenAPI

2.1. Create problem dataset

Create problem dataset using predefined model schema that follows OpenAPI specification. The application provides several out-of-the-box examples that can be used as a starting point.

Example 1. List sample datasets REST API endpoint call

GET /v1/demo-data

Example 2. Get sample dataset REST API endpoint call

GET /v1/demo-data/{dataset_name}

2.2. Submit a dataset

Submit the unsolved dataset using the REST API. The application validates the input and returns a unique identifier of the problem. The solving process is scheduled and eventually starts.

Example 3. Submit problem dataset REST API endpoint call

POST /v1/route-plans

2.3. Get current best solution and check status

Check the current best solution and receive information about the solving process. The solution contains the optimized route plan. Use id attribute returned by submit a dataset step.

Example 4. Check status REST API endpoint call

GET /v1/route-plans/{id}

2.4. Terminate solving

Terminate the solving process and receive the current best solution. Use id attribute returned by submit a dataset step.

Example 5. Terminate solving REST API endpoint call

DELETE /v1/route-plans/{id}

2.5. Get all solving processes

Get info about the status of all solving processes.

Example 6. Terminate solving REST API endpoint call

GET /v1/route-plans

2.6. Recommendations

Use this feature to react to abrupt changes in daily operations. Consider a call center that handles incoming service requests. The customer provides the operator with time windows when the service can take place. The Recommend Visit Time Windows API allows you to validate if the service can take place in one of the windows provided by the customer, in a quick way. The API provides a list of vehicle shift recommendations for every time window specified. The vehicle shift recommendations are sorted by quality, with the best fit first.

2.6.1. Recommend Visit Time Windows

Provides a list of recommendations for a single visit and given time windows.

Example 7. Get time window recommendations for a new visit in an already optimized route plan

POST /v1/route-plans/{id}/recommendations/visit-recommend-time-windows

Example 8. Get time window recommendations for a new visit in a route plan that hasn’t been optimized yet

POST /v1/route-plans/recommendations/visit-recommend-time-windows

2.6.2. Recommend Visit Group Time Windows

Provides a list of recommendations for a visit group and given time windows.

Example 9. Get time window recommendations for a new visit group in an already optimized route plan

POST /v1/route-plans/{id}/recommendations/visit-group-recommend-time-windows

Example 10. Get time window recommendations for a new visit group in a route plan that hasn’t been optimized yet

POST /v1/route-plans/recommendations/visit-group-recommend-time-windows

2.7. Score analysis

Use this feature to understand the score structure of your route plan. It provides a detailed breakdown of the score, including the score of each constraint.

The score analysis is automatically calculated and stored at the end of each solver run.

Example 11. Get score analysis for a route plan

GET /v1/route-plans/{id}/score-analysis

Example 12. Sample score analysis result
{
  "score": "0hard/0medium/-2540120soft",
  "constraints": [
      {
        "name": "Last visit max departure time soft limit",
        "weight": "0hard/0medium/-1soft",
        "score": "0hard/0medium/0soft"
      },
      {
        "name": "Minimize the visit completion risk",
        "weight": "0hard/0medium/-1soft",
        "score": "0hard/0medium/-97240soft"
      }
      ...

Consider other use case where you have solved a route plan and want to fine tune it manually afterward. For example, assign a visit to a different vehicle shift. Use the score analysis to understand the impact of the change on the score and to validate that the new route plan is feasible.

The endpoint accepts a route plan object in the request body.

Example 13. Sample score analysis result
{
  "score": "0hard/0medium/-1240120soft",
  "constraints": [
      {
        "name": "Last visit max departure time soft limit",
        "weight": "0hard/0medium/-1soft",
        "score": "0hard/0medium/0soft"
      },
      {
        "name": "Minimize the visit completion risk",
        "weight": "0hard/0medium/-1soft",
        "score": "0hard/0medium/-25240soft"
      }
      ...