Trip API

Overview

The TRIP API is a routing service that calculates the best path(s) between locations considering logistic constraints as vehicle specifications, road speeds and more. It also considers several modes of transportation, including trucks.


  • Use cases

    Our TRIP API can be used to find the best path to execute deliveries and collections checking the shortest path (by distance), the fastest (by travel time), but also the safest path.

  • First steps

    Before you start developing with the TRIP API, review the authentication requirements (you need an API key) and the API usage limits.

Introduction

The TRIP API works in 3 steps:

  1. Post your logistic problem;
  2. Check the processing steps and status of the problem until a solution be available which could be through getting the status or a callback;
  3. Get the solution for your problem.

Posting a problem

To solve a logistic problem finding the best path between two or more points, you need to send the problem to be solved by our services through the POST/problems method.

Request parameters

Certain parameters are required while others are optional. The list of parameters and their possible values are enumerated below.

Mandatory Parameters

points

Indicates the waypoints that should be considered in the route(s). At least two points must be specified. The SitePoint parameter has the following fields:

latitude Indicates the latitude point where the site is located.
longitude Indicates the longitude point where the site is located.
siteId Optional point identifier.
profileName

Indicates the default data that should be considered to calculate the route(s). The profileName parameter supports a profile id that should be previously defined during the API configuration with Maplink’s onboarding team. The default profiles are: MEXICO, COLOMBIA, CHILE, BRAZIL, ARGENTINA, EGYPT, EUROPE, FRANCE, SAUDIARABIA.

Optional Parameters

avoidance

Indicates that the calculated route(s) should avoid some features. The avoidanceTypes parameter supports the following arguments:

TOLL_ROADS Indicates that the calculated route should avoid toll roads.
TOLL_GATES Indicates that the calculated route should avoid toll gates.
FERRIES Indicates that the calculated route should avoid ferries.
TUNNELS Indicates that the calculated route should avoid tunnels.
BRIDGES Indicates that the calculated route should avoid brides.
calculationMode

Indicates which calculation mode should be consider to calculate the route(s). The calculationMode parameter supports the following arguments:

THE_FASTEST Indicates that the calculated route should consider the fastest path.
THE_SHORTEST Indicates that the calculated route should consider the path with less KM.

If not specified the calculation mode,THE_FASTEST will be considered as default.

callback

Allow to register an URL to receive a callback with the problem solving status. The callback parameter has the following fields:

url URL that will receive the problem solving status.
user User access to client’s system if it’s necessary.
password Access key to client’s system if it’s necessary.

Note: If you opt for using the callback parameter in the POST/problems, check the GET/events responde description to know the parameters you will receive in return.

restrictionZones

Indicates that the calculated route(s) should avoid some zones. The restrictionZones parameter supports a list of zone id that should be previously defined during the profile construction.

speedPreference

Indicates that the calculated route(s) should consider different speeds per road type. It can be used to adjust the speed considered in the calculation for any vehicle type. The speedPreference parameter has the following fields:

roadType Indicates the type of road that must be adjusted and supports the following arguments:
FERRY,
PENALIZED_LOCAL_ROAD,
LOCAL_ROAD,
PENALIZED_SECONDARY_ROAD,
SECONDARY_ROAD,
PENALIZED_MAIN_ROAD,
MAIN_ROAD,
EXPRESSWAY,
HIGHWAY,
speed Indicates the road speed in kilometers per hour.

If not specified a speed preference, the real road speed for cars will be considered as default.

startDate

Indicates that the calculated route(s) should start at a specific date and time. The startDate parameter is mandatory if useRealSpeeds = true, and if not specified the value will be set to current time.

useRealSpeeds

Allows to enable real speeds for trip calculation. The speeds are based on traffic history at the time set on startDate. The useRealSpeeds parameter supports the following argument:

true Indicates that the calculated route(s) should consider the speeds based on traffic history.
false Indicates that the calculated route(s) should consider the speeds based on the road type.
vehicleSpecification

Indicates that the calculated route(s) should consider the following vehicle restrictions:

loadTypes Indicates the vehicle load types.
maxHeight Indicates the max vehicle height, in meters.
maxLength Indicates the max vehicle length, in meters.
maxLengthBetweenAxles Indicates the max vehicle length between axles, in meters.
maxWeight Indicates the max vehicle weight, in tons.
maxWeightForDangerousMaterials Indicates the max vehicle weight for dangerous materials, in tons.
maxWeightForExplodingMaterials Indicates the max vehicle weight for exploding materials, in tons.
maxWeightForPollutingMaterials Indicates the max vehicle weight for polluting materials, in tons.
maxWeightPerAxle Indicates the max vehicle weight per axle, in tons.
maxWidth Indicates the max vehicle width, in meters.

Response Parameters

The list of parameters and their possible values are enumerated below.

id

The id parameter is the identification of the problem that should be used to get the problem solving status and the problem solution.

Getting a problem

You can consult a problem which has already been posted through the GET/problems method.

Request Parameters

Certain parameters are required while others are optional. The list of parameters and their possible values are enumerated below.

Mandatory Parameters

id

The id parameter is the identification of the problem that you get as response of posting a problem.

Response parameters

Consult the Posting Problem Request parameters.

Getting feedback

To follow the process of finding a solution for the problem, you should check the processing status through GET/jobs method.

Request Parameters

Certain parameters are required while others are optional. The list of parameters and their possible values are enumerated below.

Mandatory parameters

jobId

The jobId parameter is the identification of the problem that you get as response of posting a problem.

Response parameters

The list of parameters and their possible values are enumerated below.

job

Indicates the main information about the process to solve the problem

error Indicates the last error occurred during the processing.
id Indicates the processing ID.
percent The current percentage of the processing done.
status Indicates the current status of the processing.
step Indicate the current step inside the status.
warning Indicate a warning of the processing.

Feedback Status

For each step during the problem solving a different status is presented in the GET/jobs response.

ENQUEUED Indicates that the problem is ready to be processed.
PROCESSING Indicates that the problem solution is being calculates.
SOLVED Indicates that the solution is already available to be goten.
ERROR Indicates that an error occurred and it was not possible to calculate the solution.

Getting Events

To follow the process of finding a solution for the problem, you can check the events which are occurring during the processing through GET/events method.

Request Parameters

Certain parameters are required while others are optional. The list of parameters and their possible values are enumerated below.

Mandatory Parameters

jobId

The jobId parameter is the identification of the problem that you get as response of posting a problem.

Response Parameters

The list of parameters and their possible values are enumerated below.

job

Indicates the main information about the process to solve the problem.

description Indicates a description or value related to the event occurred during the processing.
jobId Indicates the processing ID.
type Indicates the event type that supports the following arguments:
STATUS_CHANGE,
ERROR,
STEP_CHANGE,
PERCENT_CHANGE,
WARNING

Getting a Solution

As soon as you have a Solved status from the GET/event method, you can get the problem solution through GET/solutions method.

Request Parameters

Certain parameters are required while others are optional. The list of parameters and their possible values are enumerated below.

Mandatory Parameters

id

The id parameter is the identification of the problem that you get as response of posting a problem.

Response Parameters

The list of parameters and their possible values are enumerated below.

solution

Indicates the consolidated information about the solution. The solution parameter has the following fields:

id Indicates the problem ID regarding this solution.
averageSpeed Indicates the average speed of the route in kilometers per hour.
clientId Indicates the client ID who posted the problem regarding this solution.
createdAt Indicates the time and date when the solution was created.
legs Indicates the detailed legs of the route created to solve the problem.
totalDistance Indicates the total distance of the route in meters.
totalNominalDuration Indicates the total nominal duration of the route, in seconds.
totalSpeedProfilePenalty Indicates the Total duration penalty of the route in case of useRealSpeeds = true
SolutiontLeg

Indicates the information about the traced route(s). The SolutiontLeg parameter has the following fields:

averageSpeed Indicates the leg average speed in kilometers per hour.
distance Indicates the leg distance in meters.
nominalDuration Indicates the leg nominal duration, in seconds.
points Indicates the geometry of the route in coordinates.
speedProfilePenalty Indicates the duration penalty in case of useRealSpeeds = true
SitePoint

Indicates the main information about the traced route. The SitePoint parameter has the following fields:

latitude Indicates the latitude point where the site is located.
longitude Indicates the longitude point where the site is located.
siteId Optional point identifier.
Maplink Platform

Contact us