CO2 API – Overview
Why should you compute CO2 emissions ?
Computing CO2 emissions for your sea transportation will help you evaluate their importance, and assess the performance of your transportation model. It will help you understand your environmental impact, comply with regulations, report sustainability efforts, and make informed decisions to promote a greener future.
Using our API, you will be able to evaluate the impact of each voyage, and thus identify where you can improve your logistics performance. It can also help you compare different routes to find the most environmentally friendly.
What is computed exactly?
CO2 emissions are computed using two different methods : one is vessel agnostic and focusses on the voyage information to help you evaluate the generic emissions over a route. The second one is vessel-specific and modelizes vessel characteristics to estimate fuel consumption and emissions.
For both vessels, we compute Well to Wheel, Well to Tank and Tank to Wheel emissions in Tons of CO2e by TEU (read https://joint-research-centre.ec.europa.eu/welcome-jec-website/jec-activities/well-wheels-analyses_en to learn more), but also the WtW emission intensity in Tons by TEU-km.
Endpoints
Authentication and Headers
Sinay CO2 API uses the same API Framework as all the other Sinay APIs. Authorization is completed via an API key that is added to the API request header.
To know more about Sinay APIs authorization and headers, follow https://developers.sinay.ai/general-documentation .
GET /compute-co2
This endpoint allows you to compute the CO2 equivalent emitted for a TEU over a voyage.
Request
Use the headers recommended in https://developers.sinay.ai/general-documentation, in the body (payload), you will have to specify the voyage characteristics.
You must submit a request with a valid vessel id: either an IMO number or an MMSI number. (If you are not familiar with IMO or MMSI, you can find more information here https://sinay.ai/en/what-is-the-difference-between-imo-and-mmsi/) You can also use our API Ports&Vessels to search for the vessel of your choice and retrieve its identifiers.
You must identify the arrival port with its official UN/LOCODE. If you are not familiar with UN/LOCODEs, you can find more information here https://unece.org/trade/cefact/unlocode-code-list-country-and-territory. You can also use our Ports&Vessels API search to look for the port of your choice and retrieve its UN/locode.
{
"vessel": {
"imo": 9706906
},
"departure": {
"portCode": "FRLEH"
},
"arrival": {
"portCode": "ESBCN"
}
}
You can
also optionally specify the vessel speed in knots.
{
"vessel": {
"imo": 9706906,
"speed": 13
},
"departure": {
"portCode": "FRLEH"
},
"arrival": {
"portCode": "ESBCN"
}
}
Response
The response body for this endpoint will display the following results:
These fields are a reminder of the parameters you submitted in your request. They can be null if you did not specify the field in your request. This does not mean that we computed the emissions for a vessel with a null MMSI or with a speed of zero.
- Input departure and arrival port codes
These fields are a reminder of the parameters you submitted in your request.
- Length
This field provides you with the length of the voyage which we computed the emissions against. The length is expressed in nautical miles.
- CO2 emission – vessel model
These fields provide you the tons of CO2 equivalent emitted over the voyage, computed by the vessel model method. This method takes into account the vessel characteristics and speed to model the vessel fuel consumption over the voyage and thus the CO2 emissions.
You can differentiate WtW (Well to Wheel) and its subparts WtT (Well to Tank) and TtW (Tank to Wheel) emissions. They are expressed in Tons by TEU.
You will also find the WtW emission intensity for this method: the CO2e emitted by TEU and by kilometer.
- CO2 emission – tradelane method
These fields provide you the tons of CO2 equivalent emitted over the voyage, computed by the tradelanes method. This method only takes into account voyage characteristics, and is vessel agnostic.
You can differentiate WtW (Well to Wheel) and its subparts WtT (Well to Tank) and TtW (Tank to Wheel) emissions. They are expressed in Tons by TEU.
You will also find the WtW emission intensity for this method : the CO2e emitted by TEU and by kilometer.
{
"input": {
"vessel": {
"imo": 9706906,
"mmsi": null,
"speed": null
},
"departure": {
"portCode": "FRLEH"
},
"arrival": {
"portCode": "ESBCN"
}
},
"length": 1709.7834398908199,
"co2EmissionResult": {
"vesselMethodResult": {
"co2Wtt": 0.043543922905257035,
"co2Ttw": 0.5275513736598448,
"co2Wtw": 0.5710952965651018,
"WtwEmissionIntensity": 0.0001803542972796
},
"tradeLaneMethodResult": {
"co2Wtt": 0.025332151445422387,
"co2Ttw": 0.32298493092913544,
"co2Wtw": 0.3483170823745578,
"WtwEmissionIntensity": 0.00011
}
}
}
GET /usages
This endpoint allows you to monitor the number of calls that were made using your API key in a given period of time. You can also retrieve this information from the monitoring page in Sinay’s Developers Platform https://developers.sinay.ai/monitoring.
Request
Without query params
If you send a request without any query params, you will get all API calls made with your key since the creation of the key, month by month.
With query params
You can also specify the startTime and/or endTime as query params (in UTC format – more detailed information on this format here : https://www.w3.org/TR/NOTE-datetime-970915.html)
If you do so, the response given will include only the calls made during the specified period.
Response
The response will show all calls made during the specified period, detailed by status, and a detailed report of calls and status, month by month.
{
"apis": {
"co2": {
"allCalls": 1713,
"successCalls": 1295,
"clientErrorCalls": 418,
"serverErrorCalls": 0,
"consumedApiUnits": 0,
"periodicUsages": {
"2023-01": {
"allCalls": 8,
"successCalls": 8,
"clientErrorCalls": 0,
"serverErrorCalls": 0,
"consumedApiUnits": 0
},
"2023-02": {
"allCalls": 654,
"successCalls": 436,
"clientErrorCalls": 218,
"serverErrorCalls": 0,
"consumedApiUnits": 0
}
}
}
}
