Routescanner OpenAPI Definition (version 1.2)
Download OpenAPI specification:
The Routescanner platform enables users to access comprehensive distance, emission, and route optimization data in an easy-to-use and intuitive format. By leveraging its RESTful API, developers can easily integrate the platform's data into their own applications.
The API is designed to provide developers with fast and reliable access to the data they need, with resource-oriented URLs, JSON-encoded responses, and standard HTTP response codes. This makes it simple and straightforward to use the Routescanner platform in any project.
To access our /route-information APIs, you will need a personal API key.
To obtain one, create an account on Routescanner.com, log in, and then select "API" on the bottom of the menu on the left side of the page.
Once you have sufficient credits, you can retrieve your API key from this page.
For security purposes, keep this key confidential and include it in the request header when using our APIs.
Specifically, add a field to the header with the name x-api-key and the value of your API key.
If you fail to include this field, you will receive an unauthorized access error.
A sample curl request may look like this:
curl --location --request GET ‘https://connect.routescanner.com/route-information/api/emissions?origin=NLRTM&destination=NLAMS&modality=DEEPSEA’ \
--header ‘x-api-key: aPJJx&IRYi8pI9F8GTMX01EffyjqsGoW4LfGq157’
Route optimization APIs
To access our paid /route-optimizer APIs, you will need to be granted special access.
To gain access, please contact us at support@routescanner.com.
Although a few of our APIs are available for free, most of the Routescanner services require credits to be used. The amount of credits required for each call will depend on the specific API and its features.
API calls in the /route-information path require API credits.
If you would like to learn more about purchasing credits please visit: https://www.routescanner.com/solutions/emission-reporting.
All the necessary information and the best options for purchasing credits can be found there.
API calls in the /route-optimizer path require separate credits allocated to the x-api-key.
If you are interested in the paid optimization APIs please contact us at support@routescanner.com.
If you have any other questions or concerns, please don't hesitate to contact us.
The base url for all our APIs is https://connect.routescanner.com/
Routescanner uses HTTP response codes to indicate the success or failure of an API request. General HTML status codes:
- 2xx: Success.
- 4xx: Errors based on information provided in the request
- 5xx: Errors on Routescanner servers
We are supporting the following error codes:
Routescanner HTTP Status Codes
| HTTP CODE | TYPE | DESCRIPTION |
|---|---|---|
| 400 | Incorrect Values | Invalid values were supplied for the API request. |
| 400 | Type Required | Batch request types parameter requires a valid value. |
| 401 | No Key | An API key is required to access the requested endpoint. |
| 402 | Over Limit | You have exceeded your credit total, please purchase additional tokens. Contac support for assistance. |
| 402 | Free Tier Not Allowed | The requested endpoint is not available to free accounts. |
| 403 | Invalid Key | The provided API token is not valid. |
| 403 | Inactive | Your account is currently inactive. |
| 404 | Unknown Data | Unknown data provided. |
| 404 | Not Found | Resource not found. |
| 429 | Too Many Requests | Too many requests hit the API too quickly. An exponential backoff of your requests is recommended. |
| 500 | System Error | Something went wrong on the Routescanner server. |
Find terminals
Search for terminals in the Routescanner system for use in emissions queries.
Authorizations:
query Parameters
| terminalLocode required | string Locode where the terminal is located. |
| terminalName | string Name of terminal. We will try to match it with names found in our system. If left empty, will return all terminals within the supplied locode. |
Responses
Response samples
- 200
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "locode": "string"
}
]Get emissions
Get emissions between two points using the given modality.
Authorizations:
query Parameters
| origin required | string Origin of voyage. Can be a locode or a lat,long |
| destination required | string Destination of voyage. Can be a locode or a lat,long |
| modality required | string Modality of voyage. Can be one of [ |
| vesselInfo | string Optional vessel information. Can be dimensions (length, width, draught) in cm or ship IMO/MMSI. Example: |
| containerType | string Optional container type information. Can be |
| fuelType | string Optional fuel type information.
|
Responses
Response samples
- 200
{- "co2eTeu": 0.1,
- "co2eTon": 0.1,
- "distance": 0
}Get voyage options
Retrieves multimodal transport routes between specified origin and destination points.
⚠️ This API is only accessible after explicit access has been granted. If you wish to gain access, please contact us at support@routescanner.com.
Authorizations:
query Parameters
| origin required | string Starting location identifier (e.g., locode, terminal UUID, or lat,lng coordinates) |
| originType required | string Type of origin location ( |
| destination required | string Ending location identifier (e.g., locode, terminal UUID, or lat,lng coordinates) |
| destinationType required | string Type of destination location ( |
| modalities | Array of strings Items Enum: "DEEPSEA" "SHORTSEA" "BARGE" "RAIL" "TRUCK" Transport modes to include in route options. If not specified, all modes will be considered |
| minDeparture | string <date> Earliest acceptable departure date for the first leg of the journey |
| maxDeparture | string <date> Latest acceptable departure date for the first leg of the journey |
| maxArrival | string <date> Latest acceptable arrival date at the final destination |
| maxTransfers | integer <int32> Maximum number of transfers allowed in the route |
| allRequiredOperators | Array of strings List of operators that must ALL be included in the route options |
| anyRequiredOperators | Array of strings List of operators where at least ONE must be included in the route options |
| excludedOperators | Array of strings List of operators to explicitly exclude from route options |
| anyRequiredLocodes | Array of strings UN/LOCODE locations where at least ONE must be included in the route |
| allRequiredLocodes | Array of strings UN/LOCODE locations that must ALL be included in the route |
| excludedLocodes | Array of strings UN/LOCODE locations to explicitly exclude from route options |
| maxFirstMileTruckingKm | integer <int32> Maximum distance in kilometers allowed for initial trucking segment from origin to first terminal |
| maxLastMileTruckingKm | integer <int32> Maximum distance in kilometers allowed for final trucking segment from last terminal to destination |
| sort | string Sorting criteria for results ( |
| directSeaOnly | boolean When true, only return routes with direct sea connections without transshipments between sea legs |
| maxEmission | integer <int64> Maximum total CO₂e emissions in kilograms allowed for the entire route |
| maxLeadTime | string <ISO-8601 duration> Maximum total transit time allowed for the journey in ISO-8601 duration format (e.g., |
Responses
Response samples
- 200
{- "results": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "leadTimeInMinutes": 0,
- "latestDropOff": "2019-08-24T14:15:22Z",
- "earliestPickup": "2019-08-24T14:15:22Z",
- "emissionsInKgCo2e": 0,
- "transfers": 0,
- "transferEmissionsInKgCo2e": 0,
- "truckToOriginInMeters": 0,
- "truckToDestinationInMeters": 0,
- "legs": [
- {
- "origin": "string",
- "originTerminals": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string"
}
], - "destination": "string",
- "destinationTerminals": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string"
}
], - "modality": "string",
- "operators": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "scac": "string",
- "serviceCodes": [
- "string"
], - "collaboratingOperators": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "scac": "string"
}
]
}
], - "departureDate": "2019-08-24T14:15:22Z",
- "arrivalDate": "2019-08-24T14:15:22Z",
- "distanceInMeters": 0,
- "emissionsInKgCo2e": 0,
- "vessel": {
- "name": "string",
- "imo": "string",
- "mmsi": "string"
}
}
]
}
]
}Get all operators
Retrieves all operators known to Routescanner with their internal identifier and Standard Carrier Alpha Code (SCAC).
⚠️ This API is only accessible after explicit access has been granted. If you wish to gain access, please contact us at support@routescanner.com.
Authorizations:
Responses
Response samples
- 200
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "scac": "string"
}