{ "openapi": "3.0.3", "info": { "title": "Carbon Emissions API", "description": "API for calculating the greenhouse gas emissions of a freight shipment, in kilograms of CO2 equivalent.\nFollows ISO 14083:2023 with the default values of the GLEC Framework v3.1. Supports road, rail, sea, air and multimodal transport chains, routing by the Qubictron Transit Time API, and the carrier's own fuel consumption data.\n\n**Authentication** is required via an API key passed in the request headers.", "version": "1.0.0", "contact": { "name": "Qubictron API Support", "url": "https://www.qubictron.com" } }, "servers": [ { "url": "https://api.qubictron.com/co2/v1", "description": "Production server" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/emissions": { "post": { "summary": "Calculate shipment emissions", "operationId": "calculate-shipment-emissions", "description": "Returns the emissions of a shipment for every leg and section of its transport chain and in total:\n- Well-to-wheel (WTW), tank-to-wheel (TTW) and well-to-tank (WTT) CO2e\n- Distance, tonne-km and emission intensity\n- The route found for legs given by places, with transit time and, on request, alternative routes\n- The basis of every figure: the factor, its source and, for fuel data, the cargo's share\n\nA section emits its tonne-km times the GLEC default intensity of its vehicle type, or, with the carrier's own fuel data, the fuel used times the fuel's emission factor times the cargo's share of the vehicle load. Hub operations (terminals, warehouses) and the non-CO2 effects of aviation at altitude are not included. Routes found for legs given by places are kept for 24 hours.", "tags": [ "Emissions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmissionsRequest" }, "examples": { "Road, routed between two cities": { "summary": "Road, routed between two cities", "value": { "cargo": { "weight_kg": 12000 }, "legs": [ { "mode": "road", "from": "Paris", "to": "Lyon" } ] } }, "Road, the carrier's own consumption per 100 km": { "summary": "Road, the carrier's own consumption per 100 km", "value": { "cargo": { "weight_kg": 12000 }, "legs": [ { "mode": "road", "from": "Paris", "to": "Lyon", "vehicle_type": "artic_40t", "fuel": { "type": "diesel", "amount": 30, "unit": "l/100km", "load_kg": 20000 } } ] } }, "Rail, electric traction, known distance": { "summary": "Rail, electric traction, known distance", "value": { "cargo": { "weight_kg": 24000 }, "legs": [ { "mode": "rail", "from": "Hamburg", "to": "Munich", "distance_km": 780, "vehicle_type": "electric" } ] } }, "Sea, container ship, safe route with alternatives": { "summary": "Sea, container ship, safe route with alternatives", "value": { "cargo": { "teu": 1 }, "legs": [ { "mode": "sea", "from": "Shanghai", "to": "Hamburg", "alternative_routes": true, "routing_mode": "safe" } ] } }, "Sea, the vessel's own fuel for the voyage": { "summary": "Sea, the vessel's own fuel for the voyage", "value": { "cargo": { "teu": 2 }, "legs": [ { "mode": "sea", "from": "Shanghai", "to": "Hamburg", "fuel": { "type": "vlsfo", "amount": 4100000, "unit": "kg", "load_kg": 110000000 } } ] } }, "Air, belly freight between airports": { "summary": "Air, belly freight between airports", "value": { "cargo": { "weight_kg": 500 }, "legs": [ { "mode": "air", "from": "PVG", "to": "FRA", "vehicle_type": "belly" } ] } }, "Multimodal, the router's road and sea chain": { "summary": "Multimodal, the router's road and sea chain", "value": { "cargo": { "weight_kg": 12000 }, "legs": [ { "mode": "multimodal", "from": "Berlin, Germany", "to": "Shanghai" } ] } }, "Multimodal chain of explicit legs": { "summary": "Multimodal chain of explicit legs", "value": { "cargo": { "teu": 2 }, "legs": [ { "mode": "road", "from": "Prague", "to": "Hamburg", "vehicle_type": "artic_40t" }, { "mode": "sea", "from": "Hamburg", "to": "Shanghai" }, { "mode": "rail", "from": "Shanghai", "to": "Chongqing", "distance_km": 1700, "vehicle_type": "electric" }, { "mode": "road", "from": "Chongqing terminal", "to": "Chongqing DC", "distance_km": 30, "fuel": { "type": "diesel", "amount": 32, "unit": "l/100km" } } ] } } } } } }, "responses": { "200": { "description": "Emissions calculated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmissionsResponse" }, "examples": { "Multimodal, Berlin - Shanghai": { "summary": "Multimodal, Berlin - Shanghai by road and sea", "value": { "success": true, "status_code": "OK", "metadata": { "request_parameters": { "cargo": { "weight_kg": 12000 }, "legs": [ { "mode": "multimodal", "from": "Berlin, Germany", "to": "Shanghai" } ] }, "methodology": { "standard": "ISO 14083:2023", "factors": "GLEC Framework v3.1 default values (Europe tables where regional)", "scope": "Well-to-wheel (WTW) = tank-to-wheel (TTW) + well-to-tank (WTT), kg CO2e", "boundary": "Transport operations only: hub operations and the non-CO2 effects of aviation at altitude are excluded" } }, "data": { "weight_tonnes": 12, "distance_km": 20228.7, "tonne_km": 242744.3, "emissions": { "co2e_wtw_kg": 2080.66, "co2e_ttw_kg": 1739.83, "co2e_wtt_kg": 340.83 }, "intensity_g_per_tkm": 8.57, "legs": [ { "mode": "multimodal", "from": { "name": "Mitte", "country_code": "DE", "locode": null, "lat": 52.52003, "lng": 13.40489 }, "to": { "name": "Shanghai", "country_code": "CN", "locode": "CNSHG", "lat": 31.366365, "lng": 121.61475 }, "duration_hours": 776.4, "distance_km": 20228.7, "tonne_km": 242744.3, "emissions": { "co2e_wtw_kg": 2080.66, "co2e_ttw_kg": 1739.83, "co2e_wtt_kg": 340.83 }, "intensity_g_per_tkm": 8.57, "sections": [ { "mode": "road", "from": { "name": "Mitte", "country_code": "DE", "locode": null, "lat": 52.52003, "lng": 13.40489 }, "to": { "name": "Hamburg", "country_code": "DE", "locode": "DEHAM", "lat": 53.55073, "lng": 9.99302 }, "distance_km": 280.9, "tonne_km": 3370.4, "emissions": { "co2e_wtw_kg": 340.41, "co2e_ttw_kg": 262.89, "co2e_wtt_kg": 77.52 }, "intensity_g_per_tkm": 101, "basis": { "method": "default_intensity", "vehicle_type": "artic_40t", "intensity_wtw_g_per_tkm": 101, "intensity_ttw_g_per_tkm": 78, "source": "GLEC v3.1 Table 8 (Europe road, diesel, average/mixed load)" } }, { "mode": "sea", "from": { "name": "Hamburg", "country_code": "DE", "locode": "DEHAM", "lat": 53.55073, "lng": 9.99302 }, "to": { "name": "Shanghai", "country_code": "CN", "locode": "CNSHG", "lat": 31.366365, "lng": 121.61475 }, "distance_km": 19947.8, "tonne_km": 239373.9, "emissions": { "co2e_wtw_kg": 1740.25, "co2e_ttw_kg": 1476.94, "co2e_wtt_kg": 263.31 }, "intensity_g_per_tkm": 7.27, "basis": { "method": "default_intensity", "vehicle_type": "container_ship", "intensity_wtw_g_per_tkm": 7.27, "intensity_ttw_g_per_tkm": 6.17, "source": "GLEC v3.1 Table 14 (Clean Cargo industry average, dry, 10 t/TEU)" } } ] } ] } } }, "Road, own fuel per 100 km": { "summary": "Road with the carrier's own consumption", "value": { "success": true, "status_code": "OK", "metadata": { "request_parameters": { "cargo": { "weight_kg": 12000 }, "legs": [ { "mode": "road", "from": "Paris", "to": "Lyon", "vehicle_type": "artic_40t", "fuel": { "type": "diesel", "amount": 30, "unit": "l/100km", "load_kg": 20000 } } ] }, "methodology": { "standard": "ISO 14083:2023", "factors": "GLEC Framework v3.1 default values (Europe tables where regional)", "scope": "Well-to-wheel (WTW) = tank-to-wheel (TTW) + well-to-tank (WTT), kg CO2e", "boundary": "Transport operations only: hub operations and the non-CO2 effects of aviation at altitude are excluded" } }, "data": { "weight_tonnes": 12, "distance_km": 432, "tonne_km": 5184.4, "emissions": { "co2e_wtw_kg": 283.99, "co2e_ttw_kg": 218.26, "co2e_wtt_kg": 65.73 }, "intensity_g_per_tkm": 54.78, "legs": [ { "mode": "road", "from": { "name": "Paris", "country_code": "FR", "locode": "FRPAR", "lat": 48.85341, "lng": 2.3488 }, "to": { "name": "Bellecour Cordeliers", "country_code": "FR", "locode": null, "lat": 45.76162, "lng": 4.83513 }, "duration_hours": 10.8, "distance_km": 432, "tonne_km": 5184.4, "emissions": { "co2e_wtw_kg": 283.99, "co2e_ttw_kg": 218.26, "co2e_wtt_kg": 65.73 }, "intensity_g_per_tkm": 54.78, "sections": [ { "mode": "road", "from": { "name": "Paris", "country_code": "FR", "locode": "FRPAR", "lat": 48.85341, "lng": 2.3488 }, "to": { "name": "Bellecour Cordeliers", "country_code": "FR", "locode": null, "lat": 45.76162, "lng": 4.83513 }, "distance_km": 432, "tonne_km": 5184.4, "emissions": { "co2e_wtw_kg": 283.99, "co2e_ttw_kg": 218.26, "co2e_wtt_kg": 65.73 }, "intensity_g_per_tkm": 54.78, "basis": { "method": "fuel", "fuel_type": "diesel", "travelled_km": 453.6, "fuel_used": 136.091, "fuel_unit": "l", "cargo_share": 0.6, "factor_wtw_kg_per_unit": 3.478, "factor_ttw_kg_per_unit": 2.673, "source": "GLEC v3.1 p.77 (diesel, Europe, density 0.83)" } } ] } ] } } } } } } }, "400": { "description": "Bad Request. The request body is malformed or contains invalid, missing, or unsupported parameters; `errors` lists every problem by field. Also returned when the router did not recognise a place.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Vehicle type of another mode": { "summary": "Vehicle type of another mode", "value": { "success": false, "status_code": "WRONG_PARAMETERS", "message": "The vehicle type of a sea leg must be one of: container_ship, bulk_carrier, tanker, general_cargo, roro, ropax_ferry.", "errors": { "legs.0.vehicle_type": [ "The vehicle type of a sea leg must be one of: container_ship, bulk_carrier, tanker, general_cargo, roro, ropax_ferry." ] } } }, "Unknown field": { "summary": "Unknown field and missing places", "value": { "success": false, "status_code": "WRONG_PARAMETERS", "message": "The cargo must be an object with weight_kg or teu.", "errors": { "cargo": [ "The cargo must be an object with weight_kg or teu." ], "cargo.weight_kg": [ "The cargo.weight kg field is required when cargo.teu is not present." ], "cargo.teu": [ "The cargo.teu field is required when cargo.weight kg is not present." ], "legs.0.from": [ "The legs.0.from field is required when legs.0.distance_km is not present." ], "legs.0.to": [ "The legs.0.to field is required when legs.0.distance_km is not present." ] } } } } } } }, "401": { "description": "`INVALID_API_KEY` - the API key is missing or unknown. The header name must be lowercase `x-api-key`. Not counted against the limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "INVALID_API_KEY": { "value": { "success": false, "status_code": "INVALID_API_KEY" } } } } } }, "403": { "description": "`API_KEY_ACCESS_DENIED` - the key is valid but has no access to the Carbon Emissions API, or its monthly request limit is used up; `error` says which. Not counted against the limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "noAccess": { "summary": "The key has no access to this API", "value": { "success": false, "status_code": "API_KEY_ACCESS_DENIED", "error": "API_KEY_ACCESS_DENIED" } }, "quotaExceeded": { "summary": "The monthly request limit is used up", "value": { "success": false, "status_code": "API_KEY_ACCESS_DENIED", "error": "API_KEY_QUOTA_EXCEEDED" } } } } } }, "404": { "description": "Not Found. The router found no route of the leg's mode between its places. Give `distance_km` to calculate the leg without routing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NO_AVAILABLE_ROUTES": { "value": { "success": false, "status_code": "NO_AVAILABLE_ROUTES", "message": "legs.0: no rail route from \"Duisburg\" to \"Warsaw\". Give distance_km to calculate without routing." } } } } } }, "500": { "description": "Internal Server Error. An unexpected error occurred on the server side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UNEXPECTED_ERROR": { "value": { "success": false, "status_code": "UNEXPECTED_ERROR" } } } } } }, "502": { "description": "Bad Gateway. The routing service failed or did not answer in time; retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UPSTREAM_UNAVAILABLE": { "value": { "success": false, "status_code": "UPSTREAM_UNAVAILABLE", "message": "The routing service did not answer in time, please retry." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key required for authentication. Pass it as an HTTP header: `x-api-key: YOUR_API_KEY`. If the key is missing or invalid, the API returns HTTP 401 with `{\"success\": false, \"status_code\": \"INVALID_API_KEY\"}`." } }, "schemas": { "EmissionsRequest": { "type": "object", "description": "A shipment: its cargo and the legs it travels, in order. Unknown fields are refused with `WRONG_PARAMETERS`.", "required": [ "cargo", "legs" ], "additionalProperties": false, "properties": { "cargo": { "$ref": "#/components/schemas/Cargo" }, "legs": { "type": "array", "minItems": 1, "maxItems": 10, "description": "1 to 10 legs of the transport chain, in the order the cargo travels them.", "items": { "$ref": "#/components/schemas/Leg" } } } }, "Cargo": { "type": "object", "description": "The cargo, by weight or by containers: exactly one of `weight_kg` and `teu`.", "additionalProperties": false, "minProperties": 1, "maxProperties": 1, "properties": { "weight_kg": { "type": "number", "format": "double", "description": "Gross weight of the goods in kilograms.", "example": 12000, "minimum": 0, "exclusiveMinimum": true, "maximum": 1000000000 }, "teu": { "type": "number", "format": "double", "description": "Number of twenty-foot equivalent units. Converted at 10 tonnes per TEU (average loaded container, GLEC / ISO 14083).", "example": 2, "minimum": 0, "exclusiveMinimum": true, "maximum": 100000 } } }, "Leg": { "type": "object", "description": "One leg of the chain. Without `distance_km` the leg is routed by the Qubictron Transit Time API between `from` and `to`; the route may come back as several sections of different modes, each calculated by its own mode.", "required": [ "mode" ], "additionalProperties": false, "properties": { "mode": { "type": "string", "enum": [ "road", "rail", "sea", "air", "multimodal" ], "description": "Mode of transport:\n- `road` - by road\n- `rail` - by rail\n- `sea` - by sea\n- `air` - by air\n- `multimodal` - the router's door-to-door chain of road pre-carriage, sea and road on-carriage. Rail and air are not chosen by the router; add them as legs of their own.", "example": "road" }, "from": { "type": "string", "maxLength": 255, "description": "Start of the leg: a place name, address, UN/LOCODE, IATA/ICAO airport code or `latitude,longitude`. Required unless `distance_km` is given; then it is only a label in the answer. Place names are the safest input: the router does not know some LOCODEs (e.g. `CNSHA`; use `Shanghai`).", "example": "Paris" }, "to": { "type": "string", "maxLength": 255, "description": "End of the leg, in the same formats as `from`. Required unless `distance_km` is given.", "example": "Lyon" }, "distance_km": { "type": "number", "format": "double", "description": "Shortest feasible distance of the leg in kilometres (great-circle distance between airports for air), as ISO 14083 measures transport activity. Skips routing. Not allowed for `multimodal`, nor together with `alternative_routes` or `routing_mode`.", "example": 432, "minimum": 0, "exclusiveMinimum": true, "maximum": 50000 }, "vehicle_type": { "type": "string", "enum": [ "van", "rigid_7_5t", "rigid_12t", "rigid_20t", "rigid_26t", "rigid_32t", "artic_40t", "artic_44t", "average", "diesel", "electric", "container_ship", "bulk_carrier", "tanker", "general_cargo", "roro", "ropax_ferry", "freighter", "belly" ], "description": "Vehicle type of the leg. Must belong to the leg's `mode`; not allowed for `multimodal`. If omitted, the mode's default type is used.\n\nDefault intensity of each type in g CO2e per tonne-km (WTW):\n\n| Mode | Vehicle type | g CO2e / t-km |\n| --- | --- | ---: |\n| `road` | `van` | 842 |\n| | `rigid_7_5t` | 335 |\n| | `rigid_12t` | 223 |\n| | `rigid_20t` | 191 |\n| | `rigid_26t` | 139 |\n| | `rigid_32t` | 125 |\n| | `artic_40t` (default) | 101 |\n| | `artic_44t` | 89 |\n| `rail` | `average` (default) | 18.5 |\n| | `diesel` | 30.7 |\n| | `electric` | 11.5 |\n| `sea` | `container_ship` (default) | 7.27 |\n| | `bulk_carrier` | 5.9 |\n| | `tanker` | 9.3 |\n| | `general_cargo` | 21.8 |\n| | `roro` | 22.4 |\n| | `ropax_ferry` | 110.9 |\n| `air` | `average` (default) | 1363 / 788 |\n| | `freighter` | 1516 / 608 |\n| | `belly` | 1239 / 936 |\n\n- `road`: Europe, diesel, average load. Trucks are named by gross vehicle weight: `rigid_12t` is 7.5-12 t GVW, `artic_40t` is 34-40 t.\n- `rail`: Europe, average load.\n- `sea`: `container_ship` is the Clean Cargo industry average (72.7 g per TEU-km at 10 t per TEU); for `roro` the tonne-km include the truck.\n- `air`: short haul under 1,500 km / long haul. `average` is GLEC's unknown aircraft type: 55% belly freight, 45% freighter.", "example": "artic_40t" }, "fuel": { "$ref": "#/components/schemas/Fuel" }, "alternative_routes": { "type": "boolean", "description": "Also calculate the router's alternative routes of this leg (`alternatives` in the answer). Only for routed legs.", "default": false, "example": true }, "routing_mode": { "type": "string", "enum": [ "short", "safe" ], "description": "Route to calculate: `short` - the shortest route; `safe` - a route that avoids areas of current geopolitical risk. Only for routed legs.", "default": "short", "example": "safe" } } }, "Fuel": { "type": "object", "description": "The carrier's own fuel or energy consumption, used instead of the default intensity for the sections of the leg's own mode (it wins over `vehicle_type`). Emissions = fuel used x the fuel's emission factor x the cargo's share of the vehicle load. Not allowed for `multimodal`.", "required": [ "type", "amount", "unit" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "diesel", "diesel_b7", "biodiesel", "hvo", "petrol", "cng", "lng", "electricity", "vlsfo", "hfo", "mgo", "lng_marine", "methanol", "jet_kerosene", "saf" ], "description": "Fuel or energy, with the modes and units it accepts:\n- `diesel` - road, rail; l, kg\n- `diesel_b7` - road, rail; l, kg\n- `biodiesel` - road, rail; l, kg\n- `hvo` - road, rail; l, kg\n- `petrol` - road; l, kg\n- `cng` - road; kg\n- `lng` - road; kg\n- `electricity` - road, rail; kWh\n- `vlsfo` - sea; kg\n- `hfo` - sea; kg\n- `mgo` - sea; kg\n- `lng_marine` - sea; kg\n- `methanol` - sea; kg\n- `jet_kerosene` - air; l, kg\n- `saf` - air; l, kg\n\nEmission factors are the GLEC Framework v3.1 European ones; `electricity` is the EU 27 average grid (0.356 kg CO2e per kWh WTW).", "example": "diesel" }, "amount": { "type": "number", "format": "double", "description": "Fuel used, in `unit`.", "example": 30, "minimum": 0, "exclusiveMinimum": true }, "unit": { "type": "string", "enum": [ "l", "kg", "kWh", "l/100km", "kg/100km", "kWh/100km" ], "description": "- `l`, `kg`, `kWh` - total the vehicle used on the leg; shared between the leg's sections of its mode by distance\n- `l/100km`, `kg/100km`, `kWh/100km` - consumption rate, applied to the distance really travelled: the shortest feasible distance with GLEC's adjustment (road x1.05, sea x1.15, air +95 km)\n\nThe unit must be one the fuel accepts (see `type`).", "example": "l/100km" }, "load_kg": { "type": "number", "format": "double", "description": "Total cargo on the vehicle in kilograms, this shipment included; the shipment carries `cargo weight / load_kg` of the fuel. Cannot be less than the cargo. Without it the shipment carries all of the fuel.", "example": 20000, "minimum": 0, "exclusiveMinimum": true } } }, "EmissionsResponse": { "type": "object", "description": "Root response envelope of a successful calculation.", "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was processed successfully.", "example": true }, "status_code": { "type": "string", "description": "A string code indicating the result of the request. See the error responses for the other values.", "enum": [ "OK", "WRONG_PARAMETERS", "NO_AVAILABLE_ROUTES", "UPSTREAM_UNAVAILABLE", "INVALID_API_KEY", "API_KEY_ACCESS_DENIED", "UNEXPECTED_ERROR" ], "example": "OK" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/EmissionsData" } } }, "Metadata": { "type": "object", "description": "Metadata about the request, useful for debugging and audit.", "properties": { "request_parameters": { "allOf": [ { "$ref": "#/components/schemas/EmissionsRequest" } ], "description": "Echo of the validated request." }, "methodology": { "$ref": "#/components/schemas/Methodology" } } }, "Methodology": { "type": "object", "description": "Standard and factors the figures follow, for emissions reporting.", "properties": { "standard": { "type": "string", "example": "ISO 14083:2023" }, "factors": { "type": "string", "example": "GLEC Framework v3.1 default values (Europe tables where regional)" }, "scope": { "type": "string", "example": "Well-to-wheel (WTW) = tank-to-wheel (TTW) + well-to-tank (WTT), kg CO2e" }, "boundary": { "type": "string", "example": "Transport operations only: hub operations and the non-CO2 effects of aviation at altitude are excluded" } } }, "Totals": { "type": "object", "description": "Totals of a shipment, leg or route. Parts are rounded first and totals are their sums, so the legs add up to the shipment.", "properties": { "distance_km": { "type": "number", "format": "double", "description": "Distance in kilometres: the shortest feasible distance, routed or given.", "example": 20228.7 }, "tonne_km": { "type": "number", "format": "double", "description": "Transport activity: tonnes x kilometres.", "example": 242744.4 }, "emissions": { "$ref": "#/components/schemas/Emissions" }, "intensity_g_per_tkm": { "type": "number", "format": "double", "description": "Emission intensity: WTW grams CO2e per tonne-km. Null when there are no tonne-km.", "example": 8.57, "nullable": true } } }, "Emissions": { "type": "object", "description": "Greenhouse gas emissions in kilograms of CO2 equivalent.", "properties": { "co2e_wtw_kg": { "type": "number", "format": "double", "description": "Well-to-wheel: the full life cycle of the fuel, the figure to report.", "example": 2080.66 }, "co2e_ttw_kg": { "type": "number", "format": "double", "description": "Tank-to-wheel: the fuel burnt by the vehicle.", "example": 1739.83 }, "co2e_wtt_kg": { "type": "number", "format": "double", "description": "Well-to-tank: producing and delivering the fuel or energy (WTW - TTW).", "example": 340.83 } } }, "EmissionsData": { "description": "The calculation: totals of the shipment and every leg.", "allOf": [ { "type": "object", "properties": { "weight_tonnes": { "type": "number", "format": "double", "description": "Cargo weight in tonnes (from `weight_kg`, or `teu` x 10).", "example": 12 } } }, { "$ref": "#/components/schemas/Totals" }, { "type": "object", "properties": { "legs": { "type": "array", "description": "The legs, in the order of the request.", "items": { "$ref": "#/components/schemas/LegResult" } } } } ] }, "Route": { "description": "A route of a leg: its ends, duration, totals and sections.", "allOf": [ { "type": "object", "properties": { "from": { "allOf": [ { "$ref": "#/components/schemas/Location" } ], "nullable": true, "description": "Start as the router resolved it, or the given label; null when not given." }, "to": { "allOf": [ { "$ref": "#/components/schemas/Location" } ], "nullable": true, "description": "End as the router resolved it, or the given label; null when not given." }, "duration_hours": { "type": "number", "format": "double", "description": "Transit time of the route in hours, from the router. Null for a leg with `distance_km`.", "example": 776.4, "nullable": true } } }, { "$ref": "#/components/schemas/Totals" }, { "type": "object", "properties": { "sections": { "type": "array", "description": "Parts of the route of one mode each.", "items": { "$ref": "#/components/schemas/Section" } } } } ] }, "LegResult": { "description": "A leg of the request with its main route and, when asked, the alternatives.", "allOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "road", "rail", "sea", "air", "multimodal" ], "description": "Mode of the leg, as requested.", "example": "multimodal" } } }, { "$ref": "#/components/schemas/Route" }, { "type": "object", "properties": { "alternatives": { "type": "array", "description": "The router's alternative routes with their own emissions. Present only with `alternative_routes: true`; may be empty.", "items": { "$ref": "#/components/schemas/Route" } } } } ] }, "Section": { "description": "A part of a route travelled by one mode.", "allOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "road", "rail", "sea", "air" ], "description": "Mode of this section.", "example": "sea" }, "from": { "allOf": [ { "$ref": "#/components/schemas/Location" } ], "nullable": true }, "to": { "allOf": [ { "$ref": "#/components/schemas/Location" } ], "nullable": true } } }, { "$ref": "#/components/schemas/Totals" }, { "type": "object", "properties": { "basis": { "$ref": "#/components/schemas/Basis" } } } ] }, "Basis": { "type": "object", "description": "How the section was calculated, for audit. `default_intensity`: tonne-km x the default intensity of `vehicle_type` (GLEC's defaults already include its distance adjustment). `fuel`: fuel used x emission factor x cargo share.", "properties": { "method": { "type": "string", "enum": [ "default_intensity", "fuel" ], "example": "default_intensity" }, "vehicle_type": { "type": "string", "description": "`default_intensity` only: the vehicle type used.", "example": "container_ship" }, "haul": { "type": "string", "enum": [ "short_haul", "long_haul" ], "description": "Air sections only: short haul under 1,500 km.", "example": "long_haul" }, "intensity_wtw_g_per_tkm": { "type": "number", "format": "double", "description": "`default_intensity` only: WTW grams CO2e per tonne-km.", "example": 7.27 }, "intensity_ttw_g_per_tkm": { "type": "number", "format": "double", "description": "`default_intensity` only: TTW grams CO2e per tonne-km.", "example": 6.17 }, "fuel_type": { "type": "string", "description": "`fuel` only: the fuel.", "example": "diesel" }, "travelled_km": { "type": "number", "format": "double", "description": "`fuel` with a per-100 km rate only: the distance the fuel was burnt over.", "example": 453.6 }, "fuel_used": { "type": "number", "format": "double", "description": "`fuel` only: fuel the vehicle used on the section, in `fuel_unit`.", "example": 136.08 }, "fuel_unit": { "type": "string", "enum": [ "l", "kg", "kWh" ], "example": "l" }, "cargo_share": { "type": "number", "format": "double", "description": "`fuel` only: the shipment's share of the vehicle load.", "example": 0.6 }, "factor_wtw_kg_per_unit": { "type": "number", "format": "double", "description": "`fuel` only: WTW kg CO2e per `fuel_unit`.", "example": 3.478 }, "factor_ttw_kg_per_unit": { "type": "number", "format": "double", "description": "`fuel` only: TTW kg CO2e per `fuel_unit`.", "example": 2.673 }, "source": { "type": "string", "description": "Source of the factor: GLEC Framework v3.1 table or page.", "example": "GLEC v3.1 Table 14 (Clean Cargo industry average, dry, 10 t/TEU)" } } }, "Location": { "type": "object", "description": "A place of the route. Only `name` is set for a label given with `distance_km`.", "properties": { "name": { "type": "string", "nullable": true, "description": "Name of the place.", "example": "Hamburg" }, "country_code": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2 country code.", "example": "DE" }, "locode": { "type": "string", "nullable": true, "description": "UN/LOCODE of the place, when it has one.", "example": "DEHAM" }, "lat": { "type": "number", "format": "double", "description": "Latitude in decimal degrees.", "example": 53.54, "nullable": true }, "lng": { "type": "number", "format": "double", "description": "Longitude in decimal degrees.", "example": 9.98, "nullable": true } } }, "Error": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates whether the request was processed successfully.", "example": false }, "status_code": { "type": "string", "description": "Machine-readable code of the error.", "example": "WRONG_PARAMETERS" }, "error": { "type": "string", "enum": [ "API_KEY_ACCESS_DENIED", "API_KEY_QUOTA_EXCEEDED" ], "description": "`API_KEY_ACCESS_DENIED` only: the reason - no access to this API, or the monthly request limit is used up.", "example": "API_KEY_QUOTA_EXCEEDED" }, "message": { "type": "string", "description": "What went wrong, for the developer. Not every error has one.", "example": "The cargo must be an object with weight_kg or teu." }, "errors": { "type": "object", "description": "`WRONG_PARAMETERS` only: every problem by field path.", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "cargo": [ "The cargo must be an object with weight_kg or teu." ] } } } } } } }