Calculate transport routes
curl --request POST \
--url https://api.terratwin.com/api/v1/transportation/routes/calculate \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"id": "123456789",
"options": {
"fallbackTransportModes": [
"ROAD",
"AIR"
]
},
"cargo": {
"category": "GENERAL"
},
"origin": {
"type": "PLACE",
"street": "221B Baker Street",
"postCode": "NW1 6XE",
"city": "London",
"country": "GB"
},
"destination": {
"type": "PLACE",
"street": "Rue Brederode 16",
"postCode": "1000",
"city": "Brussel",
"country": "BE"
},
"transportChain": [
{
"id": "123456789-01",
"type": "WATER",
"departureDateTime": "2025-12-25T00:00:00+00:00",
"arrivalDateTime": "2026-01-01T18:12:30Z",
"vehicle": "CONTAINER",
"navigationConstraints": [
"AVOID_KIEL_CANAL",
"AVOID_NORTHEAST_PASSAGE",
"AVOID_NORTHWEST_PASSAGE"
],
"context": {
"additionalInformation": "customWaterLegValue"
}
},
{
"type": "HUB",
"location": {
"type": "HARBOR",
"unLoCode": "BEANR"
}
},
{
"id": "123456789-02",
"type": "RAIL",
"departureDateTime": "2026-01-02T10:00:00+01:00",
"arrivalDateTime": "2026-01-02T22:00:00+01:00",
"trainType": "MANIFEST",
"energyType": "ELECTRICITY",
"context": {
"customProperty": "customRailLegValue"
}
}
]
}
'import requests
url = "https://api.terratwin.com/api/v1/transportation/routes/calculate"
payload = {
"id": "123456789",
"options": { "fallbackTransportModes": ["ROAD", "AIR"] },
"cargo": { "category": "GENERAL" },
"origin": {
"type": "PLACE",
"street": "221B Baker Street",
"postCode": "NW1 6XE",
"city": "London",
"country": "GB"
},
"destination": {
"type": "PLACE",
"street": "Rue Brederode 16",
"postCode": "1000",
"city": "Brussel",
"country": "BE"
},
"transportChain": [
{
"id": "123456789-01",
"type": "WATER",
"departureDateTime": "2025-12-25T00:00:00+00:00",
"arrivalDateTime": "2026-01-01T18:12:30Z",
"vehicle": "CONTAINER",
"navigationConstraints": ["AVOID_KIEL_CANAL", "AVOID_NORTHEAST_PASSAGE", "AVOID_NORTHWEST_PASSAGE"],
"context": { "additionalInformation": "customWaterLegValue" }
},
{
"type": "HUB",
"location": {
"type": "HARBOR",
"unLoCode": "BEANR"
}
},
{
"id": "123456789-02",
"type": "RAIL",
"departureDateTime": "2026-01-02T10:00:00+01:00",
"arrivalDateTime": "2026-01-02T22:00:00+01:00",
"trainType": "MANIFEST",
"energyType": "ELECTRICITY",
"context": { "customProperty": "customRailLegValue" }
}
]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
id: '123456789',
options: {fallbackTransportModes: ['ROAD', 'AIR']},
cargo: {category: 'GENERAL'},
origin: {
type: 'PLACE',
street: '221B Baker Street',
postCode: 'NW1 6XE',
city: 'London',
country: 'GB'
},
destination: {
type: 'PLACE',
street: 'Rue Brederode 16',
postCode: '1000',
city: 'Brussel',
country: 'BE'
},
transportChain: [
{
id: '123456789-01',
type: 'WATER',
departureDateTime: '2025-12-25T00:00:00+00:00',
arrivalDateTime: '2026-01-01T18:12:30Z',
vehicle: 'CONTAINER',
navigationConstraints: ['AVOID_KIEL_CANAL', 'AVOID_NORTHEAST_PASSAGE', 'AVOID_NORTHWEST_PASSAGE'],
context: {additionalInformation: 'customWaterLegValue'}
},
{type: 'HUB', location: {type: 'HARBOR', unLoCode: 'BEANR'}},
{
id: '123456789-02',
type: 'RAIL',
departureDateTime: '2026-01-02T10:00:00+01:00',
arrivalDateTime: '2026-01-02T22:00:00+01:00',
trainType: 'MANIFEST',
energyType: 'ELECTRICITY',
context: {customProperty: 'customRailLegValue'}
}
]
})
};
fetch('https://api.terratwin.com/api/v1/transportation/routes/calculate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.terratwin.com/api/v1/transportation/routes/calculate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'id' => '123456789',
'options' => [
'fallbackTransportModes' => [
'ROAD',
'AIR'
]
],
'cargo' => [
'category' => 'GENERAL'
],
'origin' => [
'type' => 'PLACE',
'street' => '221B Baker Street',
'postCode' => 'NW1 6XE',
'city' => 'London',
'country' => 'GB'
],
'destination' => [
'type' => 'PLACE',
'street' => 'Rue Brederode 16',
'postCode' => '1000',
'city' => 'Brussel',
'country' => 'BE'
],
'transportChain' => [
[
'id' => '123456789-01',
'type' => 'WATER',
'departureDateTime' => '2025-12-25T00:00:00+00:00',
'arrivalDateTime' => '2026-01-01T18:12:30Z',
'vehicle' => 'CONTAINER',
'navigationConstraints' => [
'AVOID_KIEL_CANAL',
'AVOID_NORTHEAST_PASSAGE',
'AVOID_NORTHWEST_PASSAGE'
],
'context' => [
'additionalInformation' => 'customWaterLegValue'
]
],
[
'type' => 'HUB',
'location' => [
'type' => 'HARBOR',
'unLoCode' => 'BEANR'
]
],
[
'id' => '123456789-02',
'type' => 'RAIL',
'departureDateTime' => '2026-01-02T10:00:00+01:00',
'arrivalDateTime' => '2026-01-02T22:00:00+01:00',
'trainType' => 'MANIFEST',
'energyType' => 'ELECTRICITY',
'context' => [
'customProperty' => 'customRailLegValue'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.terratwin.com/api/v1/transportation/routes/calculate"
payload := strings.NewReader("{\n \"id\": \"123456789\",\n \"options\": {\n \"fallbackTransportModes\": [\n \"ROAD\",\n \"AIR\"\n ]\n },\n \"cargo\": {\n \"category\": \"GENERAL\"\n },\n \"origin\": {\n \"type\": \"PLACE\",\n \"street\": \"221B Baker Street\",\n \"postCode\": \"NW1 6XE\",\n \"city\": \"London\",\n \"country\": \"GB\"\n },\n \"destination\": {\n \"type\": \"PLACE\",\n \"street\": \"Rue Brederode 16\",\n \"postCode\": \"1000\",\n \"city\": \"Brussel\",\n \"country\": \"BE\"\n },\n \"transportChain\": [\n {\n \"id\": \"123456789-01\",\n \"type\": \"WATER\",\n \"departureDateTime\": \"2025-12-25T00:00:00+00:00\",\n \"arrivalDateTime\": \"2026-01-01T18:12:30Z\",\n \"vehicle\": \"CONTAINER\",\n \"navigationConstraints\": [\n \"AVOID_KIEL_CANAL\",\n \"AVOID_NORTHEAST_PASSAGE\",\n \"AVOID_NORTHWEST_PASSAGE\"\n ],\n \"context\": {\n \"additionalInformation\": \"customWaterLegValue\"\n }\n },\n {\n \"type\": \"HUB\",\n \"location\": {\n \"type\": \"HARBOR\",\n \"unLoCode\": \"BEANR\"\n }\n },\n {\n \"id\": \"123456789-02\",\n \"type\": \"RAIL\",\n \"departureDateTime\": \"2026-01-02T10:00:00+01:00\",\n \"arrivalDateTime\": \"2026-01-02T22:00:00+01:00\",\n \"trainType\": \"MANIFEST\",\n \"energyType\": \"ELECTRICITY\",\n \"context\": {\n \"customProperty\": \"customRailLegValue\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.terratwin.com/api/v1/transportation/routes/calculate")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"id\": \"123456789\",\n \"options\": {\n \"fallbackTransportModes\": [\n \"ROAD\",\n \"AIR\"\n ]\n },\n \"cargo\": {\n \"category\": \"GENERAL\"\n },\n \"origin\": {\n \"type\": \"PLACE\",\n \"street\": \"221B Baker Street\",\n \"postCode\": \"NW1 6XE\",\n \"city\": \"London\",\n \"country\": \"GB\"\n },\n \"destination\": {\n \"type\": \"PLACE\",\n \"street\": \"Rue Brederode 16\",\n \"postCode\": \"1000\",\n \"city\": \"Brussel\",\n \"country\": \"BE\"\n },\n \"transportChain\": [\n {\n \"id\": \"123456789-01\",\n \"type\": \"WATER\",\n \"departureDateTime\": \"2025-12-25T00:00:00+00:00\",\n \"arrivalDateTime\": \"2026-01-01T18:12:30Z\",\n \"vehicle\": \"CONTAINER\",\n \"navigationConstraints\": [\n \"AVOID_KIEL_CANAL\",\n \"AVOID_NORTHEAST_PASSAGE\",\n \"AVOID_NORTHWEST_PASSAGE\"\n ],\n \"context\": {\n \"additionalInformation\": \"customWaterLegValue\"\n }\n },\n {\n \"type\": \"HUB\",\n \"location\": {\n \"type\": \"HARBOR\",\n \"unLoCode\": \"BEANR\"\n }\n },\n {\n \"id\": \"123456789-02\",\n \"type\": \"RAIL\",\n \"departureDateTime\": \"2026-01-02T10:00:00+01:00\",\n \"arrivalDateTime\": \"2026-01-02T22:00:00+01:00\",\n \"trainType\": \"MANIFEST\",\n \"energyType\": \"ELECTRICITY\",\n \"context\": {\n \"customProperty\": \"customRailLegValue\"\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.terratwin.com/api/v1/transportation/routes/calculate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"id\": \"123456789\",\n \"options\": {\n \"fallbackTransportModes\": [\n \"ROAD\",\n \"AIR\"\n ]\n },\n \"cargo\": {\n \"category\": \"GENERAL\"\n },\n \"origin\": {\n \"type\": \"PLACE\",\n \"street\": \"221B Baker Street\",\n \"postCode\": \"NW1 6XE\",\n \"city\": \"London\",\n \"country\": \"GB\"\n },\n \"destination\": {\n \"type\": \"PLACE\",\n \"street\": \"Rue Brederode 16\",\n \"postCode\": \"1000\",\n \"city\": \"Brussel\",\n \"country\": \"BE\"\n },\n \"transportChain\": [\n {\n \"id\": \"123456789-01\",\n \"type\": \"WATER\",\n \"departureDateTime\": \"2025-12-25T00:00:00+00:00\",\n \"arrivalDateTime\": \"2026-01-01T18:12:30Z\",\n \"vehicle\": \"CONTAINER\",\n \"navigationConstraints\": [\n \"AVOID_KIEL_CANAL\",\n \"AVOID_NORTHEAST_PASSAGE\",\n \"AVOID_NORTHWEST_PASSAGE\"\n ],\n \"context\": {\n \"additionalInformation\": \"customWaterLegValue\"\n }\n },\n {\n \"type\": \"HUB\",\n \"location\": {\n \"type\": \"HARBOR\",\n \"unLoCode\": \"BEANR\"\n }\n },\n {\n \"id\": \"123456789-02\",\n \"type\": \"RAIL\",\n \"departureDateTime\": \"2026-01-02T10:00:00+01:00\",\n \"arrivalDateTime\": \"2026-01-02T22:00:00+01:00\",\n \"trainType\": \"MANIFEST\",\n \"energyType\": \"ELECTRICITY\",\n \"context\": {\n \"customProperty\": \"customRailLegValue\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "123456789",
"origin": {
"type": "PLACE",
"countryCode": "GB",
"latitude": 51.5237629,
"longitude": -0.1584743,
"region": "England",
"postcode": "NW1 6XE",
"city": "London",
"street": "221B Baker Street",
"name": "Sherlock Holmes Museum",
"formatted": "Sherlock Holmes Museum\n221B Baker Street\nMarylebone\nLondon\nNW1 6XE\nUnited Kingdom"
},
"destination": {
"type": "PLACE",
"countryCode": "BE",
"latitude": 50.8405365,
"longitude": 4.3622675,
"region": "Brussels-Capital",
"postcode": "1000",
"city": "Brussels",
"street": "Rue Brederode - Brederodestraat 16",
"formatted": "Rue Brederode - Brederodestraat 16\n1000 Brussels\nBelgium"
},
"distanceKm": 428.17868397480544,
"transportChain": [
{
"type": "WATER",
"id": "123456789-01",
"start": {
"type": "PLACE",
"countryCode": "GB",
"latitude": 51.5237629,
"longitude": -0.1584743,
"region": "England",
"postcode": "NW1 6XE",
"city": "London",
"street": "221B Baker Street",
"name": "Sherlock Holmes Museum",
"formatted": "Sherlock Holmes Museum\n221B Baker Street\nMarylebone\nLondon\nNW1 6XE\nUnited Kingdom"
},
"end": {
"type": "HARBOR",
"countryCode": "BE",
"latitude": 51.27936713324465,
"longitude": 4.3567657470703125,
"region": "Antwerp",
"postcode": "2030",
"city": "Antwerp",
"name": "Port of Antwerp",
"code": "BEANR",
"formatted": "Port of Antwerp\n2030 Antwerp\nBelgium"
},
"distanceKm": 361.25686120325236,
"context": {
"additionalInformation": "customWaterLegValue"
},
"elements": [
{
"type": "ROAD",
"start": {
"type": "PLACE",
"countryCode": "GB",
"latitude": 51.5237629,
"longitude": -0.1584743,
"region": "England",
"postcode": "NW1 6XE",
"city": "London",
"street": "221B Baker Street",
"name": "Sherlock Holmes Museum",
"formatted": "Sherlock Holmes Museum\n221B Baker Street\nMarylebone\nLondon\nNW1 6XE\nUnited Kingdom"
},
"end": {
"type": "HARBOR",
"countryCode": "GB",
"latitude": 51.459502138725945,
"longitude": 0.3407907485961914,
"region": "England",
"postcode": "RM18 7DP",
"city": "Tilbury",
"name": "Port of Tilbury",
"code": "GBTIL",
"formatted": "Port of Tilbury\nTilbury\nRM18 7DP\nUnited Kingdom of Great Britain and Northern Ireland"
},
"distanceKm": 47.708259845301605
},
{
"vehicle": "CONTAINER",
"capacityBand": "POST_PANAMAX",
"type": "WATER",
"start": {
"type": "HARBOR",
"countryCode": "GB",
"latitude": 51.459502138725945,
"longitude": 0.3407907485961914,
"region": "England",
"postcode": "RM18 7DP",
"city": "Tilbury",
"name": "Port of Tilbury",
"code": "GBTIL",
"formatted": "Port of Tilbury\nTilbury\nRM18 7DP\nUnited Kingdom of Great Britain and Northern Ireland"
},
"end": {
"type": "HARBOR",
"countryCode": "BE",
"latitude": 51.27936713324465,
"longitude": 4.3567657470703125,
"region": "Antwerp",
"postcode": "2030",
"city": "Antwerp",
"name": "Port of Antwerp",
"code": "BEANR",
"formatted": "Port of Antwerp\n2030 Antwerp\nBelgium"
},
"distanceKm": 313.54860135795076
}
]
},
{
"type": "RAIL",
"id": "123456789-02",
"start": {
"type": "PLACE",
"countryCode": "BE",
"latitude": 51.279002,
"longitude": 4.356769,
"region": "Antwerp",
"postcode": "2030",
"city": "Antwerp",
"formatted": "2030 Antwerp\nBelgium"
},
"end": {
"type": "PLACE",
"countryCode": "BE",
"latitude": 50.8405365,
"longitude": 4.3622675,
"region": "Brussels-Capital",
"postcode": "1000",
"city": "Brussels",
"street": "Rue Brederode - Brederodestraat 16",
"formatted": "Rue Brederode - Brederodestraat 16\n1000 Brussels\nBelgium"
},
"distanceKm": 66.92182277155307,
"context": {
"customProperty": "customRailLegValue"
},
"elements": [
{
"type": "RAIL",
"start": {
"type": "PLACE",
"countryCode": "BE",
"latitude": 51.279002,
"longitude": 4.356769,
"region": "Antwerp",
"postcode": "2030",
"city": "Antwerp",
"formatted": "2030 Antwerp\nBelgium"
},
"end": {
"type": "PLACE",
"countryCode": "BE",
"latitude": 50.844459,
"longitude": 4.356229,
"region": "Brussels-Capital",
"postcode": "1000",
"city": "Brussels",
"formatted": "Pentagon\n1000 Brussels\nBrussels-Capital\nBelgium"
},
"distanceKm": 65.84587562993619
},
{
"type": "ROAD",
"start": {
"type": "PLACE",
"countryCode": "BE",
"latitude": 50.844459,
"longitude": 4.356229,
"region": "Brussels-Capital",
"postcode": "1000",
"city": "Brussels",
"formatted": "Pentagon\n1000 Brussels\nBrussels-Capital\nBelgium"
},
"end": {
"type": "PLACE",
"countryCode": "BE",
"latitude": 50.8405365,
"longitude": 4.3622675,
"region": "Brussels-Capital",
"postcode": "1000",
"city": "Brussels",
"street": "Rue Brederode - Brederodestraat 16",
"formatted": "Rue Brederode - Brederodestraat 16\n1000 Brussels\nBelgium"
},
"distanceKm": 1.075947141616878
}
]
}
],
"creditCost": 4
}{
"title": "Invalid property value",
"status": 400,
"code": 5,
"details": [
"Property 'type' contains invalid value 'WEIGHTED_MODES'"
],
"instance": "/api/v1/transportation/routes/calculate",
"recommendation": "Alter your request to use one of these values: UNKNOWN,AIR,RAIL,ROAD,WATER,HUB"
}{
"title": "API key invalid",
"status": 401,
"code": 41,
"details": [
"'...' is not a valid API key"
],
"instance": "/api/v1/transportation/routes/calculate",
"recommendation": "Provide a valid API key. If you don’t have one, then apply to TerraTwin"
}{
"title": "Insufficient credits",
"status": 403,
"code": 42,
"details": [
"Your account has no remaining credits"
],
"instance": "/api/v1/transportation/routes/calculate",
"recommendation": "Purchase additional credits from TerraTwin"
}{
"title": "Not routable by rail",
"status": 422,
"code": 33,
"details": [
"Operation 'transportChain[0]' could not be routed by rail between '50.68689,7.16285' and '-36.85209,174.76318'"
],
"instance": "/api/v1/transportation/routes/calculate",
"recommendation": "Review the mode of transport selected and the locations"
}{
"title": "Rate limit exceeded",
"status": 429,
"code": 45,
"details": [
"Too many requests. The limit is 5 requests per second"
],
"instance": "/api/v1/transportation/routes/calculate",
"recommendation": "Reduce your request rate to ≤ 5 requests/second"
}{
"title": "<string>",
"status": 123,
"code": 1,
"details": [
"<string>"
],
"instance": "<string>",
"recommendation": "<string>"
}{
"title": "<string>",
"status": 123,
"code": 1,
"details": [
"<string>"
],
"instance": "<string>",
"recommendation": "<string>"
}Endpoints
Calculate transport routes
Calculates the routes and distances of a transport chain without calculating emissions. Locations, transport modes, and fallback transport modes are handled exactly as for an emissions calculation, so the distances match those used there. The response contains the resolved locations, distances, and optionally route polylines. WEIGHTED_MODES transport operations are not supported.
POST
/
routes
/
calculate
Calculate transport routes
curl --request POST \
--url https://api.terratwin.com/api/v1/transportation/routes/calculate \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"id": "123456789",
"options": {
"fallbackTransportModes": [
"ROAD",
"AIR"
]
},
"cargo": {
"category": "GENERAL"
},
"origin": {
"type": "PLACE",
"street": "221B Baker Street",
"postCode": "NW1 6XE",
"city": "London",
"country": "GB"
},
"destination": {
"type": "PLACE",
"street": "Rue Brederode 16",
"postCode": "1000",
"city": "Brussel",
"country": "BE"
},
"transportChain": [
{
"id": "123456789-01",
"type": "WATER",
"departureDateTime": "2025-12-25T00:00:00+00:00",
"arrivalDateTime": "2026-01-01T18:12:30Z",
"vehicle": "CONTAINER",
"navigationConstraints": [
"AVOID_KIEL_CANAL",
"AVOID_NORTHEAST_PASSAGE",
"AVOID_NORTHWEST_PASSAGE"
],
"context": {
"additionalInformation": "customWaterLegValue"
}
},
{
"type": "HUB",
"location": {
"type": "HARBOR",
"unLoCode": "BEANR"
}
},
{
"id": "123456789-02",
"type": "RAIL",
"departureDateTime": "2026-01-02T10:00:00+01:00",
"arrivalDateTime": "2026-01-02T22:00:00+01:00",
"trainType": "MANIFEST",
"energyType": "ELECTRICITY",
"context": {
"customProperty": "customRailLegValue"
}
}
]
}
'import requests
url = "https://api.terratwin.com/api/v1/transportation/routes/calculate"
payload = {
"id": "123456789",
"options": { "fallbackTransportModes": ["ROAD", "AIR"] },
"cargo": { "category": "GENERAL" },
"origin": {
"type": "PLACE",
"street": "221B Baker Street",
"postCode": "NW1 6XE",
"city": "London",
"country": "GB"
},
"destination": {
"type": "PLACE",
"street": "Rue Brederode 16",
"postCode": "1000",
"city": "Brussel",
"country": "BE"
},
"transportChain": [
{
"id": "123456789-01",
"type": "WATER",
"departureDateTime": "2025-12-25T00:00:00+00:00",
"arrivalDateTime": "2026-01-01T18:12:30Z",
"vehicle": "CONTAINER",
"navigationConstraints": ["AVOID_KIEL_CANAL", "AVOID_NORTHEAST_PASSAGE", "AVOID_NORTHWEST_PASSAGE"],
"context": { "additionalInformation": "customWaterLegValue" }
},
{
"type": "HUB",
"location": {
"type": "HARBOR",
"unLoCode": "BEANR"
}
},
{
"id": "123456789-02",
"type": "RAIL",
"departureDateTime": "2026-01-02T10:00:00+01:00",
"arrivalDateTime": "2026-01-02T22:00:00+01:00",
"trainType": "MANIFEST",
"energyType": "ELECTRICITY",
"context": { "customProperty": "customRailLegValue" }
}
]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
id: '123456789',
options: {fallbackTransportModes: ['ROAD', 'AIR']},
cargo: {category: 'GENERAL'},
origin: {
type: 'PLACE',
street: '221B Baker Street',
postCode: 'NW1 6XE',
city: 'London',
country: 'GB'
},
destination: {
type: 'PLACE',
street: 'Rue Brederode 16',
postCode: '1000',
city: 'Brussel',
country: 'BE'
},
transportChain: [
{
id: '123456789-01',
type: 'WATER',
departureDateTime: '2025-12-25T00:00:00+00:00',
arrivalDateTime: '2026-01-01T18:12:30Z',
vehicle: 'CONTAINER',
navigationConstraints: ['AVOID_KIEL_CANAL', 'AVOID_NORTHEAST_PASSAGE', 'AVOID_NORTHWEST_PASSAGE'],
context: {additionalInformation: 'customWaterLegValue'}
},
{type: 'HUB', location: {type: 'HARBOR', unLoCode: 'BEANR'}},
{
id: '123456789-02',
type: 'RAIL',
departureDateTime: '2026-01-02T10:00:00+01:00',
arrivalDateTime: '2026-01-02T22:00:00+01:00',
trainType: 'MANIFEST',
energyType: 'ELECTRICITY',
context: {customProperty: 'customRailLegValue'}
}
]
})
};
fetch('https://api.terratwin.com/api/v1/transportation/routes/calculate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.terratwin.com/api/v1/transportation/routes/calculate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'id' => '123456789',
'options' => [
'fallbackTransportModes' => [
'ROAD',
'AIR'
]
],
'cargo' => [
'category' => 'GENERAL'
],
'origin' => [
'type' => 'PLACE',
'street' => '221B Baker Street',
'postCode' => 'NW1 6XE',
'city' => 'London',
'country' => 'GB'
],
'destination' => [
'type' => 'PLACE',
'street' => 'Rue Brederode 16',
'postCode' => '1000',
'city' => 'Brussel',
'country' => 'BE'
],
'transportChain' => [
[
'id' => '123456789-01',
'type' => 'WATER',
'departureDateTime' => '2025-12-25T00:00:00+00:00',
'arrivalDateTime' => '2026-01-01T18:12:30Z',
'vehicle' => 'CONTAINER',
'navigationConstraints' => [
'AVOID_KIEL_CANAL',
'AVOID_NORTHEAST_PASSAGE',
'AVOID_NORTHWEST_PASSAGE'
],
'context' => [
'additionalInformation' => 'customWaterLegValue'
]
],
[
'type' => 'HUB',
'location' => [
'type' => 'HARBOR',
'unLoCode' => 'BEANR'
]
],
[
'id' => '123456789-02',
'type' => 'RAIL',
'departureDateTime' => '2026-01-02T10:00:00+01:00',
'arrivalDateTime' => '2026-01-02T22:00:00+01:00',
'trainType' => 'MANIFEST',
'energyType' => 'ELECTRICITY',
'context' => [
'customProperty' => 'customRailLegValue'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.terratwin.com/api/v1/transportation/routes/calculate"
payload := strings.NewReader("{\n \"id\": \"123456789\",\n \"options\": {\n \"fallbackTransportModes\": [\n \"ROAD\",\n \"AIR\"\n ]\n },\n \"cargo\": {\n \"category\": \"GENERAL\"\n },\n \"origin\": {\n \"type\": \"PLACE\",\n \"street\": \"221B Baker Street\",\n \"postCode\": \"NW1 6XE\",\n \"city\": \"London\",\n \"country\": \"GB\"\n },\n \"destination\": {\n \"type\": \"PLACE\",\n \"street\": \"Rue Brederode 16\",\n \"postCode\": \"1000\",\n \"city\": \"Brussel\",\n \"country\": \"BE\"\n },\n \"transportChain\": [\n {\n \"id\": \"123456789-01\",\n \"type\": \"WATER\",\n \"departureDateTime\": \"2025-12-25T00:00:00+00:00\",\n \"arrivalDateTime\": \"2026-01-01T18:12:30Z\",\n \"vehicle\": \"CONTAINER\",\n \"navigationConstraints\": [\n \"AVOID_KIEL_CANAL\",\n \"AVOID_NORTHEAST_PASSAGE\",\n \"AVOID_NORTHWEST_PASSAGE\"\n ],\n \"context\": {\n \"additionalInformation\": \"customWaterLegValue\"\n }\n },\n {\n \"type\": \"HUB\",\n \"location\": {\n \"type\": \"HARBOR\",\n \"unLoCode\": \"BEANR\"\n }\n },\n {\n \"id\": \"123456789-02\",\n \"type\": \"RAIL\",\n \"departureDateTime\": \"2026-01-02T10:00:00+01:00\",\n \"arrivalDateTime\": \"2026-01-02T22:00:00+01:00\",\n \"trainType\": \"MANIFEST\",\n \"energyType\": \"ELECTRICITY\",\n \"context\": {\n \"customProperty\": \"customRailLegValue\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.terratwin.com/api/v1/transportation/routes/calculate")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"id\": \"123456789\",\n \"options\": {\n \"fallbackTransportModes\": [\n \"ROAD\",\n \"AIR\"\n ]\n },\n \"cargo\": {\n \"category\": \"GENERAL\"\n },\n \"origin\": {\n \"type\": \"PLACE\",\n \"street\": \"221B Baker Street\",\n \"postCode\": \"NW1 6XE\",\n \"city\": \"London\",\n \"country\": \"GB\"\n },\n \"destination\": {\n \"type\": \"PLACE\",\n \"street\": \"Rue Brederode 16\",\n \"postCode\": \"1000\",\n \"city\": \"Brussel\",\n \"country\": \"BE\"\n },\n \"transportChain\": [\n {\n \"id\": \"123456789-01\",\n \"type\": \"WATER\",\n \"departureDateTime\": \"2025-12-25T00:00:00+00:00\",\n \"arrivalDateTime\": \"2026-01-01T18:12:30Z\",\n \"vehicle\": \"CONTAINER\",\n \"navigationConstraints\": [\n \"AVOID_KIEL_CANAL\",\n \"AVOID_NORTHEAST_PASSAGE\",\n \"AVOID_NORTHWEST_PASSAGE\"\n ],\n \"context\": {\n \"additionalInformation\": \"customWaterLegValue\"\n }\n },\n {\n \"type\": \"HUB\",\n \"location\": {\n \"type\": \"HARBOR\",\n \"unLoCode\": \"BEANR\"\n }\n },\n {\n \"id\": \"123456789-02\",\n \"type\": \"RAIL\",\n \"departureDateTime\": \"2026-01-02T10:00:00+01:00\",\n \"arrivalDateTime\": \"2026-01-02T22:00:00+01:00\",\n \"trainType\": \"MANIFEST\",\n \"energyType\": \"ELECTRICITY\",\n \"context\": {\n \"customProperty\": \"customRailLegValue\"\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.terratwin.com/api/v1/transportation/routes/calculate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"id\": \"123456789\",\n \"options\": {\n \"fallbackTransportModes\": [\n \"ROAD\",\n \"AIR\"\n ]\n },\n \"cargo\": {\n \"category\": \"GENERAL\"\n },\n \"origin\": {\n \"type\": \"PLACE\",\n \"street\": \"221B Baker Street\",\n \"postCode\": \"NW1 6XE\",\n \"city\": \"London\",\n \"country\": \"GB\"\n },\n \"destination\": {\n \"type\": \"PLACE\",\n \"street\": \"Rue Brederode 16\",\n \"postCode\": \"1000\",\n \"city\": \"Brussel\",\n \"country\": \"BE\"\n },\n \"transportChain\": [\n {\n \"id\": \"123456789-01\",\n \"type\": \"WATER\",\n \"departureDateTime\": \"2025-12-25T00:00:00+00:00\",\n \"arrivalDateTime\": \"2026-01-01T18:12:30Z\",\n \"vehicle\": \"CONTAINER\",\n \"navigationConstraints\": [\n \"AVOID_KIEL_CANAL\",\n \"AVOID_NORTHEAST_PASSAGE\",\n \"AVOID_NORTHWEST_PASSAGE\"\n ],\n \"context\": {\n \"additionalInformation\": \"customWaterLegValue\"\n }\n },\n {\n \"type\": \"HUB\",\n \"location\": {\n \"type\": \"HARBOR\",\n \"unLoCode\": \"BEANR\"\n }\n },\n {\n \"id\": \"123456789-02\",\n \"type\": \"RAIL\",\n \"departureDateTime\": \"2026-01-02T10:00:00+01:00\",\n \"arrivalDateTime\": \"2026-01-02T22:00:00+01:00\",\n \"trainType\": \"MANIFEST\",\n \"energyType\": \"ELECTRICITY\",\n \"context\": {\n \"customProperty\": \"customRailLegValue\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "123456789",
"origin": {
"type": "PLACE",
"countryCode": "GB",
"latitude": 51.5237629,
"longitude": -0.1584743,
"region": "England",
"postcode": "NW1 6XE",
"city": "London",
"street": "221B Baker Street",
"name": "Sherlock Holmes Museum",
"formatted": "Sherlock Holmes Museum\n221B Baker Street\nMarylebone\nLondon\nNW1 6XE\nUnited Kingdom"
},
"destination": {
"type": "PLACE",
"countryCode": "BE",
"latitude": 50.8405365,
"longitude": 4.3622675,
"region": "Brussels-Capital",
"postcode": "1000",
"city": "Brussels",
"street": "Rue Brederode - Brederodestraat 16",
"formatted": "Rue Brederode - Brederodestraat 16\n1000 Brussels\nBelgium"
},
"distanceKm": 428.17868397480544,
"transportChain": [
{
"type": "WATER",
"id": "123456789-01",
"start": {
"type": "PLACE",
"countryCode": "GB",
"latitude": 51.5237629,
"longitude": -0.1584743,
"region": "England",
"postcode": "NW1 6XE",
"city": "London",
"street": "221B Baker Street",
"name": "Sherlock Holmes Museum",
"formatted": "Sherlock Holmes Museum\n221B Baker Street\nMarylebone\nLondon\nNW1 6XE\nUnited Kingdom"
},
"end": {
"type": "HARBOR",
"countryCode": "BE",
"latitude": 51.27936713324465,
"longitude": 4.3567657470703125,
"region": "Antwerp",
"postcode": "2030",
"city": "Antwerp",
"name": "Port of Antwerp",
"code": "BEANR",
"formatted": "Port of Antwerp\n2030 Antwerp\nBelgium"
},
"distanceKm": 361.25686120325236,
"context": {
"additionalInformation": "customWaterLegValue"
},
"elements": [
{
"type": "ROAD",
"start": {
"type": "PLACE",
"countryCode": "GB",
"latitude": 51.5237629,
"longitude": -0.1584743,
"region": "England",
"postcode": "NW1 6XE",
"city": "London",
"street": "221B Baker Street",
"name": "Sherlock Holmes Museum",
"formatted": "Sherlock Holmes Museum\n221B Baker Street\nMarylebone\nLondon\nNW1 6XE\nUnited Kingdom"
},
"end": {
"type": "HARBOR",
"countryCode": "GB",
"latitude": 51.459502138725945,
"longitude": 0.3407907485961914,
"region": "England",
"postcode": "RM18 7DP",
"city": "Tilbury",
"name": "Port of Tilbury",
"code": "GBTIL",
"formatted": "Port of Tilbury\nTilbury\nRM18 7DP\nUnited Kingdom of Great Britain and Northern Ireland"
},
"distanceKm": 47.708259845301605
},
{
"vehicle": "CONTAINER",
"capacityBand": "POST_PANAMAX",
"type": "WATER",
"start": {
"type": "HARBOR",
"countryCode": "GB",
"latitude": 51.459502138725945,
"longitude": 0.3407907485961914,
"region": "England",
"postcode": "RM18 7DP",
"city": "Tilbury",
"name": "Port of Tilbury",
"code": "GBTIL",
"formatted": "Port of Tilbury\nTilbury\nRM18 7DP\nUnited Kingdom of Great Britain and Northern Ireland"
},
"end": {
"type": "HARBOR",
"countryCode": "BE",
"latitude": 51.27936713324465,
"longitude": 4.3567657470703125,
"region": "Antwerp",
"postcode": "2030",
"city": "Antwerp",
"name": "Port of Antwerp",
"code": "BEANR",
"formatted": "Port of Antwerp\n2030 Antwerp\nBelgium"
},
"distanceKm": 313.54860135795076
}
]
},
{
"type": "RAIL",
"id": "123456789-02",
"start": {
"type": "PLACE",
"countryCode": "BE",
"latitude": 51.279002,
"longitude": 4.356769,
"region": "Antwerp",
"postcode": "2030",
"city": "Antwerp",
"formatted": "2030 Antwerp\nBelgium"
},
"end": {
"type": "PLACE",
"countryCode": "BE",
"latitude": 50.8405365,
"longitude": 4.3622675,
"region": "Brussels-Capital",
"postcode": "1000",
"city": "Brussels",
"street": "Rue Brederode - Brederodestraat 16",
"formatted": "Rue Brederode - Brederodestraat 16\n1000 Brussels\nBelgium"
},
"distanceKm": 66.92182277155307,
"context": {
"customProperty": "customRailLegValue"
},
"elements": [
{
"type": "RAIL",
"start": {
"type": "PLACE",
"countryCode": "BE",
"latitude": 51.279002,
"longitude": 4.356769,
"region": "Antwerp",
"postcode": "2030",
"city": "Antwerp",
"formatted": "2030 Antwerp\nBelgium"
},
"end": {
"type": "PLACE",
"countryCode": "BE",
"latitude": 50.844459,
"longitude": 4.356229,
"region": "Brussels-Capital",
"postcode": "1000",
"city": "Brussels",
"formatted": "Pentagon\n1000 Brussels\nBrussels-Capital\nBelgium"
},
"distanceKm": 65.84587562993619
},
{
"type": "ROAD",
"start": {
"type": "PLACE",
"countryCode": "BE",
"latitude": 50.844459,
"longitude": 4.356229,
"region": "Brussels-Capital",
"postcode": "1000",
"city": "Brussels",
"formatted": "Pentagon\n1000 Brussels\nBrussels-Capital\nBelgium"
},
"end": {
"type": "PLACE",
"countryCode": "BE",
"latitude": 50.8405365,
"longitude": 4.3622675,
"region": "Brussels-Capital",
"postcode": "1000",
"city": "Brussels",
"street": "Rue Brederode - Brederodestraat 16",
"formatted": "Rue Brederode - Brederodestraat 16\n1000 Brussels\nBelgium"
},
"distanceKm": 1.075947141616878
}
]
}
],
"creditCost": 4
}{
"title": "Invalid property value",
"status": 400,
"code": 5,
"details": [
"Property 'type' contains invalid value 'WEIGHTED_MODES'"
],
"instance": "/api/v1/transportation/routes/calculate",
"recommendation": "Alter your request to use one of these values: UNKNOWN,AIR,RAIL,ROAD,WATER,HUB"
}{
"title": "API key invalid",
"status": 401,
"code": 41,
"details": [
"'...' is not a valid API key"
],
"instance": "/api/v1/transportation/routes/calculate",
"recommendation": "Provide a valid API key. If you don’t have one, then apply to TerraTwin"
}{
"title": "Insufficient credits",
"status": 403,
"code": 42,
"details": [
"Your account has no remaining credits"
],
"instance": "/api/v1/transportation/routes/calculate",
"recommendation": "Purchase additional credits from TerraTwin"
}{
"title": "Not routable by rail",
"status": 422,
"code": 33,
"details": [
"Operation 'transportChain[0]' could not be routed by rail between '50.68689,7.16285' and '-36.85209,174.76318'"
],
"instance": "/api/v1/transportation/routes/calculate",
"recommendation": "Review the mode of transport selected and the locations"
}{
"title": "Rate limit exceeded",
"status": 429,
"code": 45,
"details": [
"Too many requests. The limit is 5 requests per second"
],
"instance": "/api/v1/transportation/routes/calculate",
"recommendation": "Reduce your request rate to ≤ 5 requests/second"
}{
"title": "<string>",
"status": 123,
"code": 1,
"details": [
"<string>"
],
"instance": "<string>",
"recommendation": "<string>"
}{
"title": "<string>",
"status": 123,
"code": 1,
"details": [
"<string>"
],
"instance": "<string>",
"recommendation": "<string>"
}Authorizations
API key for authenticating requests. Include this header in all calls.
Body
application/json
An identifier for the routes calculation, such as a shipment ID. It is returned in the response. Routes calculation results are not stored.
Used to customize routes calculations and to control which details are included in the response.
Show child attributes
Show child attributes
Optionally describes the transported goods. Only the cargo category is used: it determines the default vessel type for WATER transport operations, and so which harbors are selected. When not provided, the GENERAL category is used.
Show child attributes
Show child attributes
Locations resolve either to a transport facility (airport, harbor, or rail yard) or to a general geographic area such as a building, street, postcode, or city. For larger areas, centroids are used to represent the approximate position.
Identification and geocoding
- Airports and harbors can be identified directly by code (
iataCodefor airports,unLoCodefor harbors). - Otherwise, the location is geocoded based on the available address components,
and if the
typeis notPLACE, the closest transport facility of the indicated type is selected.
Geocoding priority
When multiple data sources are provided, they are evaluated in the following order of preference:
- Geographic coordinates (latitude and longitude)
- IATA code (for non-airport locations)
- Structured address components
- UN/LOCODE (for non-harbor locations)
- Unstructured address text
Geocoding accuracy depends on the quality and completeness of the input. Structured addresses almost always yield better results and are tolerant of minor data-entry errors, such as postcodes appearing in street fields. For both structured and unstructured inputs, the most probable match is selected based on lexicographical similarity to known locations.
Operational behavior
When a transport facility is specified directly, it will be used regardless of any transport vehicle specified. The system does not enforce suitability constraints. For example, a large aircraft such as a Boeing 747-8F may be routed to Gibraltar International (LXGB) despite its short runways. If the airport were not explicitly chosen, the system would instead select a nearby suitable airport such as Málaga-Costa del Sol (AGP).
Similarly, a container vessel may be routed to Plymouth (GBPLY) even though the port lacks container handling facilities. If the port were not specified explicitly, a capable alternative such as Southampton (GBSOU) would be selected automatically.
- Coordinates
- IATA code
- UN/LOCODE
- Unstructured address
- Structured address
- Street & city
- Street & postcode
- Postcode
- City
Show child attributes
Show child attributes
Locations resolve either to a transport facility (airport, harbor, or rail yard) or to a general geographic area such as a building, street, postcode, or city. For larger areas, centroids are used to represent the approximate position.
Identification and geocoding
- Airports and harbors can be identified directly by code (
iataCodefor airports,unLoCodefor harbors). - Otherwise, the location is geocoded based on the available address components,
and if the
typeis notPLACE, the closest transport facility of the indicated type is selected.
Geocoding priority
When multiple data sources are provided, they are evaluated in the following order of preference:
- Geographic coordinates (latitude and longitude)
- IATA code (for non-airport locations)
- Structured address components
- UN/LOCODE (for non-harbor locations)
- Unstructured address text
Geocoding accuracy depends on the quality and completeness of the input. Structured addresses almost always yield better results and are tolerant of minor data-entry errors, such as postcodes appearing in street fields. For both structured and unstructured inputs, the most probable match is selected based on lexicographical similarity to known locations.
Operational behavior
When a transport facility is specified directly, it will be used regardless of any transport vehicle specified. The system does not enforce suitability constraints. For example, a large aircraft such as a Boeing 747-8F may be routed to Gibraltar International (LXGB) despite its short runways. If the airport were not explicitly chosen, the system would instead select a nearby suitable airport such as Málaga-Costa del Sol (AGP).
Similarly, a container vessel may be routed to Plymouth (GBPLY) even though the port lacks container handling facilities. If the port were not specified explicitly, a capable alternative such as Southampton (GBSOU) would be selected automatically.
- Coordinates
- IATA code
- UN/LOCODE
- Unstructured address
- Structured address
- Street & city
- Street & postcode
- Postcode
- City
Show child attributes
Show child attributes
transportChain
(Unknown transport · object | Air transport · object | Rail transport · object | Road transport · object | Water transport · object | Hub · object)[]
Represents the sequence of transport and hub operations that define a complete multimodal logistics chain.
Structure
The transportChain is an ordered array of elements describing how cargo moves between points.
- Each transport element represents a specific operation and has a
typevalue ofAIR,RAIL,ROAD,WATER, orUNKNOWN. - Each hub element has a
typeofHUBand represents the connecting location between consecutive transport segments.
Behavior
- If this array is not provided or is empty, fallback transport modes are attempted instead. The system will cycle through the fallback modes in order, applying default parameters for each until one succeeds or all fail.
- Hubs must appear between each pair of transport operations to define the connecting locations between them.
- Hubs may also appear as the first and/or last elements in the array, acting as the origin or destination
in place of the top-level
originanddestinationproperties. - The road operations connecting the start and end locations to the selected airports, harbors, and rail yards are added automatically.
WEIGHTED_MODEStransport operations are not supported.
- Unknown transport
- Air transport
- Rail transport
- Road transport
- Water transport
- Hub
Show child attributes
Show child attributes
Any information you want returned in the response. It is returned unchanged.
Response
Routes successfully calculated
Show child attributes
Show child attributes
Show child attributes
Show child attributes
The total distance of the transport chain in kilometers. Distances are the routed distances; no distance adjustment factors are applied.
The legs of the transport chain, in order.
Show child attributes
Show child attributes
The number of credits charged for the request. Credits are charged in the same way as for an emissions calculation.
The id provided in the request.
The context provided in the request.