Skip to main content

Compute an itinerary

In this guide we will

  • create an MCI Problem (Axioroute service for itinerary computation)
  • send an MCI Problem
  • listen to Axioroute API progress
  • see how the itinerary is displayed
  • customize the itinerary display
  • tune the itinerary computation

Follow common setup steps​

If not done already, follow common Introduction page.

Basic itinerary​

Create a list of site points​

A MCI Problem is mainly defined by a list of SitePoint for the itinerary steps.

Let's make a minimal MCI Problem with a list of sitePoint:

Example of 2 SitePoints
[
    {
        "id": "0DD2BD59-B7FF-46DA-AA21-0F38CAE07C89",
        "longitude": -0.561687,
        "latitude": 47.462484
    },
    {
        "id": "2F6D5037-5B84-4321-BD67-64271ACC22B6",
        "longitude": -0.562484,
        "latitude": 47.463957
    }
]

Send the Problem​

Build a Itinerary calculation message and send it with the SDK SendEvent function.

Once the message is sent, the SDK will send one or more Job progress event messages.

Payload example of a RUN_MCI Message
{
    "problem": {
        "sitePoints": [
            {
                "id": "0DD2BD59-B7FF-46DA-AA21-0F38CAE07C89",
                "longitude": -0.561687,
                "latitude": 47.462484
            },
            {
                "id": "2F6D5037-5B84-4321-BD67-64271ACC22B6",
                "longitude": -0.562484,
                "latitude": 47.463957
            }
        ]
    }
}

Listen to the resolution progress​

We will only listen to the Job progress event message having action equals to "MCIINDEPENDANTJOB"

Note

Receiving the solution may take a few seconds to some minutes, depending on the problem complexity and Axioroute Service traffic. You can display the percent (if exists) and the message values, until lastMessage is set to true.

Payload example of a RUN_MCI job progress event message
{
    "api": "MCDI",
    "jobId": "94af85b7-37c8-4cb8-9fbd-f2ba58114ac7",
    "action": "MCIINDEPENDANTJOB",
    "progress": "COMPLETE",
    "lastMessage": true,
    "statusCode": 200,
    "message": "Itinerary : 0,375 Km, 0:00'46\"",
    "entityType": "MCIINDEPENDANTJOB",
    "jobData": { ... }
}
Warning

Receiving the solution may take a few seconds or several minutes, depending on the problem complexity and Axioroute Service traffic.

Info

You can display the percent (if exists) and the message values, until the lastMessage property in the message is true.

Send the result​

Send the content of the jobData in a ADD_SDK_ENTITIES message.

A Entities event message is sent, with mciIndependantJobs value containing the jobData.

Map display​

w_compute-mci-0

Note

By default, on itinerary rollover a tooltip will be displayed with the MCI job id matching the itinerary.

Customize the itinerary with POIs​

Before running an itinerary computation, it can be helpful to send pois in Entities message with the same coordinates and Ids than the itinerary problem.

You can read Show a POI on the Map to learn how to proceed.

Payload example of POIS sent before the itinerary calculation
{
    "pois": [
        {
            "id": "0DD2BD59-B7FF-46DA-AA21-0F38CAE07C89",
            "pos": {
                "lonLat": [
                    -0.56168682235152,
                    47.4624835894391
                ]
            },
            "icon": "pin_yellow_syd.png",
            "displayOptions": {
                "width": 18,
                "height": 24,
                "anchor": [
                    0,
                    1
                ]
            },
            "label": "10 Rue Fulton 49000 Angers"
        },
        {
            "id": "2F6D5037-5B84-4321-BD67-64271ACC22B6",
            "pos": {
                "lonLat": [
                    -0.56248432823852,
                    47.4639573265308
                ]
            },
            "icon": "flag_checkered_syd.png",
            "displayOptions": {
                "width": 26,
                "height": 32,
                "anchor": [
                    0,
                    1
                ]
            },
            "label": "Rue Auguste Gautier 49000 Angers"
        }
    ]
}

Tune itinerary computation​

Tuning computation will take various informations into account to compute the best itinerary, adding a Trip Profiles to the Entities.

Some 3 nice tips can be:

  • useVariableSpeeds : to use traffic jam prediction
  • useBiDirectionnalSites : no matter the side on the road when you arrive or leave a SitePoint
  • useOncoming: when the SitePoint is not really close to the road, it will add extra time and distance.
Warning

If useVariableSpeeds is true, you must set itineraryStartDates in the MCI problem

Add a trip profile to the entities​

After having modified the entities, send them to the SDK

Payload example with a trip profile in entities
{
    "pois": [
        {
            "id": "0DD2BD59-B7FF-46DA-AA21-0F38CAE07C89",
            "pos": {
                "lonLat": [
                    -0.56168682235152,
                    47.4624835894391
                ]
            },
            "icon": "pin_yellow_syd.png",
            "displayOptions": {
                "width": 18,
                "height": 24,
                "anchor": [
                    0,
                    1
                ]
            },
            "label": "10 Rue Fulton 49000 Angers"
        },
        {
            "id": "2F6D5037-5B84-4321-BD67-64271ACC22B6",
            "pos": {
                "lonLat": [
                    -0.56248432823852,
                    47.4639573265308
                ]
            },
            "icon": "flag_checkered_syd.png",
            "displayOptions": {
                "width": 26,
                "height": 32,
                "anchor": [
                    0,
                    1
                ]
            },
            "label": "Rue Auguste Gautier 49000 Angers"
        }
    ],
    "tripProfile": {
        "useVariableSpeed": true,
        "useBiDirectionnalSites": true,
        "useOncoming": true
    }
}

Add a start date for our initial site point.​

Update the itinerary problem adding itineraryStartDates and send the calculation.
Add the departure date to each step of the itinerary, except the last one of course. You can also set just one departure date (the departure date of the 1st step).

info

itineraryStartDates has no effect when the trip profiles value useVariableSpeeds is false

Payload example of a RUN_MCI message with 2 SitePoints and a start date
{
    "problem": {
        "sitePoints": [
            {
                "id": "0DD2BD59-B7FF-46DA-AA21-0F38CAE07C89",
                "longitude": -0.561687,
                "latitude": 47.462484
            },
            {
                "id": "2F6D5037-5B84-4321-BD67-64271ACC22B6",
                "longitude": -0.562484,
                "latitude": 47.463957
            }
        ],
        "itineraryStartDates": [
            "2024-01-22T14:03:02.370+01:00"
        ]
    }
}
info

itineraryStartDates has no effect when the trip profiles value useVariableSpeeds is false

itineraryStartDates is a timestamp that must comply with ISO 8601 standard.

Map display with itinerary tuned​

You can see the estimated traffic jam in the itinerary path.

w_compute-mci-1