🚀 Searoutes Cycle 21 updates – Q4 2024
In this cycle, we’ve focused on delivering significant updates:
- launching the multimodal Shipment API v2.1, aligned with ISO 14083 compliance;
- enhancing the flight route feature and increasing our modeled emissions for airfreight;
- introducing the fuel API;
- revamping our developer’s page to make it easier to explore, adopt, and integrate our APIs.
Let's jump right in!
🚀 New multimodal Shipment API v2.1 - ISO 14083 Compliant
We’re introducing the new Shipment API v2.1, designed to align with ISO 14083 compliance standards. At Searoutes, we aim to help businesses meet sustainability goals by delivering trusted and standardized emissions reporting.
What’s new?
1. New contract design for transparency
The updated API structure introduces dynamic handling of legs and hubs to better reflect real-world operations. By breaking the "one leg in, one leg out" rule, it enables smarter emissions reporting and fills gaps in logistics data with inferred legs and automatic hub generation.
Key improvements include:
- Smart route rebuilding – provides transparency when reconstructing routes, particularly for flight legs (see "Flight Routes" below).
- Clear distinction between inferred and user-passed legs – enhances visibility into emissions breakdowns, especially for hubs (see "3. Hubs – automatically generated for multimodal emissions" in this feature section).
This flexible structure allows the API to deliver detailed emissions breakdowns across each segment of the journey, improving accuracy and transparency.
2. Intensity calculation
The calculation method has been reviewed and updated to comply with ISO 14083 standards. It now uses the Shortest Feasible Distance (SFD) for intensity calculations. This consistency offers the opportunity to easily compare modes efficiency.
However, the computation of carbon emissions continues to leverage the most accurate available distance, best case scenario being the historical distance.
Changes by mode:
- Road, rail, and inland-water: no changes, already based on SFD.
- Air: removed 95 km adjustment factor; intensity now strictly uses SFD.
- Sea: when historical (passing a
departuredate) or scheduled (passing ascac) routes had longer distances, intensity figures may increase due to the shift to SFD. - Manual inputs: SFD may result in shorter distances, affecting intensity calculations.
Example:
In this example, you can see how the historical distance used (source: ais) in the emissions calculation differs from the SFD (sfd) used in the intensity calculation.
"properties": {
"dataType": "modeled",
"distance": {
"sfd": {
"total": 16308330
},
"used": {
"total": 27357712,
"source": "ais"
}
},
"model": {
"name": "actual-portcalls-ais"
},
3. Hubs – automatically generated for multimodal emissions
The multimodal Shipment API now identifies and generates hubs when a modal split or a maritime transshipment occurs. These hubs are automatically calculated and included in the transport chain, along with their associated emissions data.
Key features:
- Auto-generated hubs are flagged with
source: auto_generated. - Manual hubs remain supported, flagged as
source: user_input.
Examples:
Example - Autogenerated hub output
{
"properties": {
"dataType": "default",
"source": "auto_generated",
"hubType": "maritime_container_terminal"
}
}
Example - Manual hub output
{
"properties": {
"dataType": "default",
"source": "user_input",
"hubType": "warehouse"
}
}
Example - Request & Response
{
"orders": [
{
"type": "parcel",
"weight": 300
}
],
"transportChainElements": [
{
"type": "hub",
"hubType": "warehouse"
},
{
"type": "leg",
"from": "FREBU",
"to": "FRLIO",
"mode": "road"
},
{
"type": "leg",
"from": "FRLIO",
"to": "FRFOS",
"mode": "rail"
},
{
"type": "leg",
"from": "FRFOS",
"to": "CNSHA",
"mode": "sea"
}
]
}
{
"parameters": {
"orders": [
{
"weight": 300.0,
"type": "parcel"
}
]
},
"co2e": {
"total": 63126,
"wtt": 11820,
"ttw": 51306,
"intensity": 0.0126
},
"transportChainElements": [
{
"type": "hub",
"location": {
"locode": "FREBU",
"coordinates": [
4.4,
45.43333333333333
],
"city": "Saint-Étienne",
"country": "France",
"region": "Mediterranean/Black Sea"
},
"parameters": {
"hubType": "warehouse"
},
"properties": {
"dataType": "default",
"source": "user_input",
"hubType": "warehouse",
"orders": [
{
"weight": 300.0,
"type": "parcel",
"co2e": {
"total": 13650,
"wtt": 2730,
"ttw": 10920
}
}
]
},
"co2e": {
"total": 13650,
"wtt": 2730,
"ttw": 10920
}
},
{
"type": "leg",
"from": {
"locode": "FREBU",
"coordinates": [
4.4,
45.43333333333333
],
"city": "Saint-Étienne",
"country": "France",
"region": "Mediterranean/Black Sea"
},
"to": {
"locode": "FRLIO",
"coordinates": [
4.834366996675094,
45.71740311038615
],
"city": "Lyon",
"country": "France",
"region": "Mediterranean/Black Sea"
},
"tradeLane": "Intra Mediterranean",
"mode": "road",
"parameters": {},
"properties": {
"dataType": "default",
"distance": {
"sfd": {
"total": 58819
},
"used": {
"total": 58819,
"source": "daf"
}
},
"model": {
"name": "sfd-direct-emissionfactors"
},
"region": "Europe",
"truck": {
"minSize": 0.0,
"maxSize": 3.5,
"loadFactor": null,
"emptyRunning": null,
"fuelType": "petrol",
"combinedEmptyRunningLoadFactor": 0.24
},
"orders": [
{
"weight": 300.0,
"type": "parcel",
"co2e": {
"total": 17116,
"wtt": 4147,
"ttw": 12970,
"intensity": 0.97
}
}
],
"carrier": null
},
"co2e": {
"total": 17116,
"wtt": 4147,
"ttw": 12970,
"intensity": 0.97
}
},
{
"type": "hub",
"location": {
"locode": "FRLIO",
"coordinates": [
4.834366996675094,
45.71740311038615
],
"city": "Lyon",
"country": "France",
"region": "Mediterranean/Black Sea"
},
"parameters": {},
"properties": {
"dataType": "default",
"source": "auto_generated",
"hubType": "transhipment_site",
"orders": [
{
"weight": 300.0,
"type": "parcel",
"co2e": {
"total": 390,
"wtt": 78,
"ttw": 312
}
}
]
},
"co2e": {
"total": 390,
"wtt": 78,
"ttw": 312
}
},
{
"type": "leg",
"from": {
"locode": "FRLIO",
"coordinates": [
5.081111,
45.725556
],
"city": "Lyon Saint-Exupéry Airport",
"country": "France",
"region": "Mediterranean/Black Sea"
},
"to": {
"locode": "FRFOS",
"coordinates": [
4.848286968176052,
43.407186268695995
],
"city": "Fos-sur-Mer",
"country": "France",
"region": "Mediterranean/Black Sea"
},
"tradeLane": "Intra Mediterranean",
"mode": "rail",
"parameters": {},
"properties": {
"dataType": "default",
"distance": {
"sfd": {
"total": 329107
},
"used": {
"total": 329107,
"source": "daf"
}
},
"model": {
"name": "sfd-direct-emissionfactors"
},
"orders": [
{
"weight": 300.0,
"type": "parcel",
"co2e": {
"total": 1560,
"wtt": 691,
"ttw": 869,
"intensity": 0.0158
}
}
]
},
"co2e": {
"total": 1560,
"wtt": 691,
"ttw": 869,
"intensity": 0.0158
}
},
{
"type": "hub",
"location": {
"locode": "FRFOS",
"coordinates": [
4.848286968176052,
43.407186268695995
],
"city": "Fos-sur-Mer",
"country": "France",
"region": "Mediterranean/Black Sea"
},
"parameters": {},
"properties": {
"dataType": "default",
"source": "auto_generated",
"hubType": "maritime_container_terminal",
"orders": [
{
"weight": 300.0,
"type": "parcel",
"co2e": {
"total": 321,
"wtt": 64,
"ttw": 257
}
}
]
},
"co2e": {
"total": 321,
"wtt": 64,
"ttw": 257
}
},
{
"type": "leg",
"from": {
"locode": "FRFOS",
"coordinates": [
4.848286968176052,
43.407186268695995
],
"city": "Fos-sur-Mer",
"country": "France",
"region": "Mediterranean/Black Sea"
},
"to": {
"locode": "CNSHA",
"coordinates": [
122.06550521343334,
30.61798396262171
],
"city": "Shanghai",
"country": "China",
"region": "North East Asia"
},
"tradeLane": "Asia to-from Mediterranean",
"mode": "sea",
"parameters": {},
"properties": {
"dataType": "default",
"distance": {
"sfd": {
"total": 16308330
},
"used": {
"total": 18754580,
"source": "daf",
"seca": 0
}
},
"model": {
"name": "sfd-direct-emissionfactors"
},
"vessel": {
"imo": null,
"name": "Asia to-from Mediterranean GLEC Representative Vessel",
"minTeu": null,
"maxTeu": null,
"fuelType": null
},
"tradeLane": "Asia to-from Mediterranean",
"orders": [
{
"weight": 300.0,
"type": "parcel",
"co2e": {
"total": 30089,
"wtt": 4110,
"ttw": 25979,
"intensity": 0.00615
}
}
]
},
"co2e": {
"total": 30089,
"wtt": 4110,
"ttw": 25979,
"intensity": 0.00615
}
}
]
}
Want to know more about hubs? Visit our Hubs Guide.
Supporting your Migration 🚀
To make the transition smooth:
- Follow the Migration Guide for step-by-step instructions.
- Use the Support Endpoints and Resources section in our API documentation for implementation tips and best practices.
This release marks an important step toward improving compliance and transparency, providing a clearer breakdown of routes, distances, and emissions modeling. Ready to dive in? Explore the multimodal Shipment API v2.1 now!
✈️ Flight Route Feature
During 2024, we increased our capacity to report accurately on airfreight thanks to the addition of the flight number as a parameter in the air legs. Nonetheless, we were lacking enough data to model each flight consistently with the aircraft actually used. With a new provider offering a comprehensive dataset, along with smart fallback rules, we now ensure the most accurate data possible, improving reliability and trust for our users.
What's new?
- Great modeled coverage.
- You can not only search by flight number but also by carrier.
- The system adapts to your data with permissive input handling (
flightNumberaccepts either the full combination of the carrier IATA code and flight number or just the flight number alone). - Fallback logic: we ensure modeled emissions by using the carrier's most representative aircraft as a fallback when the flight number is not passed or unknown.
- Contract transparency: you can see what was taken into account in the calculation: flight, aircraft, and carrier data, along with the rebuilt route details in the output contract of the Shipment API v2.1.
Example
Example 1 - Flight number found and route rebuilt
This example is a request for emissions calculation from Amsterdam (Schiphol Airport) to Shanghai (Pudong International Airport), using the flight number 7L206. The system detects that this flight covers only the Amsterdam to Baku (Heydar Aliyev) segment and rebuilds the route, modeling emissions based on the aircraft used for this portion, and adding a direct leg with default data for the rest of the route.
{
"orders": [
{
"type": "PARCEL",
"nContainers": 2,
"weight": 300
}
],
"transportChainElements": [
{
"type": "leg",
"from": "AMS",
"to": "PVG",
"mode": "air",
"details": {
"flight": {
"number": "7L206"
}
}
}
]
}
{
"parameters": {
"orders": [
{
"weight": 300.0,
"type": "PARCEL",
"nContainers": 2.0
}
]
},
"co2e": {
"total": 2243693,
"wtt": 469382,
"ttw": 1774312,
"intensity": 0.74689
},
"transportChainElements": [
{
"type": "leg",
"from": {
"locode": "NLAMS",
"coordinates": [
4.76389,
52.308601
],
"city": "Amsterdam Airport Schiphol",
"country": "Netherlands",
"region": "North Europe"
},
"to": {
"locode": "AZGYD",
"coordinates": [
50.04669952392578,
40.467498779296875
],
"city": "Heydar Aliyev International Airport",
"country": "Azerbaijan",
"region": "Mediterranean/Black Sea"
},
"tradeLane": "North Europe to-from Mediterranean",
"mode": "air",
"parameters": {
"details": {
"flight": {
"number": "7L206"
}
}
},
"properties": {
"dataType": "modeled",
"distance": {
"sfd": {
"total": 3641047
},
"used": {
"total": 3736047,
"source": "daf"
}
},
"model": {
"name": "gcd-direct-icao"
},
"flight": {
"number": 206,
"iataNumber": "7L206"
},
"carrier": {
"iata": "7L"
},
"aircraft": {
"iata": "74Y",
"icao": "B744",
"manufacturer": "BOEING",
"model": "Boeing 747-400 Freighter",
"type": "cargo"
},
"orders": [
{
"weight": 300.0,
"type": "parcel",
"co2e": {
"total": 658529,
"wtt": 137603,
"ttw": 520926,
"intensity": 0.60288
},
"nContainers": 2.0
}
]
},
"co2e": {
"total": 658529,
"wtt": 137603,
"ttw": 520926,
"intensity": 0.60288
}
},
{
"type": "leg",
"from": {
"locode": "AZGYD",
"coordinates": [
50.04669952392578,
40.467498779296875
],
"city": "Heydar Aliyev International Airport",
"country": "Azerbaijan",
"region": "Mediterranean/Black Sea"
},
"to": {
"locode": "CNPVG",
"coordinates": [
121.80500030517578,
31.143400192260742
],
"city": "Shanghai Pudong International Airport",
"country": "China",
"region": "North East Asia"
},
"tradeLane": "Asia to-from Mediterranean",
"mode": "air",
"parameters": {
"details": {
"flight": {
"number": "7L206"
}
}
},
"properties": {
"dataType": "default",
"distance": {
"sfd": {
"total": 6372419
},
"used": {
"total": 6467419,
"source": "daf"
}
},
"model": {
"name": "gcd-direct-emissionfactors"
},
"flight": null,
"carrier": null,
"aircraft": {
"iata": null,
"icao": null,
"manufacturer": null,
"model": "GLEC long haul unknown flight representative aircraft.",
"type": "unknown"
},
"orders": [
{
"weight": 300.0,
"type": "parcel",
"co2e": {
"total": 1585164,
"wtt": 331779,
"ttw": 1253386,
"intensity": 0.82918
},
"nContainers": 2.0
}
]
},
"co2e": {
"total": 1585164,
"wtt": 331779,
"ttw": 1253386,
"intensity": 0.82918
}
}
]
}
Example 2 - Carrier fallback
This example shows how providing only a carrier code (iata), without a flight number, returns the most representative aircraft flown by the carrier on this particular route. The same logic applies when a flight number is passed but not found. In such cases, if the carrier code is valid, we use it to model emissions.
{
"orders": [
{
"type": "parcel",
"weight": 1000
}
],
"transportChainElements": [
{
"type": "leg",
"from": "LHR",
"to": "CVG",
"mode": "air",
"details": {
"carrier": {
"iata": "BA"
}
}
}
]
}
{
"parameters": {
"orders": [
{
"weight": 1000.0,
"type": "parcel"
}
]
},
"co2e": {
"total": 2444611,
"wtt": 510814,
"ttw": 1933796,
"intensity": 0.38462
},
"transportChainElements": [
{
"type": "leg",
"from": {
"locode": "GBLHR",
"coordinates": [
-0.461941,
51.4706
],
"city": "London Heathrow Airport",
"country": "United Kingdom",
"region": "North Europe"
},
"to": {
"locode": "USCVG",
"coordinates": [
-84.667801,
39.048801
],
"city": "Cincinnati Northern Kentucky International Airport",
"country": "United States",
"region": "North America - East Coast"
},
"tradeLane": "North Europe to-from North America EC",
"mode": "air",
"parameters": {
"details": {
"carrier": {
"iata": "BA"
}
}
},
"properties": {
"dataType": "modeled",
"distance": {
"sfd": {
"total": 6355876
},
"used": {
"total": 6450876,
"source": "daf"
}
},
"model": {
"name": "gcd-direct-icao"
},
"flight": null,
"carrier": {
"iata": "BA"
},
"aircraft": {
"iata": "788",
"icao": "B788",
"manufacturer": "BOEING",
"model": "Boeing 787-8 pax",
"type": "passenger"
},
"orders": [
{
"weight": 1000.0,
"type": "parcel",
"co2e": {
"total": 2444611,
"wtt": 510814,
"ttw": 1933796,
"intensity": 0.38462
}
}
]
},
"co2e": {
"total": 2444611,
"wtt": 510814,
"ttw": 1933796,
"intensity": 0.38462
}
}
]
}
Coverage
To evaluate the performance of our modeled emissions coverage, we analyzed a sample dataset containing 60,000+ flight numbers from client inputs. The results highlight how well we provide modeled emissions based on actual data:
| Case | Parameter | Route type | Data Type | Coverage % |
|---|---|---|---|---|
| 1 | Flight Number | direct | Modeled | 39% |
| 2 | Flight Number | with connection | Modeled | 44% |
| 3 | Carrier Iata | direct | Modeled | 4% |
Key insights:
- A total of 87% of the dataset provided modeled emissions.
- The remaining 13% without modeled data were primarily due to inputs using the full from-to route instead of specific flight legs, complicating matches. In such cases, the carrier fallback couldn’t locate routes that covered the full input path.
Demo video
Check out our short video demo to explore how the feature works and delivers accurate emissions reporting.
What we left out
- Handling of hubs between inferred air legs.
- Stopover flights (same flight number, multiple stops) are not handled on the full route yet.
Need guidance on the airfreight parameters?
Visit our dedicated guide and learn how to get the utmost emissions data accuracy !
⛽ Introducing the Fuel API - Beta release!
We’re thrilled to announce the beta release of the Fuel API as part of our v3 endpoints. This feature addresses a common challenge: retrieving fuel consumption statistics for a given port pair. It’s designed to support users aiming to enhance their sustainability strategies with precise fuel usage data for sea itineraries.
What’s new?
- Fuel statistics: a dedicated
/routes/fuelStatisticsendpoint calculates average fuel consumption for a shipment on multiple routes, providing insights into total and per-leg fuel usage. - Enhanced route search: the
/routesendpoint has been redesigned to return detailed objects rather than hashes, simplifying route selection for further operations. - Flexible data access: dual endpoints (
/routes/{id}/fueland/fuel?routeId=xyz) allow users to retrieve fuel data for specific routes efficiently.
Example
Fuel statistics
{
"from": "CNSHA",
"to": "NLRTM",
"mode": "sea",
"carrier": {
"scac": "CMDU"
},
"departureDate": "2024-07-01",
"shipment":{
"nContainers": 2,
"containerSizeTypeCode": "40HC"
}
}
{
"object": "fuelStatistics",
"statistics": {
"average": [
{
"fuelConsumption": {
"grade": "VLSFO",
"unit": "gram",
"value": 468594,
"mode": "sea"
},
"type": "fuelConsumption"
}
],
"sampleSize": 6,
"routes": [
"JWqT826omFl",
"K3rYGqpIXSD",
"I28GBRibUFd"
]
}
}
Beta access
The Fuel API is currently in beta. If you’re interested in testing it and sharing your feedback, please contact our sales team.
Developer's page improvements
Developer's page improvements
We want to make working with our APIs as smooth as possible! We’ve made significant improvements to our developer’s page to make it easier for you to explore our solutions, understand their value, and get the most out of our APIs. These updates aim to:
- Simplify navigation: find what you need faster with grouped sections based on API ressources.
- Boost clarity: get more visibility into our solution catalog, our methodology, and available resources.
- Maximize emissions calculations: access resources to maximize accuracy and efficiency in your calculations.
- Easily access the latest Shipment API version: our new organization highlights our most up-to-date version (v2.1), making it easier for you to find and adopt the latest features without confusion.
What’s new?
We’ve restructured and enriched it to make it more user-friendly and resourceful. Here’s what’s changed:
1. 💻 API Reference:
- Reorganizing API sections by grouping them to align with our key product categories: Carbon Emissions, Ocean tracking, Vessel, Geocoding, Search, Weather, Old (includes CO2 Direct endpoints + v2.0 of our Shipment API).
- Centralizing shared resources: moving shared resources (e.g., container size type codes, fuel types for road) into a dedicated section, to reduce reduces repetitive content in individual endpoint documentation.
- Making authentication page more explicit: with instructions on how to get and start using API keys.
2. 📚 Guides:
- Enriching content and giving it a new structure: How-to guides (at the moment only for Carbon Emissions), Migration guides, GHG Methodology + carbon emissions data models.
- Support section with useful links: API status page, support team and contact form.
3. 🏡 Home:
- Content enriching and new structure: layout changes, API catalog.
What we left out
- Additional guides.
- Home section improvements (content and layout).
- Additional resources - will be added shortly: Units, Truck sizes, Fuel options for Ocean mode.
Take a closer look 👀!
Watch our short video demo to explore the updates in detail.
You just read our Product Update 👏
We'd love to hear what you think about these updates. Send us your feedback at [email protected]!