# Searoutes Docs Documentation > Documentation for Searoutes Docs Append .md to any documentation page URL to get its markdown version. ## Guides - [Introduction](https://developer.searoutes.com/docs/guides-overview.md) - [Key glossary](https://developer.searoutes.com/docs/glossary.md) - [📖 Our methodology](https://developer.searoutes.com/docs/our-methodology.md) - [🛳 Sea transport](https://developer.searoutes.com/docs/co2-emissions-methodology.md) - [✈️ Air transport](https://developer.searoutes.com/docs/️-air-transport.md) - [🚚 Road transport](https://developer.searoutes.com/docs/road-transport.md) - [🚄 Rail transport](https://developer.searoutes.com/docs/rail-transport.md) - [🛥️ Inland waters](https://developer.searoutes.com/docs/inland-waters.md) - [📍Hubs](https://developer.searoutes.com/docs/hubs.md): This guide provides an explanation of how the Shipment API handles hubs, both autogenerated and manually defined, as well as their role in emissions calculations. - [Milk run emissions](https://developer.searoutes.com/docs/milk-run.md) - [Use case examples](https://developer.searoutes.com/docs/bulb-use-cases-examples.md) - [🔄 Modal switch](https://developer.searoutes.com/docs/modal-switch.md): Simulate the impact on CO₂e emissions when switching between different modes of transport for your shipments, and gain insights on lower-emitting modes. - [⛽ Fuel switch](https://developer.searoutes.com/docs/fuel-switch.md): Simulate the carbon impact of switching from one fuel type to another. - [Migration guides](https://developer.searoutes.com/docs/migration-guides.md) - [Migrate from v2.0 to v2.1](https://developer.searoutes.com/docs/migrate-from-v20-to-v21.md): A dedicated guide to migrate your Multimodal Shipment API - [General best practices](https://developer.searoutes.com/docs/how-to-guides.md) - [🛳️ Sea transport](https://developer.searoutes.com/docs/sea-transport.md) - [✈️ Air transport](https://developer.searoutes.com/docs/air-transport-1.md) - [🚚 Road transport](https://developer.searoutes.com/docs/road-transport-1.md) - [🚄 Rail transport](https://developer.searoutes.com/docs/rail-transport-1.md) - [🛥️ Inland waters](https://developer.searoutes.com/docs/inland-waters-1.md) - [𐄷 Weight and containers details](https://developer.searoutes.com/docs/weight-and-containers-size-and-type.md) - [⚙️ Data models](https://developer.searoutes.com/docs/our-data-models.md): Our Shipment API unlocks the potential of your data, delivering optimal results with the most fitting models. - [Position vs Timeseries vs Trace](https://developer.searoutes.com/docs/position-vs-timeseries-vs-trace.md): Understanding vessel endpoints - [Vessel trace reconstruction](https://developer.searoutes.com/docs/vessel-trace-reconstruction-and-cleaning.md) - [Understanding AIS data](https://developer.searoutes.com/docs/vessel-tracking-and-ais-data.md) - [IMO vs MMSI vs vessel name](https://developer.searoutes.com/docs/understanding-vessel-identifiers.md): Understanding vessel identifiers - [Understanding route types](https://developer.searoutes.com/docs/understanding-route-types.md): Historical vs shortest vs schedule vs proforma - [Technical support](https://developer.searoutes.com/docs/technical-support.md) ## API Reference - [Authentication](https://developer.searoutes.com/reference/intro-authentication.md): Set up the welcome page for your API to help users make their first call. - [Overview](https://developer.searoutes.com/reference/introduction.md): 👋 Welcome to Searoutes' API reference! - [Container size type codes](https://developer.searoutes.com/reference/container-size-type-codes.md) - [Fuel types](https://developer.searoutes.com/reference/fuel-types.md) - [Block Areas](https://developer.searoutes.com/reference/block-areas.md) - [Truck sizes](https://developer.searoutes.com/reference/truck-sizes.md) - [Get CO₂e for a given shipment](https://developer.searoutes.com/reference/getco2forshipment.md): > 📘 This API is fully ISO-14083 compliant > If your are looking to migrate from the previous version, check out the [Migration Guide](/docs/migrate-from-v20-to-v21). Need to access to the previous version? Check the [documentation](/reference/getco2forshipment-1). ## Table of Contents - :wrench: [Request Configuration](#request-configuration) - [Headers](#headers) - :outbox_tray: [Request Structure](#request-structure) - [Orders](#orders) - [Transport Chain Elements](#transport-chain-elements) - [Metadata](#metadata) - :inbox_tray: [Response Structure](#response-structure) - [Parameters](#parameters) - [CO₂e Emissions](#co2e-emissions) - [Transport Chain Elements](#transport-chain-elements-1) - [Metadata](#metadata-1) - [Support endpoints and resources](#support-endpoints-and-resources)
This endpoint calculates CO₂ equivalent (CO₂e) emissions for a shipment that includes multiple transport chain elements, such as legs and hubs. It supports a variety of shipment types, from containers to parcels. The response provides CO₂e emissions data at three levels: - **Total shipment emissions:** overall CO₂e emissions of the shipment. - **Per order:** breakdown of emissions for each individual order within the shipment. - **Per transport chain element:** CO₂e emissions data segmented by each leg or hub of the route. ## Request Configuration ### Headers - `x-api-key`: your unique API key, required for authentication - `Accept-Version`: specifies the contract version. - **Required for v2.1**: set to `"2.1"` to access the latest version, which is ISO-compliant. :warning: **If no Accept-Version header is provided, the API defaults to version 2.0, allowing existing integrations to work without modification.** ## Request Structure Every request is formatted as a nested JSON object containing both **required** and **optional** properties that define the shipment's details. Here’s a breakdown: ### Orders `orders`: defines each order within the shipment, with a maximum of 5 orders. - **Required field**: - `type`: specifies the order type. Accepted values: - `FCL` - `LCL` - `parcel` - `bulk` - `breakbulk` - `nContainers`: number of containers. Required only when the order type is `FCL`. - `weight`: total weight of the order (in kilograms). Required for all order types except `FCL`. - **Optional fields**: - `containerSizeTypeCode`: specifies the container size/type code (e.g., `20gp`). See the full list of accepted values [here](/reference/container-size-type-codes). ### Transport Chain Elements `transportChainElements`: defines the shipment’s transport chain, with each item in the array representing either a `leg` or a `hub`. - **Legs** - **Required fields**: - `type`: must be set to `"leg"`. - `from` and `to`: specifies the origin and destination of the leg (can be a location, `locode`, `iata`, or coordinates). - `mode`: specifies transport mode (`sea`, `road`, `rail`, `air`, `inland_water`). - **Optional fields**: - `distance`: useful if a custom distance is preferred to our calculated distance. - `details`: mode-specific details, such as `fuelType` for road mode, `vesselImo` for sea mode. - You can find all the possible fields in our [request builder](#form-body-getCO2ForShipment) below - **Hubs** - **Required fields**: - `type`: must be set to `"hub"`. - `hubType`: specifies the type of hub, such as `warehouse`. ### Metadata Can contain any information you want to add to your request, for example, to help you identify your shipment. You can pass any key-value pair and it will be echoed back in the response. When using `generateCertificate=true`, the following fields in `metadata` are used to populate the PDF certificate: | Field | Type | Description | Example | |-------|------|-------------|---------| | `id` | string | Shipment identifier | `"S00300133"` | | `referenceNumber` | string | Booking or reference number | `"26616605"` | | `status` | string | Shipment status | `"ARRIVED"` | | `carrier` | object | Carrier information (`scac`, `name`) | `{"scac": "HLCU", "name": "Hapag-Lloyd"}` | | `client` | object | Client information (`name`) | `{"name": "ACME Corp"}` | > ℹ️ Note: `metadata.carrier` is used **only for the PDF certificate display**. For the actual CO₂e calculation, carrier information should be provided in `transportChainElements[].details.carrier`. ## Response Structure The response includes **CO₂e emissions data** at various levels and details for each transport chain element. ### Parameters `parameters`: reflects the submitted `orders`. - **Fields**: - `orders`: array reflecting the structure of each submitted order, including `type`, `quantity`, `weight`, and `ContainerSizeTypeCode`. ### CO₂e Emissions `co2e`: provides total emissions values for the shipment. - **Fields**: - `total`: total CO₂e emissions (in grams). - `wtt` and `ttw`: emissions broken down by Well-to-Tank and Tank-to-Wheel (in grams). - `intensity`: CO₂e intensity (in kg CO₂e per ton-km). ### Transport Chain Elements `transportChainElements`: array of objects that lists each transport element (`leg` or `hub`) in the sequence, including associated emissions data and properties. - **Legs**: - **Fields**: - `type`: `leg`. - `from` and `to`: origin and destination, with fields like `locode`, `iata`, `coordinates`, `city`, `country`, and `region`. - `mode`: transport mode used (e.g., `sea`, `road`, `air` ...). - `co2e`: emissions object with fields like `total`, `wtt`, `ttw`, and `intensity`. - `properties`: additional details such as `distance`, `vessel`, `fuelType` and `model`. You can find out more about our models [here](/docs/our-data-models) - **Hubs**: - **Fields**: - `type`: `hub`. - `location`: object with location details, including fields like `locode`, `coordinates`, `city`, `country`, and `region`. - `properties.hubType`: specifies the hub type, such as `warehouse` or `maritime_container_terminal`. - `source`: indicates the origin of the hub (`"user_input"` or `"auto_generated"`). - `co2e`: emissions object with fields like `total`, `wtt`, and `ttw`. ### Metadata Contains everything you passed in the input field `metadata`. ### Certificate URL `certificateUrl`: returned when the query parameter `generateCertificate=true` is set. Contains a URL to download the shipment's PDF certificate. The certificate includes shipment details, emissions breakdown, and any structured metadata fields (`id`, `referenceNumber`, `status`, `carrier`, `client`) you provided. ## Support endpoints and resources - **Understand how `weight` and `containerSizeTypeCode` impact calculations** across all transport modes: visit our [Weight and Container Guide](/docs/weight-and-containers-size-and-type). - **Optimize calculation accuracy by transport mode**: explore our [Optimizing Calculations Guide](/docs/sea-transport). - **Retrieve maritime carriers**: use our [Carriers endpoint](/reference/getcarrierbynameorscac) to search for carrier information based on SCAC codes or names. - **Find locations**: access accurate data via our [Geocoding endpoint](/reference/getgeocodingall). - **Explore the list of [Supported fields and values](/reference/container-size-type-codes)**. - **Migration guide**: review the [Migration guide](/docs/migrate-from-v20-to-v21) to transition from v2.0 to v2.1 with ease. - **Learn about Data models**: visit the [Data models guide](/docs/our-data-models) in the methodology section. - [Get CO₂e for a complete run](https://developer.searoutes.com/reference/getco2forarun.md): ## Description This endpoint computes CO₂e emissions for a complete road collection and delivery operation, also known as a milk run. Total emissions are first calculated for the full vehicle run (considering weight, distance, and load factor), then allocated across shipments according to their transport activity, following ISO 14083 principles. ## Input overview The endpoint takes as input: - **locations**: the ordered sequence of stops in the run - **orders**: the shipments carried, each referencing stop indices - **details**: vehicle characteristics (fuel type, truck size) - **metadata**: any custom key-value pairs, returned as-is in the response ### Locations & terminal handling - A run is the full itinerary taken by the vehicle. - Locations can be expressed as UNLOCODE strings (e.g. `"FRMRS"`) or as `"longitude,latitude"` coordinates (e.g. `"8.833,53.884"`). - The order in the list determines each stop's index, starting at `0`. Three run shapes are supported: **Open loop**: the vehicle does not return to its starting point: ```json "locations": ["FRMRS", "FRVAF", "FRLIO"] ``` **Closed loop**: the vehicle returns to its starting point; repeat the first location at the end: ```json "locations": ["FRMRS", "FRVAF", "FRLIO", "FRMRS"] ``` **Unknown terminal**: the depot is unknown; use `""` as a placeholder for the first and last stops. The API infers a truck terminal to represent vehicle repositioning. Indices start at the first element, even when it is empty: ```json "locations": ["", "FRMRS", "FRVAF", "FRLIO", ""] ``` The inferred terminal behaves like a standard location: legs connected to it may be empty or loaded, and empty running only occurs when no shipment is assigned to them. ### Orders Each order represents a parcel transported from one stop to another. Orders must cover all goods moved during the run. The endpoint takes as input: - `fromIndex`: index of the pickup stop - `toIndex`: index of the delivery stop - `weight`: weight in kilograms - `id`: optional identifier, returned in the response - `type`: must be `"PARCEL"` Example: a 1,500 kg shipment picked up at index 1 (FRMRS) and delivered at index 4 (FRVAF): ```json { "fromIndex": 1, "toIndex": 4, "weight": 1500, "id": "ABC123", "type": "PARCEL" } ``` ## Methodology ### Full run emissions The Run API models emissions for the complete vehicle run, using: - road network distances between successive locations, - vehicle characteristics (fuel, size), - load evolution along the route, - empty and loaded movements. ### Shipment allocation (ISO 14083) Emissions are allocated based on transport activity (weight * pickup-to-delivery distance). Allocation depends on each shipment's pickup and delivery locations. Great circle distances are used for computing transport activities. ## Response The response contains: - **`co2e`**: total emissions in grams for the entire run, split into WTT and TTW. - **`orders`**: CO2e allocation per order, including intensity, allocation percentage, distance. - **`parameters`**: the resolved run definition (locations with indices, vehicle details). - **`properties`**: computation details: allocation method, data type, total distance, empty running ratio, and per-leg properties (distance, region, load factor). ## Notes & considerations - **Details (vehicle)**: vehicle characteristics can be optionally passed. If omitted, the API defaults to `DIESEL` fuel and selects the smallest truck size that can carry the orders (4t to 60t GVW). - **Metadata**: any value added to the `metadata` object is returned unchanged in the response. It has no effect on the CO2e calculation. - **Empty running**: occurs whenever the vehicle travels without any assigned shipment (not configured manually). Empty legs are included in total vehicle emissions, and `loadFactor = 0` identifies empty running segments in the response. Note that terminal legs are not automatically empty, it depends on the orders passed. - **ISO 14083 alignment**: the allocation method and emission calculations follow the ISO 14083 standard. ## Support endpoints and resources For a detailed information about the **Milk Run methodology**, refer to our [Guides](https://developer.searoutes.com/docs/milk-run) section. - [Get CO₂e statistics for a given carrier on a given port pair.](https://developer.searoutes.com/reference/getco2plan-1.md): This endpoint returns CO₂ equivalent (CO₂e) emissions statistics of a given carrier and port pair. We calculate the itineraries operated by the carrier based on their services (and their alliance's) and for each itinerary, we calculate the CO₂e emissions of each vessel operating the service and return statistics. The response provides CO₂e emissions data at two levels: - at the carrier level, - at each itinerary level. ## Response ### CO₂ emissions overview The CO₂e emissions are returned in grams. | Field | Given at carrier level | Given at itinerary level | |---------------------------|----------------|-------------| | `co2e.min` | Greenest itinerary average emissions | Greenest vessel emissions of a specific itinerary | | `co2e.max` | Most emitting itinerary emissions | Most emitting vessel emissions of a specific itinerary | | `co2e.average` | Average CO₂e emissions for all itineraries | Average CO₂e emissions of all vessels of a specific itinerary | | `co2e.standardDeviation` | Standard deviation of CO₂e emissions across itineraries | Standard deviation of CO₂e emissions across vessels operating a specific itinerary | ### Other fields - **CO₂ breakdown** *(WTT, TTW, and intensity)* is provided for each CO₂e emissions value in the response. - **Distance** is only given at the itinerary level. The distance takes into account the ports of call based on the services proformas. - **A hash (`itineraries.hash`)** is assigned to each itinerary, acting as a unique identifier for that specific route and shipment characteristics. - The corresponding itinerary can be retrieved via the `GET /itinerary/v2/proformas/{hash}` endpoint. - This endpoint provides **additional itinerary details**, including ports of call and route geometry. ### Notes & considerations - For the calculation of the emissions: - if no container info is provided but the weight is, we assume the container number based on the weight. - if none of the above is provided, we assume 1 TEU. - For the calculation of the intensity: - if no weight is provided but the container info is, we assume the weight based on the container info. - if none of the above is provided, we assume 10000 kg. - CO₂ calculations are based on itineraries built from carrier services and their planned route. - The `services` parameter forces the routing engine to build itineraries that include the specified services. You can provide up to three service IDs. This is an "AND" condition, meaning the returned itinerary will include all specified services, even if the result is not the most optimal. If no feasible itinerary can be built using all the provided services, no results will be returned. - The `services` sequence matters: the order in which services are provided must match their natural sequence in the itinerary. If services are listed in an order that does not align with a possible route, the request may return no results. However, intermediate services not explicitly listed may still appear between the specified services when necessary to complete the itinerary. - In case of an itinerary with transhipments, the minimum CO₂ emissions value is the sum of the minimum values of each leg of the itinerary. - Hashes are not intended to be persisted or used as permanent references. ## Support endpoints and resources - **Understand how `weight` and `containerSizeTypeCode` impact calculations** across all transport modes: visit our [Weight and Container Guide](/docs/weight-and-containers-size-and-type). - **Retrieve maritime carriers**: use our [Carriers endpoint](/reference/getcarrierbynameorscac) to search for carrier information based on SCAC codes or names. - **Retrieve service IDs**: use our [Search service by name endpoint](/reference/getservicebyname). - **Find locations**: access accurate data via our [Geocoding endpoint](/reference/getgeocodingall). - **Check the [Supported Container size type codes](/reference/container-size-type-codes)** for a complete list of accepted inputs. - **Learn about our methodology**: visit the [Methodology for sea emissions calculation](/docs/co2-emissions-methodology) page. - [Get CO₂ details for an itinerary from proformas by hash](https://developer.searoutes.com/reference/getco2detailsbyhash.md): This endpoint retrieves CO₂ emissions details for a specific itinerary, identified by a hash. Itinerary hashes are generated and returned in the `/itinerary/v2/proformas` response. ## Response The CO₂e emissions are returned in grams. | Field | Description | Type | |------------------|-------------------------------------------------------|-------------------------------| | `co2e` | Estimated CO₂ emissions data. | Statistics (`min`, `max`, `average`, `standardDeviation`) | | `co2e.wtt` | Well-to-Tank (`WTT`) emissions data. | Statistics (`min`, `max`, `average`, `standardDeviation`) | | `co2e.ttw` | Tank-to-Wheels (`TTW`) emissions data. | Statistics (`min`, `max`, `average`, `standardDeviation`) | | `co2e.intensity`| CO₂ intensity values (emissions per unit of cargo). | Statistics (`min`, `max`, `average`, `standardDeviation`) | | `distance` | Total itinerary distance. | Numeric (meters) | ### Notes & considerations - **Hashes** are not intended to be persisted or used as permanent references. ## Support endpoints and resources - **Retrieve itinerary solutions**: use our [`/itinerary/v2/proformas`](/reference/getItinerariesFromProformas) endpoint to retrieve itinerary hashes for a given carrier, port pair and shipment details. - **Learn about our methodology**: visit the [Methodology for sea emissions calculation](/docs/co2-emissions-methodology) page. - [Get CO₂e details of an itinerary by hash.](https://developer.searoutes.com/reference/getitineraryco2detailsbyhash.md): This endpoint returns the CO₂e details of an itinerary by hash (the unique fingerprint used to identify an itinerary). Those hashes are returned in [/itinerary/v2/execution](/reference/getitineraryperdeparture). The response gives the CO₂e breakdown at the itinerary level (total, wtt, ttw, intensity), as well as at the leg level. The distances are given in meters and the CO₂e emissions in grams. - [Authentication](https://developer.searoutes.com/reference/getgeocodingall.md): Set up the welcome page for your API to help users make their first call. - [Find closest sea point at location](https://developer.searoutes.com/reference/getgeocodingplace.md): Given a point as a coordinates pair, this endpoint checks if it is on sea or not. If on sea, it returns the coordinate pair `{longitude},{latitude}` as GeoJSON. If on land, it returns the closest coordinate pair on sea. The field 'valid' tells whether the given point is on sea or not. The response also contains information about the point : `isSeca` if the point is in an ECA zone and `isCoastal` if the point is close to the coast. - [Find the closest locations](https://developer.searoutes.com/reference/getgeocodingclosest.md): This endpoint can be used to retrieve the closest locations from a point ordered by distance or the locations around a point (inside a geographical circle with a given radius (in meters)). You can also choose the number of results. By default, the endpoint only returns the closest location. The `coordinates` of the point (or center of the circle) must be passed as path parameter as coordinates pair `longitude,latitude`. The query parameter `locationTypes` allows to filter the types returned. A list of values can be passed among `port,airport,zipcode,railTerminal, roadTerminal`. If this parameter is not passed in the query, all the types will be searched. The query parameter `sizes` allows to filter the sizes of the locations returned for ports and airports. For each location found, geometry (coordinates) is returned as well as a `properties` field that contains different information according to the type of the location. For ports : `name`, `locode`, `country`, `countryName`, `size` and `distance` (in meters) from the point passed in the query. For airports : `name`, `locode`, `size`, `iataCode`, `countryName`, `countryCode` (as a two letters code), `subdivisionName`, `city`. For zipcodes : `name`, `countryCode`, `countryName`, `postalCode` and `distance` (in meters) from the point passed in the query. For rail terminals and road terminals : `name`, `locode`, `countryCode`, `countryName` and `distance` (in meters) from the point passed in the query. - [Find routing area by name](https://developer.searoutes.com/reference/getgeocodingarea.md): This endpoint does forward geocoding: given a partial string, for instance `panam`, it returns a given number of routing areas which name contains `panam`. It also returns the `id`, `name` and `geolocation`. - [Find airport by name, locode or IATA](https://developer.searoutes.com/reference/getgeocodingairport.md): This endpoint does forward geocoding: given a name, a locode or IATA code, it returns airports matching the request with their name, locode, IATA code, country, subdivision and coordinates. This endpoint can be used for exact matching using `locode` or `iataCode` parameter or for partial matching using `query` parameter. Only one of these fields must be used in a request. - [Find port by name or locode](https://developer.searoutes.com/reference/getgeocodingport.md): This endpoint does forward geocoding: given a name or a locode, it returns ports matching the request with their name, locode, country, size, coordinates and whether the port is in an eca zone or not. Use either `locode` or `query`, not both in the same query. - [Find the geocoordinates of a zipcode](https://developer.searoutes.com/reference/getgeocodingzip.md): This endpoint does forward geocoding: given a postal code and a list of countries, it returns both coordinates and information about that particular location. - [Get sea route between locations.](https://developer.searoutes.com/reference/getsearoute.md): This endpoints returns the route between a source location and a target location on sea, along with the route distance (in meters), duration (in milliseconds) and the crossed areas. We return the shortest route sailed considering traffic separation schemes and port entries. ### Locations: origin, destination and waypoints Locations can be specified as coordinate pairs or UN/LOCODEs. Coordinate pairs are formatted as `longitude,latitude`. Each position should be separated by semicolons `;`. You can add up to 20 positions, including waypoints on a route (up to 18), or request several legs of a trip in one go by listing more than two positions. For instance: `-1.26617431640625,50.79551936692376;8.8330078125,53.88491634606499;-3.2409667968749996,53.50111704294316`. ### Vessel specific routes You can get vessel specific routes by specifying the IMO number of a vessel. The returned route will be compatible with the vessel dimensions (width (in m), length (in m), maximum draft (in m)). If the IMO is not given, We choose a small vessel in order not to block any route. You can also specify the current draft (in m) of the vessel using the parameter `vesselDraft`, with or without giving an IMO. If both IMO and vessel draft are given, the given draft (in m) is used and the other dimensions (width, length) are retrieved from the IMO number. The response contains static information about the vessel used (width (in m), length (in m), maximum draft (in m)). ### Continuous coordinates Depending on the boolean parameter `continuousCoordinates`, the longitudes of the points of the route returned can be between -180° and 180° (`false`) or continuous (ie greater than 180° or lower than -180° after crossing the antimeridian). The default behavior is to return continuous coordinates (the parameter is set to `true` as default). However, we encourage the use of normalized longitudes between -180° and 180° setting the parameter to `true` when requesting a route. ### Routing parameters #### Departure time and vessel speed To compute an accurate ETA, you can specify: - Departure time using the `departure` parameter (Unix timestamp in milliseconds). - Vessel speed, either in km/h using `speed`, or in knots using `speedInKts`. If the route crosses restricted-speed zones (for example, canals), the system automatically applies area speed limits. Outside of those areas, the specified vessel speed is used. #### Inland waterways navigation Routing through inland waterways is supported, if the vessel draft allows it. #### Zone preferences **ECA / SECA zones** Use the parameter `avoidSeca=true` to minimize the route travelled within Emission Control Areas (ECAs or SECAs). **HRA (High Risk Areas)** Use `avoidHRA=true` to minimize the route travelled in high-risk regions. - If none of your requested points are inside the HRA, the zone will be fully avoided. - Otherwise, the system reduces the route within the HRA as much as possible. - The distance sailed in HRA is available in the `hraIntersection` field of the response. **Ice areas** - By default, some seas that are difficult to navigate due to ice (for example the Bering Sea, the Northern Sea Route) are avoided. - You can override this using `allowIceAreas=true`. **Blocked areas** - Use the `blockAreas` parameter to manually exclude specific regions (Panama Canal: `11112`, Suez Canal: `11117`). - If your locations list includes a blocked area, the API returns a `400` error, with the index of the problematic location and the ID of the blocked area. ### Support endpoints and resources - Browse the list of supported [Block Areas](/reference/block-areas) to look up area IDs by name. - You can also use our [Geocoding API](https://developer.searoutes.com/reference/getgeocodingarea) to retrieve an area id from its name. - [Get detailed sea route plan between locations.](https://developer.searoutes.com/reference/getplansearoute.md): This endpoints returns the route between a source location and a target location on sea, along with the route distance (in meters), duration (in milliseconds) and details about the zones it goes through. We return the shortest route sailed considering traffic separation schemes and port entries. ### Locations: origin, destination and waypoints Locations can be specified as coordinate pairs or UN/LOCODEs. Coordinate pairs are formatted as `longitude,latitude`. Each position should be separated by semicolons `;`. You can add up to 20 positions, including waypoints on a route (up to 18), or request several legs of a trip in one go by listing more than two positions. For instance: `-1.26617431640625,50.79551936692376;8.8330078125,53.88491634606499;-3.2409667968749996,53.50111704294316`. ### Vessel specific routes You can get vessel specific routes by specifying the IMO number of a vessel. The returned route will be compatible with the vessel dimensions (width (in m), length (in m), maximum draft (in m)). If the IMO is not given, We choose a small vessel in order not to block any route. You can also specify the current draft (in m) of the vessel using the parameter `vesselDraft`, with or without giving an IMO. If both IMO and vessel draft are given, the given draft (in m) is used and the other dimensions (width, length) are retrieved from the IMO number. The response contains static information about the vessel used (width (in m), length (in m), maximum draft (in m)). ### Continuous coordinates Depending on the boolean parameter `continuousCoordinates`, the longitudes of the points of the route returned can be between -180° and 180° (`false`) or continuous (ie greater than 180° or lower than -180° after crossing the antimeridian). The default behavior is to return continuous coordinates (the parameter is set to `true` as default). However, we encourage the use of normalized longitudes between -180° and 180° setting the parameter to `true` when requesting a route. ### Routing parameters #### Departure time and vessel speed To compute an accurate ETA, you can specify: - Departure time using the `departure` parameter (Unix timestamp in milliseconds). - Vessel speed, either in km/h using `speed`, or in knots using `speedInKts`. If the route crosses restricted-speed zones (for example, canals), the system automatically applies area speed limits. Outside of those areas, the specified vessel speed is used. #### Inland waterways navigation Routing through inland waterways is supported, if the vessel draft allows it. #### Zone preferences **ECA / SECA zones** Use the parameter `avoidSeca=true` to minimize the route travelled within Emission Control Areas (ECAs or SECAs). **HRA (High Risk Areas)** Use `avoidHRA=true` to minimize the route travelled in high-risk regions. - If none of your requested points are inside the HRA, the zone will be fully avoided. - Otherwise, the system reduces the route within the HRA as much as possible. - The distance sailed in HRA is available in the `hraIntersection` field of the response. **Ice areas** - By default, some seas that are difficult to navigate due to ice (for example the Bering Sea, the Northern Sea Route) are avoided. - You can override this using `allowIceAreas=true`. **Blocked areas** - Use the `blockAreas` parameter to manually exclude specific regions (Panama Canal: `11112`, Suez Canal: `11117`). - If your locations list includes a blocked area, the API returns a `400` error, with the index of the problematic location and the ID of the blocked area. ### Waypoints returned This endpoint additionally returns a list of waypoints of interest in the `waypoints` fields of the `properties` of each leg. The waypoints can be of different types : - `VOYAGE` for voyage scale events such as departure and arrival with class either `ENTRY` or `EXIT`; - `ROUTING` for special zones with class either `ENTRY` or `EXIT`; - `SECA` for ECA zones with class either `ENTRY` or `EXIT`; - `SPEED` for points where speed must be adjusted with class `INCREASE`, `DECREASE` or `TARGET` (only used to know the speed at departure when it must be different than the given speed). ### Support endpoints and resources - Browse the list of supported [Block Areas](/reference/block-areas) to look up area IDs by name. - You can also use our [Geocoding API](https://developer.searoutes.com/reference/getgeocodingarea) to retrieve an area id from its name. - [Get proformas and their CO₂e emissions for a carrier on a port pair.](https://developer.searoutes.com/reference/getitinerariesfromproformas.md): This endpoint retrieves itineraries for a given carrier on a given port pair. It provides estimated transit times, distance and route details, along with CO₂e data. ## Response The response is a list of **FeatureCollection**, where: - Each **`featureCollection`** represents an itinerary. - **`Properties`** contain key details such as transit time, CO₂ emissions, and ports of call. - **`Geometry`** provides the route geometry as a `LineString` in GeoJSON format. | Field | Description | |-------------------|-------------| | `duration.days` | Estimated transit time in days, including transhipments and waiting time in ports. | | `duration.ms` | Estimated transit time in milliseconds. | | `departure.dayNumber` | Represents the starting reference day of the journey. | | `arrival.dayNumber` | Represents the arrival day relative to the departure day. | | `from.locode` | Departure port UN/LOCODE. | | `from.name` | Departure port name. | | `to.locode` | Arrival port UN/LOCODE. | | `to.name` | Arrival port name. | | `distance` | Total itinerary distance (in meters). | | `mode` | Transport mode (`"SEA"`). | | `serviceId` | Service ID associated with the leg. Retrievable with `/search/v2/service/{id}` | | `calls` | List of intermediate port calls. | | `co2e` | Estimated CO₂ emissions for the itinerary. | | `geometry` | GeoJSON `LineString` representing the leg’s route geometry. | ### Notes & considerations - GeoJSON compliance: by default, the response includes a properties field at the FeatureCollection level. If full GeoJSON compliance is required, you should omit `properties` field. - The `services` parameter forces the routing engine to build itineraries that include the specified services. You can provide up to three service IDs. This is an "AND" condition, meaning the returned itinerary will include all specified services, even if the result is not the most optimal. If no feasible itinerary can be built using all the provided services, no results will be returned. - The `services` sequence matters: the order in which services are provided must match their natural sequence in the itinerary. If services are listed in an order that does not align with a possible route, the request may return no results. However, intermediate services not explicitly listed may still appear between the specified services when necessary to complete the itinerary. - **Sorting behavior**: - `TRANSIT_TIME`: Returns fastest itineraries first. - `CO2`: Returns itineraries with the lowest estimated CO₂ emissions first. - Each itinerary has a **unique `hash`**, which can be used to retrieve additional CO₂ details from `/co2/v2/proformas/{hash}`. - **Proforma API itineraries vs. Execution API itineraries**: - `/itinerary/v2/proformas` provides planned itineraries for strategic procurement and short to long-term support to decision-making. - `/itinerary/v2/execution` data (from `/itinerary/v2/execution`) reflects upcoming departures, including sailing dates and assigned vessels, for optimizing immediate shipments' operations. - Hashes are not intended to be persisted or used as permanent references. ## Support endpoints and resources - ** Retrieve CO₂e details for an itinerary** using the [`/co2/v2/proformas/{hash}`](/reference/getco2) endpoint - **Learn about our methodology**: visit the [Methodology for sea emissions calculation](/docs/co2-emissions-methodology) page. - **Understand how `weight` and `containerSizeTypeCode` impact calculations** across all transport modes: visit our [Weight and Container Guide](/docs/weight-and-containers-size-and-type). - **Retrieve maritime carriers**: use our [Carriers endpoint](/reference/getcarrierbynameorscac) to search for carrier information based on SCAC codes or names. - **Find services ids by name**: using our [Search endpoint](/reference//getservicebyname). - **Find locations**: access accurate data via our [Geocoding endpoint](/reference/getgeocodingall). - **Explore the list of [Supported fields and values](/reference/container-size-type-codes)**. - [Get itinerary by hash.](https://developer.searoutes.com/reference/getitinerarybyhash.md): This endpoint retrieves detailed itinerary information for a specific route, identified by its unique hash. Itinerary hashes are generated and returned in the `/co2/v2/plan` response, allowing users to request detailed routing information for a given carrier and port pair. The response provides: - Itinerary-level details (duration, distance, CO₂e emissions). - Leg-specific details (departure and arrival days, port of calls, service ID). - Route geometry (LineString in GeoJSON format). ## Response The response is a GeoJSON FeatureCollection, where: - Each `Feature` represents a leg of the itinerary. - `Properties` contain key details such as transit time, CO₂ emissions, and ports of call. - `Geometry` provides the route geometry as a `LineString` in GeoJSON format. | Field | Description | |-------------------------|-------------| | `duration.days` | Estimated transit time in days, including transhipments and waiting time in ports. | | `duration.ms` | Estimated transit time in milliseconds. | | `departure.dayNumber` | Represents the starting reference day of the journey. | | `arrival.dayNumber` | Represents the arrival day relative to the departure day. | | `from.locode` | Departure port UN/LOCODE. | | `from.name` | Departure port name. | | `to.locode` | Arrival port UN/LOCODE. | | `to.name` | Arrival port name. | | `distance` | Total itinerary distance (in meters). | | `mode` | Mode of transport (`"SEA"`). | | `serviceId` | Service ID associated with the leg. Retrievable with `/search/v2/service/{id}`. | | `calls` | List of intermediate port calls. | | `co2e` | Estimated CO₂ emissions for the itinerary (in grams), corresponding to the load characteristics passed as input when searching for the itinerary | | `geometry` | GeoJSON `LineString` representing the leg’s route geometry. | ### Notes & considerations - GeoJSON compliance: by default, the response includes a properties field at the FeatureCollection level. If full GeoJSON compliance is required, you should omit `properties` field. - Antimeridian crossing: if a LineString crosses the antimeridian (longitude ±180°), the response may include longitude values greater than 180° or less than -180°. This behavior maintains continuity in a single LineString. - Hashes are not intended to be persisted or used as permanent references. ## Support endpoints and resources - **Get CO₂-based itineraries**: use our [`/co2/v2/plan`](/reference/getco2plan) endpoint to retrieve itinerary hashes and estimated emissions for a given carrier and port pair. - **Learn about our methodology**: visit the [Methodology for sea emissions calculation](/docs/co2-emissions-methodology) page. - **Retrieve maritime carriers**: use our [Carriers endpoint](/reference/getcarrierbynameorscac) to search for carrier information based on SCAC codes or names. - **Find locations**: access accurate data via our [Geocoding endpoint](/reference/getgeocodingall). - **Find services ids**: using our [Search endpoint](/reference/getservicebyid). - [Get ocean schedules and their CO₂e emissions for a port pair](https://developer.searoutes.com/reference/getitineraryperdeparture.md): Gain the ability to choose the greenest or fastest option among upcoming vessel departures, selecting from the best available itineraries per carrier. This endpoint returns the possible itinerary and their CO₂e emissions in the near future, for a given carrier and a given port pair. The CO₂e emissions are returned in grams. ### Input Location of origin (`fromLocode`) and destination (`toLocode`), and carrier information (`carrierScac` or `carrierId`) are mandatory fields. #### Dates This endpoint takes two dates as input: `fromDate` and `toDate`. It represents the departure date range within which the endpoint will search for itineraries. Passing the dates is optional. If no date is given, the endpoint will return itineraries sailing 7 days onwards after the current date. Both dates should be passed using the ISO 8601 format. #### Sorting To get the results in order of preference, use the parameter `sortBy`. You can input `CO2` or `TRANSIT_TIME`, depending on your main interest. ### Response The response is a list of `featureCollection`'s, where each feature collection is a possible itinerary. The feature collection is made of: - One or multiple features A direct itinerary results in a feature collection made of only one feature. An itinerary with transshipments results is a feature collection made of multiple features, each of it representing one leg. - One hash Each itinerary is associated to a unique fingerprint (called "hash") that you can use to retrieve the CO₂e breakdown and details of the itinerary via the /co2/v2/execution endpoint. It will return the CO₂e breakdown (total, TTW, WTT, intensity values). Each feature has its own properties, including details such as duration, departure and arrival dates, locations, distance, mode, service ID, asset (vessel) details, port of calls, total CO₂e emissions. Results are given in the order of sorting requested (`CO2` or `TRANSIT_TIME`). If no `sortBy` is input, the sorting will be done on the CO₂e basis. ### Notes & considerations - Hashes are not intended to be persisted or used as permanent references. ### Support endpoints and resources - **Get CO₂e emissions for a given ocean schedule itinerary (by hash)**: use our [`/co2/v2/execution/{hash}`](/reference/getitineraryco2detailsbyhash) endpoint. - **Learn about our methodology**: visit the [Methodology for sea emissions calculation](/docs/co2-emissions-methodology) page. - **Understand how `weight` and `containerSizeTypeCode` impact calculations** across all transport modes: visit our [Weight and Container Guide](/docs/weight-and-containers-size-and-type). - **Retrieve maritime carriers**: use our [Carriers endpoint](/reference/getcarrierbynameorscac) to search for carrier information based on SCAC codes or names. - **Find locations**: access accurate data via our [Geocoding endpoint](/reference/getgeocodingall). - **Explore the list of [Supported fields and values](/reference/container-size-type-codes)**. - [Find a carrier by id](https://developer.searoutes.com/reference/getcarrierbyid.md): This endpoint allows to get carrier information by id. - [Find a carrier by name or SCAC](https://developer.searoutes.com/reference/getcarrierbynameorscac.md): This endpoint allows to get carrier information by name or SCAC. The API returns a list of carriers matching the request. - [Find a service by id](https://developer.searoutes.com/reference/getservicebyid.md): This endpoint allows to get service information by id including the name, the ids of the carriers which operate the service, the designation of the service per carrier, the intermediate port calls and the IMOs of the vessels operating these services. Note that `carrierIds`, `portLocodes` and `vesselImos` in the response are deprecated. - [Find a service by name](https://developer.searoutes.com/reference/getservicebyname.md): This endpoint allows to search for services by name or partial name and retrieve the matching services and their information including the name, the ids of the carriers that operate the service, the designation of the service per carrier, the intermediate port calls and the IMOs of the vessels operating these services. You can also pass a carrier SCAC to filter on the services operated by this carrier. - [Get vessel ETA by IMO number](https://developer.searoutes.com/reference/getvesseleta.md): Retrieve information from AIS and return general information about the vessel, its current speed (in km/h), its current draft (in m), its last position, its destination and an ETA predicted by our algorithms (Unix timestamp in ms). - [Get vessel information, by name.](https://developer.searoutes.com/reference/getvesselsbyname.md): This endpoint returns vessel information by name. You can search for vessels using a name string. If several vessels match the query, up to 5 results may be returned. The response includes: - Identification fields: `imo`, `mmsi`, `name`, and `fka` (former known as). - Vessel dimensions (in meters): `length`, `width, and `maxDraft`. - Additional details: - `vesselType`: classification of the vessel (such as `bulk_carrier`, or `container_ship`). - `dwt`: deadweight tonnage (in tonnes) - the maximum weight a ship can safely carry, including cargo, fuel, crew, etc. - `gt`: gross tonnage - a unitless measure of the vessel’s total internal volume. - [Get vessel position](https://developer.searoutes.com/reference/getvesselpositionbyimo.md): Retrieve information from static and dynamic AIS messages for a vessel. Vessel are identified either by `imo` or `mmsi`. You can pass a `dateTime` or `timestamp` as parameter to get the closest position to a specific time. This endpoint returns the position as geoJSON, along with properties such as speed over ground (in km/h), course over ground, heading, current draft (in m), the navigational status reported over AIS (`navigationalStatus`, with the AIS status code and its label), the origin port call (`originPort`, the last port the vessel departed from, with arrival/departure times and duration of the call in hours), the raw AIS destination (`destination`) together with the resolved destination port (`destinationPort`), and the estimated time of arrival to the next port (`eta`). The position time is returned both as a human readable `dateTime` (ISO 8601) and as an epoch `timestamp` (in ms). **Note**: `originPort` is only returned when a recent enough port call can be resolved for the vessel; otherwise it is omitted. - [Get vessel position](https://developer.searoutes.com/reference/getvesselposition.md): Retrieve information from AIS and return general information about the vessel together with its last known position, its last known speed (in km/h) and its current draft (in m). If an IMO was not found, the object at its position is `null`. - [Get the timeseries of a vessel](https://developer.searoutes.com/reference/getvesseltimeseries.md): This endpoint returns the historical timeseries of a vessel between two dates in the past. We return the successive positions of the vessel, retrieved from both dynamic and static AIS messages. ### Vessel information The vessel can be specified either by passing its `imo` number or its `mmsi`. In the case both are given, the `mmsi` will be taken into account. ### Dates This endpoint takes two dates as argument to specifying the window of the timeseries. Both dates are required and can be passed using the ISO 8601 format (`departureDateTime` and `arrivalDateTime`) or the unix time in milliseconds (`departure` and `arrival`). About the time range: this endpoint returns a position point for every AIS signal received during the requested period, which can result in very large responses for active vessels over long date ranges. To ensure reliable results, we recommend keeping your date range to 3 months or less. If you need data covering a longer period, split your query into consecutive 3-month windows. ### Response The response is a Geojson `FeatureCollection`, where each position is represented as a Feature. Each feature gathers the properties of the position: speed over ground (kmh), draft (meters), heading (degrees), etc. - [Get trace of vessel](https://developer.searoutes.com/reference/getvesseltrace.md): This endpoint returns the historical trace of a given vessel between two dates in the past. The successive positions of the vessel are retrieved from AIS and processed to determine the geometry and route statistics. ### Vessel information The vessel can be identified either by its `imo` number or its `mmsi`. In the case both are given, the `mmsi` will be taken into account. ### Dates This endpoint takes two dates for the beginning and the end of the trace. Both are required and can be passed using the ISO 8601 format (`departureDateTime` and `arrivalDateTime`) or the unix time in milliseconds (`departure` and `arrival`). ### Response The response is a Geojson `FeatureCollection`. The trace is represented as a `Feature` : its geometry is a MultiLineString (cut at the antimeridian if crossed) and its properties give information about the route (distance, areas crossed, average speed). Total distance + distances in Seca zones and HRA are returned. Note that the average speed is computed for the entire trace. If the vessel stops multiple days, the average speed can be low. - [Get vessel arrivals at port (beta)](https://developer.searoutes.com/reference/getvesselarrivals.md): Retrieve a structured list of vessels scheduled to arrive at a specified port, identified by its UN/LOCODE. This endpoint is designed for operational monitoring, congestion analysis, and port traffic visibility. ### Response Vessels are: - Sorted by ETA (earliest -> latest) - Filtered to include only vessels with a known ETA - Limited to a short operational time window (recent arrivals + upcoming arrivals) ### Notes & considerations: - This endpoint relies on AIS destination data. - [Get latest weather at location](https://developer.searoutes.com/reference/getweather.md): Get historical, real or forecasted weather information at a given location. In the response, we return the closest point, on a 0.5 degree grid, at which our models computed weather information (wind, waves, current, etc.). Likewise, we find the closest timestamp to your requested timestamp for which we have data. For instance, when requesting weather information at the point `{"latitude": 17.152, "longitude": -80.564, "timestamp": 1548388800000}`, we return data for our closest point ` {"latitude": 17, "longitude": -80.5, "timestamp": 1548385200000}`. All values are expressed in the standard SI units (temperatures in Celcius degrees, humidity, cloud coverage and ice coverage in percentages, pressure in hectopascals, precipitation in millimeters, times in seconds, distances in meters, speeds in meters per second, salinity in PSU). - [Get Forecasted weather at location](https://developer.searoutes.com/reference/getweatherforecast.md): Get forecasted weather information in bulk, at a given location. By default we return weather information every 3 hours for your requested timeframe. If you do not specify a timeframe, we return the full 14 days forecast. The timestamp you pass in your request needs to be after today. All values are expressed in the standard SI units (temperatures in Celcius degrees, humidity, cloud coverage and ice coverage in percentages, pressure in hectopascals, precipitation in millimeters, times in seconds, distances in meters, speeds in meters per second, salinity in PSU). - [Get historical weather at location](https://developer.searoutes.com/reference/getweathertimeframe.md): Get historical weather information in bulk, at a given location, for the period 2013-today. By default we return weather information every 3 hours for your requested timeframe. You cannot request data for more than two weeks at a time. All values are expressed in the standard SI units (temperatures in Celcius degrees, humidity, cloud coverage and ice coverage in percentages, pressure in hectopascals, precipitation in millimeters, times in seconds, distances in meters, speeds in meters per second, salinity in PSU). - [Get weather along a route](https://developer.searoutes.com/reference/postweather.md): When using our [`/route/v2/`](/reference/getsearoute) endpoint, users are returned suggested vessel routes, for a particular vessel and speed, through canals and straight. You can use our `weather/v2/track` endpoint to post the route you obtained from `/route/v2/`, in order to get the weather at each route point. This works both in the past, with historical values, or in the future, with forecasted values. Alternatively, you can form your own GeoJSON object, and post it to our `weather/v2/track` endpoint to obtain weather on your route. A minima, your FeatureCollection should contain at least one Feature, with the properties `departure` and `speed`, and the corresponding geometry. Below an example of such a minimal object: ```json { "type": "FeatureCollection", "properties": {}, "features": [ { "type": "Feature", "properties": { "departure": 1581166465000, "arrival": 1581191106000, "duration": 24641000, "speed": 42.0 }, "geometry": { "type": "LineString", "coordinates": [[7.294921874999999,54.265224078605684],[3.076171875,54.13669645687002],[-1.318359375,57.9148477670092]] } } ] } ``` Note that using our endpoint [`/route/v2/sea/{coordinates}/plan`](/reference/getplansearoute) yields the best results, since we cap the vessel speed in canals and straights where there are vessel speed restrictions. All values are expressed in the standard SI units (temperatures in Celcius degrees, humidity, cloud coverage and ice coverage in percentages, pressure in hectopascals, precipitation in millimeters, times in seconds, distances in meters, speeds in meters per second, salinity in PSU). - [Get CO₂e for given shipment](https://developer.searoutes.com/reference/getco2forshipment-1.md): > ❗️ Important > As part of our transition to ISO-14083 certification, we've made some adjustments that don't require any action on your part. You can find detailed information about the changes in our [changelog](https://developer.searoutes.com/changelog/searoutes-cycle-21-pre-release-notice-preparing-for-shipment-api-v20-changes). You can also explore the new ISO-compliant version [here](/reference/getco2forshipment). This endpoint computes CO₂e emissions (i.e CO2 equivalent emissions) for a given shipment. Shipment API allows you to define multiple route legs with multiple containers or parcels. The response contains CO2e per route leg as well as per order and total CO₂e of the shipment. Shipment request is a nested json on the root level, it consists of required properties - `orders`, `legs` and optional properties - `metadata` and `details`. You can specify `details` of shipment that will be displayed on the certificate (pdf). The following `details` are allowed: `id`, `referenceNumber`, `status`, `carrier.id`, `carrier.scac`, `carrier.name` and `client.name`. Where `status` can be `BOOKED` or `ARRIVED` and `client.name` is the name of your client. Provided carrier id, name or scac are the only parameters taken into account when computing CO₂e. However, `legs[0].details.carrier` id, scac or name will take precedence if has been provided. To be more specific, `/search/v2/carriers` endpoint can be used to retrieve a carrier object by its name or scac and can be used in `details.carrier` or `legs[0].details.carrier`. You can define list of `orders` that belong to your shipment with maximum number of 5. All orders must include the `type` value. You can differentiate between container and parcel shipments using different `type` values. The different types are `FCL` (or `CONTAINER`), `LCL` and `PARCEL` (with `PALLET` and `UNIT_LOAD` as aliases). Each order must have at least one of the following properties: `weight` (weight of orders in kg) or `quantity` (number of containers for containerized shipping). You can optionally define `sizeTypeCode` (size and type of your container). The supported values and their meanings are: 20GP, 22G1, 2200, 22G0, 2202, 2210 (20ft, General purpose (Standard)) [Default] 40GP, 42G1, 42G0, 40G1 (40ft, General purpose (Standard)), 40HC, 45G1, 45G0, 4500, 4510 (40ft High cube, General Purpose), 22R1, 2231 (20ft, Reefer), 40NOR, 42R1, 4531 (40ft, Reefer), 40REHC, 45R1, 45R8 (40ft High cube, Reefer), 53GP (53ft High cube). You can also optionally provide `id` of your order. Field `legs` is a list of routes that are part of the shipment. Request must contain at leas one transport `leg` and maximum number of legs is 10. Each _leg_ requires `from` and `to` (origin and destination). The value could be coordinates `"59.11;6.14"` or a string that could be geolocated `"hamburg"`. Each _leg_ requires a `mode`. The following modes are supported: `sea`, `road`, `rail`, `inland-water` and `air`. Each _leg_ can have an optional `details`. For all _modes_ you can specify `dateTime` with `arrival` and `departure` properties in ISO_8601 format, preferrably with timezone `YYYY-MM-DDTHH-mm-ssTZD` (`2022-02-22T15:00:00+01:00`). if you want to use different distance than the one we calculate you can specify optional `distance` property. - For **mode sea** you can specify `details.voyageNumber` and `details.vessel`. Object `vessel` has two properties `name` and `imo`. Specifying `imo` of the `vessel` increases accuracy of CO2e values. Different way of improving accuracy of CO2e values is defining a carrier or `details.fuelType`. You can define `details.carrier.id`, `details.carrier.name` or `details.carrier.scac` per leg. In this case, you receive CO2e values that are calculated as average values of all the itineraries for given carrier on given route. If you define `details.carrier.scac` you are required to use UNLOCODES for origin (`from`) and destination (`to`) of your leg. Passing coordinates or location string will not pass our validation. If you provide both a vessel imo and a carrier id, scac or name the imo will take the precedence over the carrier. - For **modes road and rail** you can specify `details.fuelType` to get a more accurate CO2e. Furthermore, you can specify `details.truckSize` (integer) for mode `road`. If you don't pass the trucksize we will choose appropriate truckSize for you. To improve accuracy of CO2e values for mode `road` you can define `details.carrier.id`, `details.carrier.name` or `details.carrier.scac`. This works only for North America region and the computation uses SmartWay carrier data (Dray (CONTAINER) and Mix (AVERAGE_MIXED)). If the SCAC passed is not valid or we don't have enough data to compute CO2e, the computation will be based on GLEC defaults. - For **mode inland-water** you can specify `vesselType` with one of the following values: `MOTOR_VESSEL`, `COUPLED_CONVOY`, `PUSHED_CONVOY`, `CONTAINER_VESSEL_110`, `CONTAINER_VESSEL_135` or `CONTAINER_COUPLED`. Default value is `MOTOR_VESSEL.` - For **mode air**, you can specify `details.flight` to get the emissions based on the aircraft operated for this specific flight number. In case the flight number is not found but the carrier is, emissions will be modeled based on the mot representative aircraft for this carrier. If you don't know the flight number, you can choose to specify `details.aircraft` with two optional properties: `iata` (IATA designator of the aircraft type) and `type` (either `PASSENGER` or `CARGO`). While air mode still accepts **LCL** shipments, note that the parameter will automatically default to **PARCEL** as air shipments cannot be containerized. To avoid an inaccurate increase in CO₂e when your shipment includes `road` and `air` legs, specify the `truckSize` parameter. Each _leg_ can have optional `metadata`. You can add any information you want to `metadata` object and it will be returned to you in the response. Contents of `metadata` do not influence CO2e calculation. You can generate a certificate document (pdf) by setting the optional query parameter `generateCertificate` to `true`. ### Hubs Logistics hubs are locations where freight is stored and processed, and handled from one vehicle or transport mode to another. Hubs are an integral part of a shipment transport flows, and their impact is not to be overlooked. With our Shipment API, you can define hubs for your shipment as leg with mode `hub`. This type of leg does not include the standard properties of common legs but instead use a `detail` object with a `hubType` property. The `hubType` must be one of the following value: - `WAREHOUSE` - `TRANSHIPMENT_SITE` - `STORAGE_TRANSHIPMENT` - `LIQUID_BULK_TERMINAL` - `MARITIME_CONTAINER_TERMINAL` As we are finalizing ISO-14083 compliance, we now automatically detect and include `TRANSHIPMENT_SITE`, and `MARITIME_CONTAINER_TERMINAL` in our calculations. Please be aware that these are not reflected in the response of this current version, so you may see a small increase in the total CO₂e as a result. This is an example of such a leg: ```JSON ... { "mode": "hub", "details": { "hubType": "WAREHOUSE" } } ... ``` ### Container shipment For a container shipment the `type` of `orders` is required. The type can be `CONTAINER`, `FCL` or `LCL`. Result depends on `sizeTypeCode` and `quantity` of `orders` (1 by default), and if you provide the `weight` of the goods, this value will take priority over the `quantity` for the CO2 calculation in road and rail but also in sea and inland waters mode for LCL only. See list of available `sizeTypeCodes` above. Container shipment cannot be used in combination with `air` transport. Example of defined orders for container shipment: ```JSON "orders": [{ "type": "CONTAINER", "quantity": 2, }, { "type": "CONTAINER", "quantity": 1, "sizeTypeCode": "40GP" }] ``` ### Parcel shipment For a parcel shipment the `weight` of `orders` and `type` are required. See list of available parcel aliases above. Defining `quantity` of `orders` makes the request a container shipment. Example of defined order for parcel shipment: ```JSON orders: [{ type: "PALLET", weight: 7000, // in kilograms }] ``` ## Response The response contains `parameters` object which consist of `orders` and `type` specified in the request. The `co2e` object represents the CO2e of the entire shipment. You can also find a `co2e` object within each `leg` with the following properties: - `co2e.total` (value in grams) - `co2e.ttw` (Tank to Wheel - value in grams) - `co2e.wtt` (Well to Tank - value in grams) - `co2e.intensity` (value in Kg CO2e / t.km). While we use actual distances for emissions modeling, please note that intensity and transport activity calculations now adhere to ISO-14083 rules. These rules rely on the shortest feasible distance (SFD), making it easier to evaluate and compare itinerary efficiency. Legs also have `properties` field with data that were used to compute CO₂e. You can find common properties for all leg - order CO2e requests in the root of the properties and order specific data in particular order object for instance `properties.orders[0]`. Each order contains CO₂e object and has a common structure accross the whole shipment which is located in `legs[0].properties.orders[0].co2e`. `Parameters` property inside a leg holds `details` that were used in the request. `from` and `to` are objects containing `coordinates`, `locode` (if exists), `country` and `city`. The `certificateUrl` is where you can download certificate for your shipment in pdf format. We recommend saving this pdf right after receiving the response. - [Get CO₂e for a given vessel](https://developer.searoutes.com/reference/getco2forvessel.md): This endpoint returns CO2e emissions (i.e CO2 equivalent emissions) in grams (g) for the shortest path between a port of origin (from) and a port of destination (to). ### Origin and destination You must provide either `fromLocode` or `fromCoordinates` for the origin and either `toLocode` or `toCoordinates` for the destination. You can use the parameter `distance` (in meters) to pass your own distance (the origin and destination remain mandatory because the co2 computation is region dependent). ### Vessel information You can obtain accurate CO2 values for a specific vessel by passing its IMO as a query parameter. If we cannnot find enough data on the IMO you passed as a parameter, if you pass a wrong IMO number or if you pass no IMO, we estimate the CO2e emissions based on the trade lane (with 30 trade lanes supported) using the GLEC coefficients. #### Fuel types When a vessel IMO number is provided, we use its fuel type for emission factors, taking into account if necessary fuel switches within SECA zones (ie VLSFO -> LSMDO). Presence of a scrubber is also taken into account for emissions within SECA zones. If the fuel type for the vessel is missing from our dataset, we will use VLSFO as default value since it is IMO 2020 compatible. The optional customer parameter `fuelType` will overwrite the vessel’s default fuel if it is physically compatible with the structure of the vessel. For example, ULSFO or UCO for ships running on HFO, or VLSFO or BIOLNG for LNG ships using dual engines will be taken into account, but METHANOL for a HFO vessel will not. The fuel type taken into account for CO2 calculation is specified in the response (`fuelType` in properties). When no IMO number is provided, the response will use GLEC emission factors and `fuelType` parameter will not have an impact on the result. ### Cargo specifications (container only) We provide CO2 calculation for FCL and LCL. We support dry and reefer container types (`containerSizeTypeCode`). The following types are supported by our API : 20GP, 22G1, 2200, 22G0, 2202, 2210 (20ft, General purpose (Standard)) [Default] 40GP, 42G1, 42G0, 40G1 (40ft, General purpose (Standard)), 40HC, 45G1, 45G0, 4500, 4510 (40ft High cube, General Purpose), 22R1, 2231 (20ft, Reefer), 40NOR, 42R1, 4531 (40ft, Reefer), 40REHC, 45R1, 45R8 (40ft High cube, Reefer), 53GP (53ft High cube). ### Routing parameters #### Avoid zones ECA zones can be avoided by using the parameter `avoidSeca`. In that case, the distance travelled in the ECA zone is minimized. The HRA (high risk area) zone can be avoided using parameter `avoidHRA`. If no points from the query are in the HRA zones, the zone will be totally avoided, if at least one point is in the HRA zone, the route will go through it but minimize the distance navigated in it. #### Ice areas and block areas By default, the seas that are difficult to sail due to the presence of ice are not allowed (for example the Bering Sea, the Northern Sea Route, etc). You can allow the route to go through these zones by using the `allowIceAreas` parameter. It is possible to block some areas by using the parameter `blockAreas` which takes a list of ids (Panama Canal : 11112 , Suez Canal : 11117). In that case, the route won't cross the areas blocked. ### Impact of the weight and number of containers on CO2e emissions and intensity calculation #### For CO2e emissions: The CO2e emissions only depend on the number of containers (`nContainers`). If you don't know the `nContainers` but you know the total weight of the goods, our algorithm will estimate the `nContainers` based on the `weight`. If neither `nContainers` nor `weight` are provided, by default, we return emissions for one TEU (20G1, Dry). #### For CO2e intensity: The CO2e intensity depends on the `weight`. If you don't know the `weight` but you know the `nContainers`, our algorithm will estimate the `weight` based on the `nContainers`. *Note that you can give a non integer number of containers that allows you to calculate CO2e for LCL.* ### Response The response contains CO2e WTW (well-to-wheels) emissions in grams (g) for the shortest route between origin and destination ports. We also provide detailed emissions with TTW (tank-to-wheels) emissions and WTT (well-to-tank) emissions. The method takes into account the emissions caused by the fuel consumption of the main engines, the auxiliary engines and the boilers. The response also returns the intensity factor (kg of CO2e per ton.kilometer) which is calculated based on the CO2e WTW, distance and the weight provided. If no weight has been provided, we estimate the weight based on the number of containers and their type (`weight` in `properties`) The `parameters` field in the response contains all the parameters that were given in the request. The `properties` field in the response gives some data that was used to calculate the CO2 based on the parameters for example the distance, the distance in ECA zones, some data about the vessel, the trade lane, etc. The property `dataType` precise if the data used to calculate the CO2 emissions is `default` data (representative of average operating practices) or `modeled` data (taking into account vehicle information). Note that the distance we use to calculate CO2e is 15% higher than the shortest distance (returned in the response in meters (m)) as recommended by the GLEC framework to take into account the stops in other ports, the weather and all other deviations from the shortest route. ### Methodology references The method used to calculate emissions is based on the following references: - Third IMO Greenhouse Gas Study 2014; - Fourth IMO Greenhouse Gas Study 2020; - EMEP/EEA air pollutant emission inventory guidebook 2019; - GLEC Framework 2020. - [Get CO₂e for a given aircraft](https://developer.searoutes.com/reference/getco2foraircraft.md): This endpoint returns CO2e emissions (i.e CO2 equivalent emissions) in grams (g) for a direct flight between a source airport (origin) and a target airport (destination) ### Origin and destination You can pass either a Locode (`fromLocode`, `toLocode`), coordinates (`fromCoordinates`, `toCoordinates`) or a IATA airport code (`fromIata`, `toIata`) to specify the origin and the destination. You can use the parameter `distance` (in meters) to pass your own distance (the origin and destination remain mandatory because the co2 computation is region dependent). ### Aircraft and methodology You can either pass an aircraft IATA code to get the CO2 emissions of this specific aircraft or only the aircraft type. In case the IATA code is given, the emissions are calculated using EEA/EMEP methodology and EUROCONTROL data. They take into account take-off, landing, climbing, descent and cruising phases. In case the aircraft IATA is not given, we use the GLEC emission factors based on the length (short, medium, long haul) of the flight and the aircraft type (passenger, cargo or unknown). ### Weight You can pass the weight of the goods carried (in kg). The default weight is 1000 kg (1 metric ton) ### Response The response contains total CO2e WTW emissions and detailed emissions (in grams) : CO2e WTT (well-to-tank) emissions and CO2e TTW (tank-to-wheels) for the amount of goods carried. The response also contains the intensify factor (kg of CO2e per ton.kilometer) which is calculated based on the CO2e WTW emissions, the distance and the weight passed. The response contains the parameters passed in the request and the used values of the parameters if they were not passed. The `properties` field contains useful information about the data that was used for the calculation. For example the name, and model of the aircraft, the distance, etc. The property `dataType` precise if the data used to calculate the CO2 emissions is `default` data (representative of average operating practices) or `modeled` data (taking into account vehicle information). ### Methodology references The method uses CO2e emission factors from fuel consumption and distance calculation in accordance with EN 16258. - [Get CO₂e for inland waters](https://developer.searoutes.com/reference/getco2forinlandwater.md): This endpoint returns CO2e emissions (i.e CO2e equivalent emissions) in grams (g) for a voyage from a given inland port to another using the inland waterways network. ### Origin and destination The origin and destination ports can be given either as locodes or as coordinates. You must provide either `fromLocode` or `fromCoordinates` and either `toLocode` or `toCoordinates`. You can use the parameter `distance` (in meters) to pass your own distance (the origin and destination remain mandatory because the co2 computation is region dependent). ### Cargo specifications Several parameters allow you to define the specification of the cargo carried : `nContainers`, `containerSizeTypeCode`, `weight`. The following container types are supported by our API : 20GP, 22G1, 2200, 22G0, 2202, 2210 (20ft, General purpose (Standard)) [Default] 40GP, 42G1, 42G0, 40G1 (40ft, General purpose (Standard)), 40HC, 45G1, 45G0, 4500, 4510 (40ft High cube, General Purpose), 22R1, 2231 (20ft, Reefer), 40NOR, 42R1, 4531 (40ft, Reefer), 40REHC, 45R1, 45R8 (40ft High cube, Reefer), 53GP (53ft High cube). Here are common use cases : #### FCL use the parameters `nContainers` and `containerSizeTypeCode`. We recommend to use the parameter `containerSizeTypeCode` to precise the size and type of the containers. We will estimate the weight of the cargi based on the container specifications providesd. #### LCL use the parameters `weight` in combination with an appropriate `containerTypeSizeCode` (In case of reefer, you can choose 22R1) #### Default Use the parameters `weight` without container specifications. ### Vessel If known, the type of inland vessel can be given. By default, a motor vessel is always used to compute CO2e (`MOTOR_VESSEL`). ### Response The response contains WTT (well-to-tank) and TTW (tank-to-wheels) CO2e emissions in grams (g) for the amount of goods carried. It also contains the intensity factor (kg of CO2e per ton.kilometer) which is calculated from the WTW CO2e emissions, the distance and the weight (in `properties`). The response contains a `parameters` field which contains all the parameters that were passed in the query and the default values if some parameters were not passed. The response contains a `properties` field which contains the useful information that was used for the calculation, for example the distance of the route calculated. The property `dataType` precises if the data used to calculate the CO2 emissions is `default` data (representative of average operating practices) or `modeled` data (taking into account vehicle information). ### Methodology references The emissions are calculated using the GLEC framework. - [Get CO₂e for rail](https://developer.searoutes.com/reference/getco2forrail.md): This endpoint returns CO2e emissions (i.e., CO2e equivalent emissions) in grams (g) for a train voyage between two specified train stations. ### Origin and destination The train stations can be given either as locodes or as coordinates. You must provide either `fromLocode` or `fromCoordinates` and either `toLocode` or `toCoordinates`. We currently support calculation within these regions: Europe, North America, South America, Asia, Oceania, Europe/Asia, and Africa. Please note that both origin and destination must be in the same region. The distance between the origin and destination is computed using rail networks. However, you can use your own computed distance (in meters) using the `distance` parameter. It's important to note that while custom distance input is accepted, both the origin and destination remain mandatory as CO2e computation is region-dependent. ### Cargo specifications Several parameters allow to define the specification of the cargo carried: `nContainers`, `containerSizeTypeCode`, `weight` and `loadCharacteristics`. The following container types are supported by our API: 20GP, 22G1, 2200, 22G0, 2202, 2210 (20ft, General purpose (Standard)) [Default] 40GP, 42G1, 42G0, 40G1 (40ft, General purpose (Standard)), 40HC, 45G1, 45G0, 4500, 4510 (40ft High cube, General Purpose), 22R1, 2231 (20ft, Reefer), 40NOR, 42R1, 4531 (40ft, Reefer), 40REHC, 45R1, 45R8 (40ft High cube, Reefer), 53GP (53ft High cube). **Here are two common use cases:** #### Container For a container, use the parameters `nContainers` and `containerSizeTypeCode`. Additionaly, you can set the parameter `loadCharacteristics` to `CONTAINER`. If you also provide the `weight` of the goods, this value will take priority over the `nContainers`. If `weight` is not provided, an average of 10 tons per TEU will be taken into account for CO2e calculations. #### Average If you do not specify `loadCharacteristics`, or container specifications, we assume you have a cargo of type `AVERAGE_MIXED`. The default weight in that case is 1 metric ton, but it can be specified if known. ### Fuel The fuel type can be specified when known. Please note that certain fuel types may not be supported in all regions. ### Response The response contains WTT (well-to-tank) and TTW (tank-to-wheels) CO2e emissions in grams (g) for the amount of goods carried. It also contains the intensity factor (kg of CO2e per ton.kilometer) which is calculated from the WTW CO2e emissions, the distance and the weight (in `properties`). A `parameters` field is present, containing all the parameters that were passed in the query and the default values if some parameters were not passed. Additionally, a `properties` field, which contains useful information used for the calculation, for example, the distance. The property `dataType` specifies if the data used to calculate the CO2e emissions is `default` data (representative of average operating practices) or `modeled` data (taking into account vehicle information). ### Methodology references The emissions are calculated using the GLEC framework. - [Get CO₂e for road](https://developer.searoutes.com/reference/getco2forroad.md): This endpoint returns CO2e emissions (i.e., CO2 equivalent emissions) in grams (g) for a voyage from a city to another by road. ### Origin and destination The source and destination can be given either by locode or coordinates. You must provide either `fromLocode` or `fromCoordinates` and either `toLocode` or `toCoordinates`. The emissions are calculated using the real road network distance and based on the region. However, you can use the parameter `distance` (in meters) to pass your own distance (the origin and destination remain mandatory because the co2e computation is region-dependent). Supported regions are: Europe, North America, Ocenia South America, Africa and Asia. Please note that both origin and destination must be in the same region. ### Cargo specifications Container specifications such as `nContainers`, `nContainers`, `weight` and `loadCharacteristics` define the cargo specifications. The following container types are supported by our API: 20GP, 22G1, 2200, 22G0, 2202, 2210 (20ft, General purpose (Standard)) [Default] 40GP, 42G1, 42G0, 40G1 (40ft, General purpose (Standard)), 40HC, 45G1, 45G0, 4500, 4510 (40ft High cube, General Purpose), 22R1, 2231 (20ft, Reefer), 40NOR, 42R1, 4531 (40ft, Reefer), 40REHC, 45R1, 45R8 (40ft High cube, Reefer), 53GP (53ft High cube). **Here are some use cases:** #### Container For a container use the parameters `nContainers` and `containerSizeTypeCode`. If you also provide the `weight` of the goods, this value will take priority over the `nContainers`. If `weight` is not provided, an average of 10 tons per TEU will be taken into account for CO2e calculations. You can also pass a `truckSize` and a `fuelType`. Not all combinations are usable: in order to limit the errors and return CO2e emissions in most cases, we adapt `truckSize` and `fuel` parameters passed. If you do not specify a `truckSize`, an appropiate one will be chosen for you (except if you pass one). The parameters actually used are listed in the `properties` object of the response. #### Average If you do not specify the `weight` or the `loadCharacteristics`, we assume you have a cargo of type `AVERAGE_MIXED`. The default weight in that case is 1 metric ton of goods in the worst case scenario (smallest truck) (`loadCharacteristics = AVERAGE_MIXED or DEFAULT`). If the `weight` is specified, you must also provide the size of the truck (gross vehicle weight in tons) except for North America, where the truck size is not taken into account. ### Truck specifications For regions including Europe, South America, Africa and Asia, you can pass a `truckSize` (gross vehicle weight - GVW) for more accurate results. ### Fuel specifications For greater accuracy in CO2e values, you can specify the fuel type from the following options: - DIESEL - CNG - LNG - HVO - ELEC - BIOLNG - BIOCNG - BIODIESEL - HYDROGEN_GASEOUS_FCV Diesel-Biodiesel blends: - B1 (99% Diesel, 1% Biodiesel) - B2 (98% Diesel, 2% Biodiesel) - B5 (95% Diesel, 5% Biodiesel) - B7 (93% Diesel, 7% Biodiesel) - B10 (90% Diesel, 10% Biodiesel) - B20 (80% Diesel, 20% Biodiesel) - B30 (70% Diesel, 30% Biodiesel) - B50 (50% Diesel, 50% Biodiesel) For `ELEC` the calculation uses local emission factors from the origin. Additionally, for vans weighing less than 3.5t, you may select `LPG` and `PETROL` as fuel options in regions including Europe, South America, Africa and Asia. ### Carrier specifications (North America) We can compute CO2e for a given truck carrier (identified by its SCAC). This is only available in North America (the from/to locations should be within this region) and the computation uses SmartWay carrier data (Dray (CONTAINER) and Mix (AVERAGE_MIXED)). You can use the parameter `carrierScac` (which is a carrier alpha code identifier) to select the carrier. Note that in that case we only support DIESEL as fuel type and the `truckSize` cannot be changed. If the SCAC passed is not valid or we don't have enough data to compute CO2e, the computation will be based on GLEC defaults. In that case, the `carrierScac` property in the field `properties` of the response is set to `null`. ### Response The response contains WTW (well-to-wheels) CO2e emissions in grams (g) for the amount of goods carried and detailed emissions: WTT (well-to-tank) and TTW (tank-to-wheels). It also contains the intensity factor (kg of CO2e per ton.kilometer) which is calculated from the WTW CO2e emissions, the distance and the weight (in `properties`). The field `parameters` contains the parameters that were passed in the query and the default values that were used. Depending on the combination of parameters you enter, the default values for other parameters may vary. For example, the default `truckSize` for average mixed goods is 3t while it is 33t for container. The field `properties` contains information about the data that was used for the calculation, for example the distance, some characteristics about the truck, the hypothesis made for load factor, etc. The property `dataType` indicates whether the data used to calculate the CO2 emissions is `default` data (representative of average operating practices) or `modeled` data (which takes into account specific vehicle information). ### Methodology references The emissions are calculated using the GLEC framework or SmartWay Carrier data. You can find detailed information about the calculation and the hypothesis in our Guide section. - [Get itinerary by hash.](https://developer.searoutes.com/reference/getitinerarybyhashold.md): > ❗️ Deprecation Notice > This endpoint (`/itinerary/v2/hash/{hash}`) is **deprecated** but will continue to be maintained. > It is replaced by [`/itinerary/v2/proformas/{hash}`](/reference/getItineraryByHash), the only change is the url. > We recommend updating your integration to use the new endpoint to ensure long-term compatibility. This endpoint returns the details about an itinerary by hash (the unique fingerprint used to identify them). Itinerary hashes are returned in [/co2/v2/plan](/reference/getco2plan) for example. The response is a feature collection where each feature corresponds to a leg of the itinerary. Each feature has its own properties such as the distance, the duration, the day of departure and arrival, the service id, etc. The feature collection properties are those of the entire itinerary : duration (including transhipments, wait in ports), ids of the carriers that can operate the itinerary, etc. The distances are given in meters and the CO2e emissions in grams per TEU. ## Pages - [Report](https://developer.searoutes.com/page/report.md) - [🟢 Status](https://developer.searoutes.com/page/status.md) ## Changelog - [🛰️ Richer AIS context on vessel positions](https://developer.searoutes.com/changelog/️-richer-ais-context-on-vessel-positions.md) - [🚚 Milk Run API methodology update, vessel timeseries error handling](https://developer.searoutes.com/changelog/milk-run-api-methodology-update-vessel-timeseries-error-handling.md) - [📗 Up-to-date GLEC factors, vessel arrivals by port new endpoint](https://developer.searoutes.com/changelog/up-to-date-glec-factors-vessel-arrivals-by-port-new-endpoint.md) - [📄 Shipment API v2.1 Certificate release](https://developer.searoutes.com/changelog/cycle-28-shipment-api-v21-certificate-release.md) - [🍚 Bulk and breakbulk emissions all modes, v3 Fuel switch, V3 Emission new endpoint, and Milk Run fuels support](https://developer.searoutes.com/changelog/bulk-and-breakbulk-emissions-all-modes-v3-fuel-switch-v3-emission-new-endpoint-and-milk-run-fuels-support.md) - [🚢 Schedules routing via COGH and Suez, accurate historical traces, and container types supported](https://developer.searoutes.com/changelog/small-fixes.md) - [🚢 Bulk & breakbulk emissions, and other improvements](https://developer.searoutes.com/changelog/bulk-and-breakbulk-emissions-vessel-data-update.md) - [🇬🇧 UK ZIP codes, 🗺️ Mediterranean ECA and more](https://developer.searoutes.com/changelog/uk-postcodes-now-supported-️-med-eca-zone-added.md) - [🔍 Services search, Tender benchmarking & Shipments dashboard](https://developer.searoutes.com/changelog/release-q1-2025-.md) - [🚢 Ocean schedules, GLEC 3.1 update, Vessel Timeseries and more](https://developer.searoutes.com/changelog/searoutes-1.md)