--- updatedAt: 2026-07-17T07:00:52.000Z agentTools: projectIndex: https://developer.searoutes.com/llms.txt --- # Get CO₂e for a complete run ## 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. # OpenAPI definition ````json { "openapi": "3.1.0", "info": { "version": "2.10.0", "title": "Carbon Emissions", "description": "# Introduction\nThe Searoutes web services APIs allow you to programmatically access tools and services from the Searoutes ecosystem. You can use these APIs to retrieve informations about vessel positions, vessel routes, GHG emissions, weather and other core data points. Searoutes services are divided in five categories:\n\n- Our [CO2 service](#tag/co2) calculates the CO₂e emissions of a container on several modes of transport `SEA`, `AIR`, `RAIL` and `ROAD`.\n\n- Our [Vessel service](#tag/vessel) gives you up to date positions of vessels and estimated travel times to their next destination.\n\n- Our [Weather service](#tag/weather) lets you explore weather data points in the past or the future, at a location or on a route.\n\nNote that this is the documentation page for most recent stable version of Searoutes API. For the previous stable versions, [visit this documentation page](http://developer.searoutes.com/api/v1). \n\nIf you have a `valid API key`, you may try the API by copying the code samples in your shell, your favorite editor, or API development platform. Please be aware that some endpoints may not work with your API key depending on your service plan. If you would like a trial key or you want to add additional endpoints to your plan, please [get in touch with us](https://searoutes.typeform.com/to/ZRAoy5).\n", "termsOfService": "https://searoutes.com/terms-of-service/", "contact": { "email": "support@searoutes.com", "url": "https://searoutes.com" }, "x-logo": { "url": "/img/searoutes-logo-vertical-blue.svg", "altText": "Searoutes logo" } }, "servers": [ { "url": "https://api.searoutes.com" } ], "paths": { "/asset/v2/run/co2": { "post": { "operationId": "getCO2ForARun", "tags": [ "For a milkrun" ], "summary": "Get CO₂e for a complete run", "description": "\n## Description \n\nThis endpoint computes CO₂e emissions for a complete road collection and delivery operation, also known as a milk run.\nTotal 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.\n\n## Input overview\nThe endpoint takes as input:\n- **locations**: the ordered sequence of stops in the run\n- **orders**: the shipments carried, each referencing stop indices\n- **details**: vehicle characteristics (fuel type, truck size)\n- **metadata**: any custom key-value pairs, returned as-is in the response\n\n### Locations & terminal handling\n\n- A run is the full itinerary taken by the vehicle. \n- Locations can be expressed as UNLOCODE strings (e.g. `\"FRMRS\"`) or as `\"longitude,latitude\"` coordinates (e.g. `\"8.833,53.884\"`). \n- The order in the list determines each stop's index, starting at `0`.\n\nThree run shapes are supported:\n\n**Open loop**: the vehicle does not return to its starting point:\n```json\n\"locations\": [\"FRMRS\", \"FRVAF\", \"FRLIO\"]\n```\n\n**Closed loop**: the vehicle returns to its starting point; repeat the first location at the end:\n```json\n\"locations\": [\"FRMRS\", \"FRVAF\", \"FRLIO\", \"FRMRS\"]\n```\n\n**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:\n```json\n\"locations\": [\"\", \"FRMRS\", \"FRVAF\", \"FRLIO\", \"\"]\n```\n\nThe 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.\n\n### Orders\n\nEach order represents a parcel transported from one stop to another. Orders must cover all goods moved during the run.\nThe endpoint takes as input:\n- `fromIndex`: index of the pickup stop\n- `toIndex`: index of the delivery stop\n- `weight`: weight in kilograms\n- `id`: optional identifier, returned in the response\n- `type`: must be `\"PARCEL\"`\n\nExample: a 1,500 kg shipment picked up at index 1 (FRMRS) and delivered at index 4 (FRVAF):\n```json\n{\n \"fromIndex\": 1,\n \"toIndex\": 4,\n \"weight\": 1500,\n \"id\": \"ABC123\",\n \"type\": \"PARCEL\"\n}\n```\n\n## Methodology\n\n### Full run emissions\n\nThe Run API models emissions for the complete vehicle run, using:\n- road network distances between successive locations,\n- vehicle characteristics (fuel, size),\n- load evolution along the route,\n- empty and loaded movements.\n\n### Shipment allocation (ISO 14083)\n\nEmissions 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.\n\n## Response\n\nThe response contains:\n\n- **`co2e`**: total emissions in grams for the entire run, split into WTT and TTW.\n- **`orders`**: CO2e allocation per order, including intensity, allocation percentage, distance.\n- **`parameters`**: the resolved run definition (locations with indices, vehicle details).\n- **`properties`**: computation details: allocation method, data type, total distance, empty running ratio, and per-leg properties (distance, region, load factor).\n\n## Notes & considerations\n\n- **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).\n- **Metadata**: any value added to the `metadata` object is returned unchanged in the response. It has no effect on the CO2e calculation.\n- **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.\n- **ISO 14083 alignment**: the allocation method and emission calculations follow the ISO 14083 standard.\n\n## Support endpoints and resources\n\nFor a detailed information about the **Milk Run methodology**, refer to our [Guides](https://developer.searoutes.com/docs/milk-run) section.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/milkrun" } } }, "description": "Request Object with run and parcels" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "metadata": { "customKey1": "customValue1", "customKey2": "customValue2" }, "co2e": { "total": 1793887, "wtt": 315591, "ttw": 1478296 }, "orders": [ { "co2e": { "total": 857981, "wtt": 150941, "ttw": 707040, "intensity": 0.1396 }, "parameters": { "fromIndex": 0, "toIndex": 1, "weight": 12000, "id": "ABC123", "type": "PARCEL" }, "properties": { "allocation": 0.48, "distance": 512056 } }, { "co2e": { "total": 1026274, "wtt": 180548, "ttw": 845726, "intensity": 0.1015 }, "parameters": { "fromIndex": 1, "toIndex": 2, "weight": 12000, "id": "ABC124", "type": "PARCEL" }, "properties": { "allocation": 0.52, "distance": 768399 } } ], "parameters": { "locations": { "0": "ESBCN", "1": "FRMRS", "2": "FRGEB" }, "details": { "identifier": null, "size": 26, "fuel": "DIESEL", "carrier": { "name": "CARRIER_NAME", "scac": "SCXYZ" } } }, "properties": { "allocationMethod": "TRANSPORT_SERVICE_ALLOCATION", "dataType": "MODELED", "distance": 1280414, "emptyRunning": 0.41, "legs": [ { "properties": { "from": { "locode": "ESBCN", "coordinates": [ 2.1541063785553, 41.3384418487549 ], "city": "Barcelona", "country": "Spain" }, "to": { "locode": "FRMRS", "coordinates": [ 5.34005236625671, 43.3317317962646 ], "city": "Marseille", "country": "France" }, "distance": 512044, "region": "Europe", "loadFactor": 0.6 } }, { "properties": { "from": { "locode": "FRMRS", "coordinates": [ 5.34005236625671, 43.3317317962646 ], "city": "Marseille", "country": "France" }, "to": { "locode": "FRGEB", "coordinates": [ 1.92079, 48.4365 ], "city": "Garancières-en-Beauce", "country": "France" }, "distance": 768370, "region": "Europe", "loadFactor": 0.6 } } ], "truck": { "minSize": 26, "maxSize": 32, "identifier": "EURO6", "fuel": "DIESEL" } } } } } } }, "x-code-samples": [ { "lang": "curl", "source": "curl --location --request POST 'http://api.searoutes.com/asset/v2/run/co2' \\\n--header 'x-api-key: ' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"metadata\":{\n \"customKey1\":\"customValue1\",\n \"customKey2\": \"customValue2\"\n },\n \"locations\": [\n \"ESBCN\",\n \"FRMRS\",\n \"FRGEB\"\n ],\n \"orders\": [\n {\n \"fromIndex\": 1,\n \"toIndex\": 2,\n \"weight\": 12000,\n \"id\": \"ABC123\",\n \"type\": \"PARCEL\"\n },\n {\n \"fromIndex\": 2,\n \"toIndex\": 3,\n \"weight\": 12000,\n \"id\": \"ABC124\",\n \"type\": \"PARCEL\"\n }\n ],\n \"mode\": \"road\",\n \"details\": {\n \"truckSize\": \"26\",\n \"fuel\": \"DIESEL\",\n \"carrier\": {\n \"name\": \"CARRIER_NAME\",\n \"scac\": \"SCXYZ\"\n }\n }\n}'\n" } ], "security": [ { "api_key": [] } ] } } }, "components": { "securitySchemes": { "api_key": { "type": "apiKey", "name": "x-api-key", "in": "header", "description": "Use your `x-api-key` to authenticate with our APIs. Note that your key is tied with a usage plan. You are therefore rate limited depending on your subscription. If you wish you increase your request calls, please [get in touch with us](/contact/)." } }, "schemas": { "milkrun": { "type": "object", "required": [ "locations", "orders", "mode" ], "properties": { "metadata": { "type": "object" }, "locations": { "type": "array", "minItems": 1, "items": { "type": "string" }, "default": [ "FRMRS", "FRVAF" ] }, "orders": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "fromIndex": { "type": "integer", "description": "index of the stop where the parcel is loaded.", "default": 0 }, "toIndex": { "type": "integer", "description": "index of the stop where the parcel is unloaded.", "default": 1 }, "weight": { "type": "number", "description": "weight (in kg) of the parcel", "default": 1000 }, "id": { "type": "string", "description": "identifier of the booking (can be an external reference)", "default": "ABC1234" }, "type": { "type": "string", "enum": [ "PARCEL" ], "default": "PARCEL" } } } }, "mode": { "type": "string", "enum": [ "road" ], "default": "road" }, "details": { "type": "object", "properties": { "fuel": { "type": "string", "description": "fuel type of the truck used during the run.", "enum": [ "DIESEL", "CNG", "LNG", "PETROL", "HVO", "ELEC", "LPG", "BIOLNG", "BIOCNG", "HYDROGEN_GASEOUS_FCV", "BIODIESEL", "B1", "B2", "B5", "B7", "B10", "B20", "B30", "B50" ], "default": "DIESEL" }, "truckSize": { "type": "integer", "description": "truck size of the asset (GWV from 4t to 60t)", "default": 34 }, "carrier": { "type": "object", "properties": { "name": { "type": "string" }, "scac": { "type": "string" } } } } } } } } } } ````