Sustainable logistics
The Lune API and our approach
Lune provides a single API for use in-app and web channels to fetch, mutate, and deliver the data necessary to offset CO₂ emissions across a range of verticals.
Our API-first approach allows our customers to embed carbon offsetting and emission calculations into logistics, payments, and fintech platforms to deliver a unique and programmatically driven experience that brings climate into our clients' products.
Overview
In this guide, you will learn how to interact with the Lune API to:
- Calculate emissions for shipments
- Offset emissions for shipments
Who is this guide for?
This guide is primarily aimed at Product Managers and developers looking to integrate CO₂ emissions estimations and offsetting into an existing end-user experience.
Feel free to contact our support team if you encounter any issues integrating our logistics use case.
Lune is Smart Freight Centre accredited, following the GLEC Framework.
Concepts
- Client account - You must create a client account for each of your clients to define their basic characteristics, such as name, currency, and beneficiary. Clients will be provided Lune defaults
- Lune defaults - Lune has provided a default Project bundle for each of our clients. Every order will be placed against the following projects and ratios:
- Conserving forests in Asia - 95%
- Ocean Carbon Removal - 5%
- Project bundle - Group of offsetting projects with similar characteristics., e.g., Conserving forests in Asia and Ocean Carbon Removal
- Offsetting preferences page - Your clients will decide whether to offset CO₂ emissions on this page
API flow
Getting an API key
First, head over to the Lune dashboard and generate a new API key.
Navigate to https://dashboard.lune.co/developers
Select New Test API Key, enter a value in the Name field, and select an account from Default account
Select Save
Copy your API key, as you'll need it to interact with the Lune API
Create a client account
A client account is required for each of your clients and defines their basic characteristics, for example, the currency used to display emission offsetting prices.
Store and map the client account id to your client in your database.
Client accounts are optional but recommended for B2B businesses and discouraged for B2C businesses. Learn about their benefits and how to use either.
Sample request
You can optionally pass in beneficiary
to link a client account to the legal entity receiving the carbon offset.
Sample response
A successful request will return a unique id, which you will need to pass in later interactions with the Lune API.
Where:
id
is the unique identifier for each of your clients, which you must map in your code basename
is a name that you will use to identify your client and present offsetting options tocurrency
defines the currency used to display the price for each offsetting optiontype
defines the type of account. Usetest
for your playgroundbeneficiary
is the legal entity shown on the Carbon Offset Certificate and carbon registries
Following a successful response, a client account will be added to your dashboard:
You can access the dedicated client account page by appending the id
to /client-account
e.g., https://dashboard.lune.co/settings/client-accounts/K4enjo9g08vx3MpjnbpPrEZ57XJkDVdb
.
curl "https://api.lune.co/v1/accounts/client" \
-X POST \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"name": "MY TEST COMPANY",
"currency": "USD",
"beneficiary": "MY TEST COMPANY INC"
}'
{
"id": "K4enjo9g08vx3MpjnbpPrEZ57XJkDVdb",
"name": "MY TEST COMPANY",
"currency": "USD",
"balance": "0",
"balance_outstanding": "0",
"type": "test",
"scope": "client_account",
"beneficiary": "MY TEST COMPANY INC",
"organisation_id": "42O097M13DKvo5pmlJYZjmVlGzqJwXbE",
"bundle_portfolio_id": null,
"logo": null
}
Store a client's offsetting decision
On the Offsetting preferences page, your clients will be able to select whether to offset the CO₂ emissions from their logistics operation:
Store this decision in your database.
Calculating CO₂ emissions for a shipment
To present an estimate of CO₂ emissions for a given shipping route, pass in the journey details (e.g., route source and destination for one or more journey legs, shipment mode, load).
Sample request
Where:
$CLIENT_ACCOUNT_ID
is the unique identifier for the clientshipment
defines the shipment load; in this example, 40 tonneslegs
is a container object for one or more journey legsroute
is the source and destination for each leg in the chosen journey, which can either be the shipping distance or the start/destination address pair (physical address or coordinates)method
is the chosen form of transport
Sample response
A successful 200 request will result in an estimate of offsetting costs for the chosen journey.
Where:
id
is the unique identifier for the CO₂ emissions estimatelegs
is a container object for one or more journey legs, which includes the CO₂ emissionslegs.mass.amount
and distance per legmass.amount
is the aggregated CO₂ emissions for the chosen journeyquote.bundles
is a container object that confirms the client's offsetting decision (as defined in the Offsetting preferences page) and provides the details of each bundle, including the bundle id, bundle name, and unit pricequote.estimated_total_cost
is the total cost of offsetting the CO₂ emissions in the client's currencydistance
is the total distance for the chosen journey
curl https://api.lune.co/v1/estimates/shipping/multi-leg \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $API_KEY" \
-H "Lune-Account: $CLIENT_ACCOUNT_ID" \
-X POST \
-d '
{
"shipment": {
"mass": {
"amount": "10.36",
"unit": "t"
}
},
"legs": [
{
"route": {
"source": {
"lon": 120.960515,
"lat": 23.69781
},
"destination": {
"lon": 120.5075,
"lat": 24.255
}
},
"method": "diesel_truck"
},
{
"route": {
"source": {
"lon": 120.5075,
"lat": 24.255
},
"destination": {
"lon": 121.51,
"lat": 25.03
}
},
"method": {
"vessel_type": "container_ship"
}
},
{
"route": {
"source": {
"lon": 121.51,
"lat": 25.03
},
"destination": {
"lon": 9.9619,
"lat": 53.5231
}
},
"method": {
"vessel_imo_number": "9893890"
}
},
{
"route": {
"source": {
"lon": 9.9619,
"lat": 53.5231
},
"destination": {
"lon": 13.49587,
"lat": 52.4857
}
},
"method": "electric_freight_train"
},
{
"route": {
"source": {
"lon": 13.49587,
"lat": 52.4857
},
"destination": {
"lon": 13.2937333,
"lat": 52.362524
}
},
"method": "diesel_truck"
}
]
}'
{
"legs": [
{
"mass": {
"unit": "t",
"amount": "0.089758"
},
"distance": {
"unit": "km",
"amount": "106.9614"
},
"methodology": []
},
{
"mass": {
"unit": "t",
"amount": "0.030356"
},
"distance": {
"unit": "km",
"amount": "266.02"
},
"methodology": []
},
{
"mass": {
"unit": "t",
"amount": "0.897291"
},
"distance": {
"unit": "km",
"amount": "22247.389399999996"
},
"methodology": []
},
{
"mass": {
"unit": "t",
"amount": "0.048678"
},
"distance": {
"unit": "km",
"amount": "313.8612"
},
"methodology": []
},
{
"mass": {
"unit": "t",
"amount": "0.039615"
},
"distance": {
"unit": "km",
"amount": "47.2081"
},
"methodology": []
}
],
"mass": {
"unit": "t",
"amount": "1.105698"
},
"quote": {
"bundles": [
{
"quantity": "1.050413",
"bundle_id": "q9aKx7b6nNXMk3Yv3pD1mlW5Od2eLZE8",
"unit_price": "12.65",
"bundle_name": "Conserving forests in Asia",
"offset_cost": "13.29",
"gross_unit_price": "14.06",
"insufficient_available_quantity": null
},
{
"quantity": "0.055284",
"bundle_id": "xWaKJL3okjD46VpJ4yGXnQNZRe1vzP0w",
"unit_price": "250",
"bundle_name": "Ocean Carbon Removal",
"offset_cost": "13.82",
"gross_unit_price": "277.78",
"insufficient_available_quantity": null
}
],
"currency": "USD",
"requested_value": null,
"estimated_quantity": "1.105697",
"requested_quantity": "1.105698",
"estimated_commission": "3.02",
"estimated_total_cost": "30.13",
"estimated_offset_cost": "27.11"
},
"distance": {
"unit": "km",
"amount": "22981.440099999996"
},
"id": "08QD7GPaBx5b6Y6mJlWyONXLvrZljRE2",
"request": {
"shipment": {
"mass": {
"amount": "10.36",
"unit": "t"
}
},
"legs": [
{
"route": {
"source": {
"lon": 120.960515,
"lat": 23.69781
},
"destination": {
"lon": 120.5075,
"lat": 24.255
}
},
"method": "diesel_truck"
},
{
"route": {
"source": {
"lon": 120.5075,
"lat": 24.255
},
"destination": {
"lon": 121.51,
"lat": 25.03
}
},
"method": {
"vessel_type": "container_ship"
}
},
{
"route": {
"source": {
"lon": 121.51,
"lat": 25.03
},
"destination": {
"lon": 9.9619,
"lat": 53.5231
}
},
"method": {
"vessel_imo_number": "9893890"
}
},
{
"route": {
"source": {
"lon": 9.9619,
"lat": 53.5231
},
"destination": {
"lon": 13.49587,
"lat": 52.4857
}
},
"method": "electric_freight_train"
},
{
"route": {
"source": {
"lon": 13.49587,
"lat": 52.4857
},
"destination": {
"lon": 13.2937333,
"lat": 52.362524
}
},
"method": "diesel_truck"
}
]
}
}
Offsetting shipment emissions
For clients that have opted to offset their emissions in their Offsetting preferences page, when they book a shipment, you can present a confirmation of a booking, including the amount of CO₂ emissions that will be offset, the Lune default Project bundle, and the total cost of offsetting the CO₂ emissions. To do this, pass in the estimate id:
Sample request
Where:
$CLIENT_ACCOUNT_ID
is the unique identifier for the clientestimate_id
is the unique identifier for the emissions estimate
Sample response
A successful request will return an order summary, which can be displayed as part of your confirmation flow.
Where:
id
is the unique identifier for the booking
curl https://api.lune.co/v1/orders/by-estimate \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $API_KEY" \
-H "Lune-Account: $CLIENT_ACCOUNT_ID" \
-X POST -d '
{
"estimate_id": "08QD7GPaBx5b6Y6mJlWyONXLvrZljRE2"
}'
{
"id": "a1BER4JZqnzPkYxLKQeYLg0GeQDoXlWO",
"metadata": {},
"idempotency_key": null,
"type": "quantity",
"status": "placed",
"currency": "USD",
"offset_cost": "27.11",
"total_cost": "30.13",
"commission": "3.02",
"quantity": "1.105697",
"created_at": "2022-10-19T16:58:44.558Z",
"bundles": [
{
"bundle_id": "q9aKx7b6nNXMk3Yv3pD1mlW5Od2eLZE8",
"bundle_name": "Conserving forests in Asia",
"quantity": "1.050413",
"unit_price": "12.65",
"gross_unit_price": "14.06",
"offset_cost": "13.29",
"insufficient_available_quantity": null
},
{
"bundle_id": "xWaKJL3okjD46VpJ4yGXnQNZRe1vzP0w",
"bundle_name": "Ocean Carbon Removal",
"quantity": "0.055284",
"unit_price": "250",
"gross_unit_price": "277.78",
"offset_cost": "13.82",
"insufficient_available_quantity": false
}
],
"projects": [],
"certificate": null,
"offset_link_id": null,
"email": null,
"estimate_id": "08QD7GPaBx5b6Y6mJlWyONXLvrZljRE2",
"requested_quantity": "1.105698",
"requested_value": null
}