Routescanner OpenAPI Definition
1.0

The Routescanner platform enables users to access comprehensive distance and emission 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.

This is the documentation for version 1.0 of the API. Last update on Mar 16, 2023.

Base URL 
https://connect.routescanner.com/route-information

Api-key

To access our APIs, you will need a personal API key. To obtain one, create an account on Routescanner.com, log in, and then select "API" from the menu under your name on the right 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’

Credits

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.

If you would like to learn more about purchasing credits please go to https://www.routescanner.com/features/distance-emissions-api All the necessary information and the best options for purchasing credits can be found there.
If you have any other questions or concerns, please don't hesitate to contact us.

Base Url

The base-url is https://connect.routescanner.com/route-information

Error Codes

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 working to improve our error handling by 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.

Distance

Get distance between two points using the given modality.

GET /api/distance

Query parameters

  • origin string Required

    Origin of voyage. Can be a locode, a terminal UUID, or a lat,long

  • destination string Required

    Destination of voyage. Can be a locode, a terminal UUID, or a lat,long

  • modality string Required

    Modality of voyage. Can be DEEPSEA, SHORTSEA, BARGE, RAIL or TRUCK

Responses

  • • 200 object

    Calculated the distance in meters

  • • 204

    The distance couldn't be calculated because a route could not be found

  • • 400

    Bad request, query parameters were wrong

  • • 500

    Something went wrong on our side.

GET /api/distance 
curl \
 -X GET https://connect.routescanner.com/route-information/api/distance?origin=string&destination=string&modality=string
Response example (200) 
{
  "distance": 42
}

Emissions

Get emissions between two points using the given modality.

GET /api/emissions

Query parameters

  • origin string Required

    Origin of voyage. Can be a locode or a lat,long

  • destination string Required

    Destination of voyage. Can be a locode or a lat,long

  • modality string Required

    Modality of voyage. Can be DEEPSEA, SHORTSEA, BARGE, RAIL or TRUCK

Responses

  • • 200 object

    Calculated the emissions in CO2eTeu, C02eTon and the distance in meters

  • • 204

    The emissions couldn't be calculated because a route could not be found

  • • 400

    Bad request, query parameters were wrong

  • • 500

    Something went wrong on our side.

GET /api/emissions 
curl \
 -X GET https://connect.routescanner.com/route-information/api/emissions?origin=string&destination=string&modality=string
Response example (200) 
{
  "co2eTeu": 42.0,
  "co2eTon": 42.0,
  "distance": 42
}

Terminals

Search for terminals in the routescanner system for use in distance and/or emissions queries.

GET /api/terminals

Query parameters

  • terminalLocode string Required

    Locode where 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 under locode.

Responses

  • • 200 array[object]

    Found terminals

  • • 204

    No terminals were found.

  • • 400

    Bad request, query parameters were wrong

  • • 500

    Something went wrong on our side.

GET /api/terminals 
curl \
 -X GET https://connect.routescanner.com/route-information/api/terminals?terminalLocode=string
Response example (200) 
[
  {
    "id": "string",
    "name": "string",
    "locode": "string"
  }
]