Single leg

Deprecated. Please use the Multi leg method instead.

Create a shipping emission estimate (single)

HTTP POST to /v1/estimates/shipping

Query parameters

estimate_mass_unitstring

By default estimate mass units are returned in tonnes.

Estimate mass units in responses are converted to estimate_mass_unit when set.

mg

g

kg

t

Request body

Parameters for estimating shipping emissions

shipmentoneOfrequired
Mass

Either a mass given in kilograms or tonnes (mass) or the number of Twenty-foot Equivalent Units (TEUs) (with their cargo type, optionally). Note that providing mass will result in more accurate estimates for methods other than container_ship. Estimates using container_ship are more precise when the shipment is given in TEUs.

namestring

A name to reference this calculation.

bundle_selectionarray

Bundle selection percentages.

The sum of all percentages must equal 100.

If not specified, the preconfigured allocation ratios are going to be used.

If, for each selection, percentage is not provided, the selection is divided equally (best effort) between bundles. percentage must be provided for all or none of the bundles.

object

Maps a bundle id to an allocation ratio

bundle_idstringrequired

The bundle's unique identifier

percentageoneOf
Selection percentage as integer

quantity_truncstring

Selects to which precision to truncate quantities specific to carbon offsetting.

g

kg

t

is_shipmentboolean

When true, the emission estimate refers to an actual shipment of goods, will be included in Lune analytics and can be included in any CO2 emissions reporting.

This property exists to distinguish booking quotes or forecasts from actual shipments where goods are moved.

You can mark an estimate as shipment at any time.

shipped_atstring (date-time)

The date and time of shipping the goods for the purpose of analytics (it doesn't affect emission calculations in any way).

If a value is provided when creating or updating an estimate we use the value. Otherwise defaults to the current time when creating estimates and remains unchanged when updating estimates.

This property must be formatted as RFC 3339, section 5.6 timestamp.

Examples:

2023-12-01T12:30:30.000Z
2023-12-01T12:30:30Z
2023-12-01T11:30:30+01.00

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

idempotency_keystring

Account-unique identifier provided by the client.

idempotency_key has two purposes:

Clients can safely retry estimate requests without accidentally performing the same operation multiple times.
Clients can use idempotency_key to reconcile estimates with entities on their system.

oneOf
Shipping

Sample request

Response

massobjectrequired

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, t for tonne, kg for kilogram, g for gram, mg for milligram

mg

g

kg

t

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

idempotency_keystring

Account-unique identifier provided by the client.

idempotency_key has two purposes:

Clients can safely retry estimate requests without accidentally performing the same operation multiple times.
Clients can use idempotency_key to reconcile estimates with entities on their system.

vessel_inference_detailsoneOf
Failed to infer the vessel

The method we used to infer a vessel from client provided input.

null when vessel identifier provided by client or no vessel inference not relevant to estimation.

distanceobject

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, km for kilometers, mi for miles

km

mi

nm

adjusted_distanceobject

Distance estimation after distance adjustment factors have been applied. Adjusted factors are decided by GLEC and are added to make distances more realistic.

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

km

mi

nm

distance_calculation_methodstringrequirednullable

The method we used to determine the shipping distance.

null in case of logistics sites or when resolved_legs is set.

great_circle_distance

great_circle_distance_x2

sea_distance_algorithm

mapbox

user_input

routeobjectrequirednullable

The shipping route.

null in case of logistics sites and situations where the concept of a route doesn't make sense or we're unable to return the route. That includes the following situations at the moment:

Routes where source or destination is an address (or both are).
Most land and inland waterways routes.
The actual distance value was provided by the user.
The emission estimate was created before 2023-09-22.

sourceobjectrequired

labelstringrequirednullable

coordinatesobjectrequired

latnumberrequired

Latitude

lonnumberrequired

Longitude

legsarrayrequired

object

A location and a distance from the previous location (or source, if this is the first leg).

If this is the last leg then the location is the final location (destination) of the route.

locationobjectrequired

labelstringrequirednullable

coordinatesobjectrequired

latnumberrequired

Latitude

lonnumberrequired

Longitude

distanceobjectrequired

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, km for kilometers, mi for miles

km

mi

nm

adjusted_distanceobjectrequired

Distance estimation after distance adjustment factors have been applied. Adjusted factors are decided by GLEC and are added to make distances more realistic.

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

km

mi

nm

emission_factorobjectrequired

idstringrequired

The emission factor unique identifier

namestringrequired

The emission factor name

sourcestringrequired

epa

exiobase

ecoinvent

beis

lune

source_versionstringrequired

Source version of the emission factor.

publication_yearnumberrequired

Publication year of the emission factor

numerator_unitstringrequired

Unit, t for tonne, kg for kilogram, g for gram

g

kg

t

denominator_unitoneOfrequired
Currency code

Denominator unit of the emission factor

created_atstring (date-time)required

Date of creation of the emission factor

regionstringrequired

The name of the region that the emission factor covers.

categorystringrequirednullable

A category that describes the emission factor.

gas_emissionsobjectrequirednullable

Detailed information about the gas emissions.

This property is always set as of March 2024.

co2estringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of CO₂ equivalent gas. All gas emissions are accounted here.

co2string

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of CO₂ gas.

methanestring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of methane gas.

nitrous_oxidestring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of nitrous oxide gas.

otherstring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of other greenhouse gases.

methodologyarrayrequired

Summary of the methodology used to calculate emissions or any value which is a prerequisite.

imo_unavailable_container_ship_fallback: the vessel IMO was not found, therefore a generic container ship emission factor has been used. flight_number_unavailable_fallback: the flight number could not be found or the aircraft is currently not supported, therefore a generic plane method has been used.

string

imo_unavailable_container_ship_fallback

imo_unavailable_container_ship_trade_lane_fallback

flight_number_unavailable_fallback

invalid_flight_route_fallback

distance_calculation_detailsobjectrequirednullable

Information regarding why an alternative distance calculation method was used. null in case several resolved legs are presented.

vessel_trackingoneOfrequired
Vessel tracking details

carrier_schedule_stopsobjectrequirednullable

messagestringrequired

The human-readable message describing the details of how we used or failed to use carrier schedule stops to calculate the route.

The property is meant only for informational purposes and its exact format can change.

methodology_detailsoneOfrequired
Air freight transport

converted_shipmentobjectrequirednullable

The shipment after conversion to the emission factor unit (mass to/from TEU).

null if no conversion was necessary.

amountstringrequired

unitoneOfrequired
Mass

shipment_conversion_methodstringrequirednullable

The method we used to convert the shipment to the emission factor unit.

null if no conversion was necessary.

user_provided_cargo_type

average_cargo_type

resolved_legsarrayrequirednullable

If the input shipping method results in multiple legs being detected, each leg will be calculated and shown separately.

object

massobjectrequired

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, t for tonne, kg for kilogram, g for gram, mg for milligram

mg

g

kg

t

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

idempotency_keystring

Account-unique identifier provided by the client.

idempotency_key has two purposes:

Clients can safely retry estimate requests without accidentally performing the same operation multiple times.
Clients can use idempotency_key to reconcile estimates with entities on their system.

vessel_inference_detailsoneOf
Failed to infer the vessel

The method we used to infer a vessel from client provided input.

null when vessel identifier provided by client or no vessel inference not relevant to estimation.

distanceobject

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, km for kilometers, mi for miles

km

mi

nm

adjusted_distanceobject

Distance estimation after distance adjustment factors have been applied. Adjusted factors are decided by GLEC and are added to make distances more realistic.

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

km

mi

nm

distance_calculation_methodstringrequirednullable

The method we used to determine the shipping distance.

null in case of logistics sites or when resolved_legs is set.

great_circle_distance

great_circle_distance_x2

sea_distance_algorithm

mapbox

user_input

routeobjectrequirednullable

The shipping route.

null in case of logistics sites and situations where the concept of a route doesn't make sense or we're unable to return the route. That includes the following situations at the moment:

Routes where source or destination is an address (or both are).
Most land and inland waterways routes.
The actual distance value was provided by the user.
The emission estimate was created before 2023-09-22.

sourceobjectrequired

labelstringrequirednullable

coordinatesobjectrequired

latnumberrequired

Latitude

lonnumberrequired

Longitude

legsarrayrequired

object

A location and a distance from the previous location (or source, if this is the first leg).

If this is the last leg then the location is the final location (destination) of the route.

locationobjectrequired

labelstringrequirednullable

coordinatesobjectrequired

latnumberrequired

Latitude

lonnumberrequired

Longitude

distanceobjectrequired

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, km for kilometers, mi for miles

km

mi

nm

adjusted_distanceobjectrequired

Distance estimation after distance adjustment factors have been applied. Adjusted factors are decided by GLEC and are added to make distances more realistic.

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

km

mi

nm

emission_factorobjectrequired

idstringrequired

The emission factor unique identifier

namestringrequired

The emission factor name

sourcestringrequired

epa

exiobase

ecoinvent

beis

lune

source_versionstringrequired

Source version of the emission factor.

publication_yearnumberrequired

Publication year of the emission factor

numerator_unitstringrequired

Unit, t for tonne, kg for kilogram, g for gram

g

kg

t

denominator_unitoneOfrequired
Currency code

Denominator unit of the emission factor

created_atstring (date-time)required

Date of creation of the emission factor

regionstringrequired

The name of the region that the emission factor covers.

categorystringrequirednullable

A category that describes the emission factor.

gas_emissionsobjectrequirednullable

Detailed information about the gas emissions.

This property is always set as of March 2024.

co2estringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of CO₂ equivalent gas. All gas emissions are accounted here.

co2string

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of CO₂ gas.

methanestring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of methane gas.

nitrous_oxidestring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of nitrous oxide gas.

otherstring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of other greenhouse gases.

methodologyarrayrequired

Summary of the methodology used to calculate emissions or any value which is a prerequisite.

string

imo_unavailable_container_ship_fallback

imo_unavailable_container_ship_trade_lane_fallback

flight_number_unavailable_fallback

invalid_flight_route_fallback

distance_calculation_detailsobjectrequirednullable

Information regarding why an alternative distance calculation method was used. null in case several resolved legs are presented.

vessel_trackingoneOfrequired
Vessel tracking details

carrier_schedule_stopsobjectrequirednullable

messagestringrequired

The human-readable message describing the details of how we used or failed to use carrier schedule stops to calculate the route.

The property is meant only for informational purposes and its exact format can change.

methodology_detailsoneOfrequired
Air freight transport

methodoneOfrequired
Non-parameterized other than sea

idstringrequired

The emission calculation unique identifier

is_shipmentbooleanrequired

When true, the emission estimate refers to an actual shipment of goods, will be included in Lune analytics and can be included in any CO2 emissions reporting.

This property exists to distinguish booking quotes or forecasts from actual shipments where goods are moved.

You can mark an estimate as shipment at any time.

shipped_atstring (date-time)required

The date and time of shipping the goods for the purpose of analytics (it doesn't affect emission calculations in any way).

If a value is provided when creating or updating an estimate we use the value. Otherwise defaults to the current time when creating estimates and remains unchanged when updating estimates.

This property must be formatted as RFC 3339, section 5.6 timestamp.

Examples:

2023-12-01T12:30:30.000Z
2023-12-01T12:30:30Z
2023-12-01T11:30:30+01.00

quoteoneOfrequired
Error response

requestobjectrequired

Parameters for estimating shipping emissions

shipmentoneOfrequired
Mass

namestring

A name to reference this calculation.

bundle_selectionarray

Bundle selection percentages.

The sum of all percentages must equal 100.

If not specified, the preconfigured allocation ratios are going to be used.

If, for each selection, percentage is not provided, the selection is divided equally (best effort) between bundles. percentage must be provided for all or none of the bundles.

object

Maps a bundle id to an allocation ratio

bundle_idstringrequired

The bundle's unique identifier

percentageoneOf
Selection percentage as integer

quantity_truncstring

Selects to which precision to truncate quantities specific to carbon offsetting.

g

kg

t

is_shipmentboolean

When true, the emission estimate refers to an actual shipment of goods, will be included in Lune analytics and can be included in any CO2 emissions reporting.

This property exists to distinguish booking quotes or forecasts from actual shipments where goods are moved.

You can mark an estimate as shipment at any time.

shipped_atstring (date-time)

The date and time of shipping the goods for the purpose of analytics (it doesn't affect emission calculations in any way).

If a value is provided when creating or updating an estimate we use the value. Otherwise defaults to the current time when creating estimates and remains unchanged when updating estimates.

This property must be formatted as RFC 3339, section 5.6 timestamp.

Examples:

2023-12-01T12:30:30.000Z
2023-12-01T12:30:30Z
2023-12-01T11:30:30+01.00

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

idempotency_keystring

Account-unique identifier provided by the client.

idempotency_key has two purposes:

Clients can safely retry estimate requests without accidentally performing the same operation multiple times.
Clients can use idempotency_key to reconcile estimates with entities on their system.

oneOf
Shipping

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

external_estimate_urlstring (https-url)requirednullable

An external accessible URL linking to a detailed page that provides complete information about the estimate.

sourcestring

Identifies the source used to create the estimate.

api

dashboard

csv

chain_io

ecotransit_csv

Sample response

Errors

This API operation can return the following errors:

HTTP status codeError code

400

api_version_invalid

400

bundle_selection_ratios_invalid

400

bundle_selection_bundle_invalid

400

order_value_invalid

400

bundle_id_invalid

400

id_invalid

400

distance_invalid

400

test_account_name_update_disallowed

400

bundle_selection_ratios_invalid_format

400

address_not_found

List all shipping estimates

HTTP GET to /v1/estimates/shipping/all

Sample request

Returns single and multi-leg shipping estimates paginated in reverse order.

Query parameters

limitstring

Pattern: ^\d+$

Maximum number of resources to return, between 1 and 100.

afterstring

A cursor for use in pagination.

The cursor that points to the starting item of the next page of results. If not provided, the first page of results is returned.

is_shipmentstring

When true, the emission estimate refers to an actual shipment of goods.

This property exists to distinguish booking quotes or forecasts from actual shipments where goods are moved.

By default, all estimates are returned.

fromstring (date-time)

When set, the result includes estimates created at or after the timestamp.

Both from and through are either provided or missing.

throughstring (date-time)

When set, the result includes estimates created at or before the timestamp.

Both from and through are either provided or missing.

estimate_mass_unitstring

By default estimate mass units are returned in tonnes.

Estimate mass units in responses are converted to estimate_mass_unit when set.

mg

g

kg

t

Response

has_morebooleanrequired

Whether or not there are more elements available after this set.

If false, this set comprises the end of the array.

Part of a paginated response.

next_cursorstringrequirednullable

The cursor value to be used as the after parameter for fetching the next page of results.

null if has_more is false.

dataarrayrequired

Paginated single and multi-leg shipping emission estimates

oneOf
Single-leg shipping estimate

Errors

This API operation can return the following errors:

HTTP status codeError code

400

api_version_invalid

400

bundle_selection_ratios_invalid

400

bundle_selection_bundle_invalid

400

order_value_invalid

400

bundle_id_invalid

400

id_invalid

400

distance_invalid

400

test_account_name_update_disallowed

400

bundle_selection_ratios_invalid_format

400

address_not_found

Get a shipping emission estimate (single)

HTTP GET to /v1/estimates/shipping/{id}

Sample request

Query parameters

idstringrequired

The estimate's unique identifier

estimate_mass_unitstring

By default estimate mass units are returned in tonnes.

Estimate mass units in responses are converted to estimate_mass_unit when set.

mg

g

kg

t

Response

massobjectrequired

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, t for tonne, kg for kilogram, g for gram, mg for milligram

mg

g

kg

t

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

idempotency_keystring

Account-unique identifier provided by the client.

idempotency_key has two purposes:

Clients can safely retry estimate requests without accidentally performing the same operation multiple times.
Clients can use idempotency_key to reconcile estimates with entities on their system.

vessel_inference_detailsoneOf
Failed to infer the vessel

The method we used to infer a vessel from client provided input.

null when vessel identifier provided by client or no vessel inference not relevant to estimation.

distanceobject

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, km for kilometers, mi for miles

km

mi

nm

adjusted_distanceobject

Distance estimation after distance adjustment factors have been applied. Adjusted factors are decided by GLEC and are added to make distances more realistic.

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

km

mi

nm

distance_calculation_methodstringrequirednullable

The method we used to determine the shipping distance.

null in case of logistics sites or when resolved_legs is set.

great_circle_distance

great_circle_distance_x2

sea_distance_algorithm

mapbox

user_input

routeobjectrequirednullable

The shipping route.

null in case of logistics sites and situations where the concept of a route doesn't make sense or we're unable to return the route. That includes the following situations at the moment:

Routes where source or destination is an address (or both are).
Most land and inland waterways routes.
The actual distance value was provided by the user.
The emission estimate was created before 2023-09-22.

sourceobjectrequired

labelstringrequirednullable

coordinatesobjectrequired

latnumberrequired

Latitude

lonnumberrequired

Longitude

legsarrayrequired

object

A location and a distance from the previous location (or source, if this is the first leg).

If this is the last leg then the location is the final location (destination) of the route.

locationobjectrequired

labelstringrequirednullable

coordinatesobjectrequired

latnumberrequired

Latitude

lonnumberrequired

Longitude

distanceobjectrequired

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, km for kilometers, mi for miles

km

mi

nm

adjusted_distanceobjectrequired

Distance estimation after distance adjustment factors have been applied. Adjusted factors are decided by GLEC and are added to make distances more realistic.

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

km

mi

nm

emission_factorobjectrequired

idstringrequired

The emission factor unique identifier

namestringrequired

The emission factor name

sourcestringrequired

epa

exiobase

ecoinvent

beis

lune

source_versionstringrequired

Source version of the emission factor.

publication_yearnumberrequired

Publication year of the emission factor

numerator_unitstringrequired

Unit, t for tonne, kg for kilogram, g for gram

g

kg

t

denominator_unitoneOfrequired
Currency code

Denominator unit of the emission factor

created_atstring (date-time)required

Date of creation of the emission factor

regionstringrequired

The name of the region that the emission factor covers.

categorystringrequirednullable

A category that describes the emission factor.

gas_emissionsobjectrequirednullable

Detailed information about the gas emissions.

This property is always set as of March 2024.

co2estringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of CO₂ equivalent gas. All gas emissions are accounted here.

co2string

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of CO₂ gas.

methanestring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of methane gas.

nitrous_oxidestring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of nitrous oxide gas.

otherstring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of other greenhouse gases.

methodologyarrayrequired

Summary of the methodology used to calculate emissions or any value which is a prerequisite.

string

imo_unavailable_container_ship_fallback

imo_unavailable_container_ship_trade_lane_fallback

flight_number_unavailable_fallback

invalid_flight_route_fallback

distance_calculation_detailsobjectrequirednullable

Information regarding why an alternative distance calculation method was used. null in case several resolved legs are presented.

vessel_trackingoneOfrequired
Vessel tracking details

carrier_schedule_stopsobjectrequirednullable

messagestringrequired

The human-readable message describing the details of how we used or failed to use carrier schedule stops to calculate the route.

The property is meant only for informational purposes and its exact format can change.

methodology_detailsoneOfrequired
Air freight transport

converted_shipmentobjectrequirednullable

The shipment after conversion to the emission factor unit (mass to/from TEU).

null if no conversion was necessary.

amountstringrequired

unitoneOfrequired
Mass

shipment_conversion_methodstringrequirednullable

The method we used to convert the shipment to the emission factor unit.

null if no conversion was necessary.

user_provided_cargo_type

average_cargo_type

resolved_legsarrayrequirednullable

If the input shipping method results in multiple legs being detected, each leg will be calculated and shown separately.

object

massobjectrequired

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, t for tonne, kg for kilogram, g for gram, mg for milligram

mg

g

kg

t

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

idempotency_keystring

Account-unique identifier provided by the client.

idempotency_key has two purposes:

Clients can safely retry estimate requests without accidentally performing the same operation multiple times.
Clients can use idempotency_key to reconcile estimates with entities on their system.

vessel_inference_detailsoneOf
Failed to infer the vessel

The method we used to infer a vessel from client provided input.

null when vessel identifier provided by client or no vessel inference not relevant to estimation.

distanceobject

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, km for kilometers, mi for miles

km

mi

nm

adjusted_distanceobject

Distance estimation after distance adjustment factors have been applied. Adjusted factors are decided by GLEC and are added to make distances more realistic.

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

km

mi

nm

distance_calculation_methodstringrequirednullable

The method we used to determine the shipping distance.

null in case of logistics sites or when resolved_legs is set.

great_circle_distance

great_circle_distance_x2

sea_distance_algorithm

mapbox

user_input

routeobjectrequirednullable

The shipping route.

null in case of logistics sites and situations where the concept of a route doesn't make sense or we're unable to return the route. That includes the following situations at the moment:

Routes where source or destination is an address (or both are).
Most land and inland waterways routes.
The actual distance value was provided by the user.
The emission estimate was created before 2023-09-22.

sourceobjectrequired

labelstringrequirednullable

coordinatesobjectrequired

latnumberrequired

Latitude

lonnumberrequired

Longitude

legsarrayrequired

object

A location and a distance from the previous location (or source, if this is the first leg).

If this is the last leg then the location is the final location (destination) of the route.

locationobjectrequired

labelstringrequirednullable

coordinatesobjectrequired

latnumberrequired

Latitude

lonnumberrequired

Longitude

distanceobjectrequired

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, km for kilometers, mi for miles

km

mi

nm

adjusted_distanceobjectrequired

Distance estimation after distance adjustment factors have been applied. Adjusted factors are decided by GLEC and are added to make distances more realistic.

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

km

mi

nm

emission_factorobjectrequired

idstringrequired

The emission factor unique identifier

namestringrequired

The emission factor name

sourcestringrequired

epa

exiobase

ecoinvent

beis

lune

source_versionstringrequired

Source version of the emission factor.

publication_yearnumberrequired

Publication year of the emission factor

numerator_unitstringrequired

Unit, t for tonne, kg for kilogram, g for gram

g

kg

t

denominator_unitoneOfrequired
Currency code

Denominator unit of the emission factor

created_atstring (date-time)required

Date of creation of the emission factor

regionstringrequired

The name of the region that the emission factor covers.

categorystringrequirednullable

A category that describes the emission factor.

gas_emissionsobjectrequirednullable

Detailed information about the gas emissions.

This property is always set as of March 2024.

co2estringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of CO₂ equivalent gas. All gas emissions are accounted here.

co2string

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of CO₂ gas.

methanestring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of methane gas.

nitrous_oxidestring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of nitrous oxide gas.

otherstring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of other greenhouse gases.

methodologyarrayrequired

Summary of the methodology used to calculate emissions or any value which is a prerequisite.

string

imo_unavailable_container_ship_fallback

imo_unavailable_container_ship_trade_lane_fallback

flight_number_unavailable_fallback

invalid_flight_route_fallback

distance_calculation_detailsobjectrequirednullable

Information regarding why an alternative distance calculation method was used. null in case several resolved legs are presented.

vessel_trackingoneOfrequired
Vessel tracking details

carrier_schedule_stopsobjectrequirednullable

messagestringrequired

The human-readable message describing the details of how we used or failed to use carrier schedule stops to calculate the route.

The property is meant only for informational purposes and its exact format can change.

methodology_detailsoneOfrequired
Air freight transport

methodoneOfrequired
Non-parameterized other than sea

idstringrequired

The emission calculation unique identifier

is_shipmentbooleanrequired

When true, the emission estimate refers to an actual shipment of goods, will be included in Lune analytics and can be included in any CO2 emissions reporting.

This property exists to distinguish booking quotes or forecasts from actual shipments where goods are moved.

You can mark an estimate as shipment at any time.

shipped_atstring (date-time)required

The date and time of shipping the goods for the purpose of analytics (it doesn't affect emission calculations in any way).

If a value is provided when creating or updating an estimate we use the value. Otherwise defaults to the current time when creating estimates and remains unchanged when updating estimates.

This property must be formatted as RFC 3339, section 5.6 timestamp.

Examples:

2023-12-01T12:30:30.000Z
2023-12-01T12:30:30Z
2023-12-01T11:30:30+01.00

quoteoneOfrequired
Error response

requestobjectrequired

Parameters for estimating shipping emissions

shipmentoneOfrequired
Mass

namestring

A name to reference this calculation.

bundle_selectionarray

Bundle selection percentages.

The sum of all percentages must equal 100.

If not specified, the preconfigured allocation ratios are going to be used.

If, for each selection, percentage is not provided, the selection is divided equally (best effort) between bundles. percentage must be provided for all or none of the bundles.

object

Maps a bundle id to an allocation ratio

bundle_idstringrequired

The bundle's unique identifier

percentageoneOf
Selection percentage as integer

quantity_truncstring

Selects to which precision to truncate quantities specific to carbon offsetting.

g

kg

t

is_shipmentboolean

When true, the emission estimate refers to an actual shipment of goods, will be included in Lune analytics and can be included in any CO2 emissions reporting.

This property exists to distinguish booking quotes or forecasts from actual shipments where goods are moved.

You can mark an estimate as shipment at any time.

shipped_atstring (date-time)

The date and time of shipping the goods for the purpose of analytics (it doesn't affect emission calculations in any way).

If a value is provided when creating or updating an estimate we use the value. Otherwise defaults to the current time when creating estimates and remains unchanged when updating estimates.

This property must be formatted as RFC 3339, section 5.6 timestamp.

Examples:

2023-12-01T12:30:30.000Z
2023-12-01T12:30:30Z
2023-12-01T11:30:30+01.00

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

idempotency_keystring

Account-unique identifier provided by the client.

idempotency_key has two purposes:

Clients can safely retry estimate requests without accidentally performing the same operation multiple times.
Clients can use idempotency_key to reconcile estimates with entities on their system.

oneOf
Shipping

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

external_estimate_urlstring (https-url)requirednullable

An external accessible URL linking to a detailed page that provides complete information about the estimate.

sourcestring

Identifies the source used to create the estimate.

api

dashboard

csv

chain_io

ecotransit_csv

Sample response

Errors

This API operation can return the following errors:

HTTP status codeError code

401

404

429

503

service_unavailable

Update a shipping emission estimate (single)

HTTP PUT to /v1/estimates/shipping/{id}

Query parameters

idstringrequired

The estimate's unique identifier

estimate_mass_unitstring

By default estimate mass units are returned in tonnes.

Estimate mass units in responses are converted to estimate_mass_unit when set.

mg

g

kg

t

Request body

Parameters for estimating shipping emissions

shipmentoneOfrequired
Mass

namestring

A name to reference this calculation.

bundle_selectionarray

Bundle selection percentages.

The sum of all percentages must equal 100.

If not specified, the preconfigured allocation ratios are going to be used.

If, for each selection, percentage is not provided, the selection is divided equally (best effort) between bundles. percentage must be provided for all or none of the bundles.

object

Maps a bundle id to an allocation ratio

bundle_idstringrequired

The bundle's unique identifier

percentageoneOf
Selection percentage as integer

quantity_truncstring

Selects to which precision to truncate quantities specific to carbon offsetting.

g

kg

t

is_shipmentboolean

When true, the emission estimate refers to an actual shipment of goods, will be included in Lune analytics and can be included in any CO2 emissions reporting.

This property exists to distinguish booking quotes or forecasts from actual shipments where goods are moved.

You can mark an estimate as shipment at any time.

shipped_atstring (date-time)

The date and time of shipping the goods for the purpose of analytics (it doesn't affect emission calculations in any way).

If a value is provided when creating or updating an estimate we use the value. Otherwise defaults to the current time when creating estimates and remains unchanged when updating estimates.

This property must be formatted as RFC 3339, section 5.6 timestamp.

Examples:

2023-12-01T12:30:30.000Z
2023-12-01T12:30:30Z
2023-12-01T11:30:30+01.00

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

idempotency_keystring

Account-unique identifier provided by the client.

idempotency_key has two purposes:

Clients can safely retry estimate requests without accidentally performing the same operation multiple times.
Clients can use idempotency_key to reconcile estimates with entities on their system.

oneOf
Shipping

Sample request

Response

massobjectrequired

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, t for tonne, kg for kilogram, g for gram, mg for milligram

mg

g

kg

t

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

idempotency_keystring

Account-unique identifier provided by the client.

idempotency_key has two purposes:

Clients can safely retry estimate requests without accidentally performing the same operation multiple times.
Clients can use idempotency_key to reconcile estimates with entities on their system.

vessel_inference_detailsoneOf
Failed to infer the vessel

The method we used to infer a vessel from client provided input.

null when vessel identifier provided by client or no vessel inference not relevant to estimation.

distanceobject

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, km for kilometers, mi for miles

km

mi

nm

adjusted_distanceobject

Distance estimation after distance adjustment factors have been applied. Adjusted factors are decided by GLEC and are added to make distances more realistic.

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

km

mi

nm

distance_calculation_methodstringrequirednullable

The method we used to determine the shipping distance.

null in case of logistics sites or when resolved_legs is set.

great_circle_distance

great_circle_distance_x2

sea_distance_algorithm

mapbox

user_input

routeobjectrequirednullable

The shipping route.

null in case of logistics sites and situations where the concept of a route doesn't make sense or we're unable to return the route. That includes the following situations at the moment:

Routes where source or destination is an address (or both are).
Most land and inland waterways routes.
The actual distance value was provided by the user.
The emission estimate was created before 2023-09-22.

sourceobjectrequired

labelstringrequirednullable

coordinatesobjectrequired

latnumberrequired

Latitude

lonnumberrequired

Longitude

legsarrayrequired

object

A location and a distance from the previous location (or source, if this is the first leg).

If this is the last leg then the location is the final location (destination) of the route.

locationobjectrequired

labelstringrequirednullable

coordinatesobjectrequired

latnumberrequired

Latitude

lonnumberrequired

Longitude

distanceobjectrequired

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, km for kilometers, mi for miles

km

mi

nm

adjusted_distanceobjectrequired

Distance estimation after distance adjustment factors have been applied. Adjusted factors are decided by GLEC and are added to make distances more realistic.

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

km

mi

nm

emission_factorobjectrequired

idstringrequired

The emission factor unique identifier

namestringrequired

The emission factor name

sourcestringrequired

epa

exiobase

ecoinvent

beis

lune

source_versionstringrequired

Source version of the emission factor.

publication_yearnumberrequired

Publication year of the emission factor

numerator_unitstringrequired

Unit, t for tonne, kg for kilogram, g for gram

g

kg

t

denominator_unitoneOfrequired
Currency code

Denominator unit of the emission factor

created_atstring (date-time)required

Date of creation of the emission factor

regionstringrequired

The name of the region that the emission factor covers.

categorystringrequirednullable

A category that describes the emission factor.

gas_emissionsobjectrequirednullable

Detailed information about the gas emissions.

This property is always set as of March 2024.

co2estringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of CO₂ equivalent gas. All gas emissions are accounted here.

co2string

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of CO₂ gas.

methanestring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of methane gas.

nitrous_oxidestring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of nitrous oxide gas.

otherstring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of other greenhouse gases.

methodologyarrayrequired

Summary of the methodology used to calculate emissions or any value which is a prerequisite.

string

imo_unavailable_container_ship_fallback

imo_unavailable_container_ship_trade_lane_fallback

flight_number_unavailable_fallback

invalid_flight_route_fallback

distance_calculation_detailsobjectrequirednullable

Information regarding why an alternative distance calculation method was used. null in case several resolved legs are presented.

vessel_trackingoneOfrequired
Vessel tracking details

carrier_schedule_stopsobjectrequirednullable

messagestringrequired

The human-readable message describing the details of how we used or failed to use carrier schedule stops to calculate the route.

The property is meant only for informational purposes and its exact format can change.

methodology_detailsoneOfrequired
Air freight transport

converted_shipmentobjectrequirednullable

The shipment after conversion to the emission factor unit (mass to/from TEU).

null if no conversion was necessary.

amountstringrequired

unitoneOfrequired
Mass

shipment_conversion_methodstringrequirednullable

The method we used to convert the shipment to the emission factor unit.

null if no conversion was necessary.

user_provided_cargo_type

average_cargo_type

resolved_legsarrayrequirednullable

If the input shipping method results in multiple legs being detected, each leg will be calculated and shown separately.

object

massobjectrequired

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, t for tonne, kg for kilogram, g for gram, mg for milligram

mg

g

kg

t

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

idempotency_keystring

Account-unique identifier provided by the client.

idempotency_key has two purposes:

Clients can safely retry estimate requests without accidentally performing the same operation multiple times.
Clients can use idempotency_key to reconcile estimates with entities on their system.

vessel_inference_detailsoneOf
Failed to infer the vessel

The method we used to infer a vessel from client provided input.

null when vessel identifier provided by client or no vessel inference not relevant to estimation.

distanceobject

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, km for kilometers, mi for miles

km

mi

nm

adjusted_distanceobject

Distance estimation after distance adjustment factors have been applied. Adjusted factors are decided by GLEC and are added to make distances more realistic.

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

km

mi

nm

distance_calculation_methodstringrequirednullable

The method we used to determine the shipping distance.

null in case of logistics sites or when resolved_legs is set.

great_circle_distance

great_circle_distance_x2

sea_distance_algorithm

mapbox

user_input

routeobjectrequirednullable

The shipping route.

null in case of logistics sites and situations where the concept of a route doesn't make sense or we're unable to return the route. That includes the following situations at the moment:

Routes where source or destination is an address (or both are).
Most land and inland waterways routes.
The actual distance value was provided by the user.
The emission estimate was created before 2023-09-22.

sourceobjectrequired

labelstringrequirednullable

coordinatesobjectrequired

latnumberrequired

Latitude

lonnumberrequired

Longitude

legsarrayrequired

object

A location and a distance from the previous location (or source, if this is the first leg).

If this is the last leg then the location is the final location (destination) of the route.

locationobjectrequired

labelstringrequirednullable

coordinatesobjectrequired

latnumberrequired

Latitude

lonnumberrequired

Longitude

distanceobjectrequired

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, km for kilometers, mi for miles

km

mi

nm

adjusted_distanceobjectrequired

Distance estimation after distance adjustment factors have been applied. Adjusted factors are decided by GLEC and are added to make distances more realistic.

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

km

mi

nm

emission_factorobjectrequired

idstringrequired

The emission factor unique identifier

namestringrequired

The emission factor name

sourcestringrequired

epa

exiobase

ecoinvent

beis

lune

source_versionstringrequired

Source version of the emission factor.

publication_yearnumberrequired

Publication year of the emission factor

numerator_unitstringrequired

Unit, t for tonne, kg for kilogram, g for gram

g

kg

t

denominator_unitoneOfrequired
Currency code

Denominator unit of the emission factor

created_atstring (date-time)required

Date of creation of the emission factor

regionstringrequired

The name of the region that the emission factor covers.

categorystringrequirednullable

A category that describes the emission factor.

gas_emissionsobjectrequirednullable

Detailed information about the gas emissions.

This property is always set as of March 2024.

co2estringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of CO₂ equivalent gas. All gas emissions are accounted here.

co2string

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of CO₂ gas.

methanestring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of methane gas.

nitrous_oxidestring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of nitrous oxide gas.

otherstring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of other greenhouse gases.

methodologyarrayrequired

Summary of the methodology used to calculate emissions or any value which is a prerequisite.

string

imo_unavailable_container_ship_fallback

imo_unavailable_container_ship_trade_lane_fallback

flight_number_unavailable_fallback

invalid_flight_route_fallback

distance_calculation_detailsobjectrequirednullable

Information regarding why an alternative distance calculation method was used. null in case several resolved legs are presented.

vessel_trackingoneOfrequired
Vessel tracking details

carrier_schedule_stopsobjectrequirednullable

messagestringrequired

The human-readable message describing the details of how we used or failed to use carrier schedule stops to calculate the route.

The property is meant only for informational purposes and its exact format can change.

methodology_detailsoneOfrequired
Air freight transport

methodoneOfrequired
Non-parameterized other than sea

idstringrequired

The emission calculation unique identifier

is_shipmentbooleanrequired

When true, the emission estimate refers to an actual shipment of goods, will be included in Lune analytics and can be included in any CO2 emissions reporting.

This property exists to distinguish booking quotes or forecasts from actual shipments where goods are moved.

You can mark an estimate as shipment at any time.

shipped_atstring (date-time)required

The date and time of shipping the goods for the purpose of analytics (it doesn't affect emission calculations in any way).

If a value is provided when creating or updating an estimate we use the value. Otherwise defaults to the current time when creating estimates and remains unchanged when updating estimates.

This property must be formatted as RFC 3339, section 5.6 timestamp.

Examples:

2023-12-01T12:30:30.000Z
2023-12-01T12:30:30Z
2023-12-01T11:30:30+01.00

quoteoneOfrequired
Error response

requestobjectrequired

Parameters for estimating shipping emissions

shipmentoneOfrequired
Mass

namestring

A name to reference this calculation.

bundle_selectionarray

Bundle selection percentages.

The sum of all percentages must equal 100.

If not specified, the preconfigured allocation ratios are going to be used.

If, for each selection, percentage is not provided, the selection is divided equally (best effort) between bundles. percentage must be provided for all or none of the bundles.

object

Maps a bundle id to an allocation ratio

bundle_idstringrequired

The bundle's unique identifier

percentageoneOf
Selection percentage as integer

quantity_truncstring

Selects to which precision to truncate quantities specific to carbon offsetting.

g

kg

t

is_shipmentboolean

When true, the emission estimate refers to an actual shipment of goods, will be included in Lune analytics and can be included in any CO2 emissions reporting.

This property exists to distinguish booking quotes or forecasts from actual shipments where goods are moved.

You can mark an estimate as shipment at any time.

shipped_atstring (date-time)

The date and time of shipping the goods for the purpose of analytics (it doesn't affect emission calculations in any way).

If a value is provided when creating or updating an estimate we use the value. Otherwise defaults to the current time when creating estimates and remains unchanged when updating estimates.

This property must be formatted as RFC 3339, section 5.6 timestamp.

Examples:

2023-12-01T12:30:30.000Z
2023-12-01T12:30:30Z
2023-12-01T11:30:30+01.00

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

idempotency_keystring

Account-unique identifier provided by the client.

idempotency_key has two purposes:

Clients can safely retry estimate requests without accidentally performing the same operation multiple times.
Clients can use idempotency_key to reconcile estimates with entities on their system.

oneOf
Shipping

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

external_estimate_urlstring (https-url)requirednullable

An external accessible URL linking to a detailed page that provides complete information about the estimate.

sourcestring

Identifies the source used to create the estimate.

api

dashboard

csv

chain_io

ecotransit_csv

Sample response

Errors

This API operation can return the following errors:

HTTP status codeError code

400

api_version_invalid

400

bundle_selection_ratios_invalid

400

bundle_selection_bundle_invalid

400

order_value_invalid

400

bundle_id_invalid

400

id_invalid

400

distance_invalid

400

test_account_name_update_disallowed

400

bundle_selection_ratios_invalid_format

400

address_not_found

Update a shipping emission estimate's annotations

HTTP PATCH to /v1/estimates/shipping/{id}/annotationsThis method allows updating a selection of estimate annotations without going through a full estimate update (with all the necessary inputs).Only properties included in the input data are updated.

Query parameters

idstringrequired

The estimate's unique identifier

Request body

oneOf
`is_shipment` with optional `shipped_at`, `metadata` and `idempotency_key`

Sample request

Response

massobjectrequired

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, t for tonne, kg for kilogram, g for gram, mg for milligram

mg

g

kg

t

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

idempotency_keystring

Account-unique identifier provided by the client.

idempotency_key has two purposes:

Clients can safely retry estimate requests without accidentally performing the same operation multiple times.
Clients can use idempotency_key to reconcile estimates with entities on their system.

vessel_inference_detailsoneOf
Failed to infer the vessel

The method we used to infer a vessel from client provided input.

null when vessel identifier provided by client or no vessel inference not relevant to estimation.

distanceobject

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, km for kilometers, mi for miles

km

mi

nm

adjusted_distanceobject

Distance estimation after distance adjustment factors have been applied. Adjusted factors are decided by GLEC and are added to make distances more realistic.

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

km

mi

nm

distance_calculation_methodstringrequirednullable

The method we used to determine the shipping distance.

null in case of logistics sites or when resolved_legs is set.

great_circle_distance

great_circle_distance_x2

sea_distance_algorithm

mapbox

user_input

routeobjectrequirednullable

The shipping route.

null in case of logistics sites and situations where the concept of a route doesn't make sense or we're unable to return the route. That includes the following situations at the moment:

Routes where source or destination is an address (or both are).
Most land and inland waterways routes.
The actual distance value was provided by the user.
The emission estimate was created before 2023-09-22.

sourceobjectrequired

labelstringrequirednullable

coordinatesobjectrequired

latnumberrequired

Latitude

lonnumberrequired

Longitude

legsarrayrequired

object

A location and a distance from the previous location (or source, if this is the first leg).

If this is the last leg then the location is the final location (destination) of the route.

locationobjectrequired

labelstringrequirednullable

coordinatesobjectrequired

latnumberrequired

Latitude

lonnumberrequired

Longitude

distanceobjectrequired

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, km for kilometers, mi for miles

km

mi

nm

adjusted_distanceobjectrequired

Distance estimation after distance adjustment factors have been applied. Adjusted factors are decided by GLEC and are added to make distances more realistic.

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

km

mi

nm

emission_factorobjectrequired

idstringrequired

The emission factor unique identifier

namestringrequired

The emission factor name

sourcestringrequired

epa

exiobase

ecoinvent

beis

lune

source_versionstringrequired

Source version of the emission factor.

publication_yearnumberrequired

Publication year of the emission factor

numerator_unitstringrequired

Unit, t for tonne, kg for kilogram, g for gram

g

kg

t

denominator_unitoneOfrequired
Currency code

Denominator unit of the emission factor

created_atstring (date-time)required

Date of creation of the emission factor

regionstringrequired

The name of the region that the emission factor covers.

categorystringrequirednullable

A category that describes the emission factor.

gas_emissionsobjectrequirednullable

Detailed information about the gas emissions.

This property is always set as of March 2024.

co2estringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of CO₂ equivalent gas. All gas emissions are accounted here.

co2string

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of CO₂ gas.

methanestring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of methane gas.

nitrous_oxidestring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of nitrous oxide gas.

otherstring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of other greenhouse gases.

methodologyarrayrequired

Summary of the methodology used to calculate emissions or any value which is a prerequisite.

string

imo_unavailable_container_ship_fallback

imo_unavailable_container_ship_trade_lane_fallback

flight_number_unavailable_fallback

invalid_flight_route_fallback

distance_calculation_detailsobjectrequirednullable

Information regarding why an alternative distance calculation method was used. null in case several resolved legs are presented.

vessel_trackingoneOfrequired
Vessel tracking details

carrier_schedule_stopsobjectrequirednullable

messagestringrequired

The human-readable message describing the details of how we used or failed to use carrier schedule stops to calculate the route.

The property is meant only for informational purposes and its exact format can change.

methodology_detailsoneOfrequired
Air freight transport

converted_shipmentobjectrequirednullable

The shipment after conversion to the emission factor unit (mass to/from TEU).

null if no conversion was necessary.

amountstringrequired

unitoneOfrequired
Mass

shipment_conversion_methodstringrequirednullable

The method we used to convert the shipment to the emission factor unit.

null if no conversion was necessary.

user_provided_cargo_type

average_cargo_type

resolved_legsarrayrequirednullable

If the input shipping method results in multiple legs being detected, each leg will be calculated and shown separately.

object

massobjectrequired

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, t for tonne, kg for kilogram, g for gram, mg for milligram

mg

g

kg

t

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

idempotency_keystring

Account-unique identifier provided by the client.

idempotency_key has two purposes:

Clients can safely retry estimate requests without accidentally performing the same operation multiple times.
Clients can use idempotency_key to reconcile estimates with entities on their system.

vessel_inference_detailsoneOf
Failed to infer the vessel

The method we used to infer a vessel from client provided input.

null when vessel identifier provided by client or no vessel inference not relevant to estimation.

distanceobject

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, km for kilometers, mi for miles

km

mi

nm

adjusted_distanceobject

Distance estimation after distance adjustment factors have been applied. Adjusted factors are decided by GLEC and are added to make distances more realistic.

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

km

mi

nm

distance_calculation_methodstringrequirednullable

The method we used to determine the shipping distance.

null in case of logistics sites or when resolved_legs is set.

great_circle_distance

great_circle_distance_x2

sea_distance_algorithm

mapbox

user_input

routeobjectrequirednullable

The shipping route.

null in case of logistics sites and situations where the concept of a route doesn't make sense or we're unable to return the route. That includes the following situations at the moment:

Routes where source or destination is an address (or both are).
Most land and inland waterways routes.
The actual distance value was provided by the user.
The emission estimate was created before 2023-09-22.

sourceobjectrequired

labelstringrequirednullable

coordinatesobjectrequired

latnumberrequired

Latitude

lonnumberrequired

Longitude

legsarrayrequired

object

A location and a distance from the previous location (or source, if this is the first leg).

If this is the last leg then the location is the final location (destination) of the route.

locationobjectrequired

labelstringrequirednullable

coordinatesobjectrequired

latnumberrequired

Latitude

lonnumberrequired

Longitude

distanceobjectrequired

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

Unit, km for kilometers, mi for miles

km

mi

nm

adjusted_distanceobjectrequired

Distance estimation after distance adjustment factors have been applied. Adjusted factors are decided by GLEC and are added to make distances more realistic.

amountstringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

unitstringrequired

km

mi

nm

emission_factorobjectrequired

idstringrequired

The emission factor unique identifier

namestringrequired

The emission factor name

sourcestringrequired

epa

exiobase

ecoinvent

beis

lune

source_versionstringrequired

Source version of the emission factor.

publication_yearnumberrequired

Publication year of the emission factor

numerator_unitstringrequired

Unit, t for tonne, kg for kilogram, g for gram

g

kg

t

denominator_unitoneOfrequired
Currency code

Denominator unit of the emission factor

created_atstring (date-time)required

Date of creation of the emission factor

regionstringrequired

The name of the region that the emission factor covers.

categorystringrequirednullable

A category that describes the emission factor.

gas_emissionsobjectrequirednullable

Detailed information about the gas emissions.

This property is always set as of March 2024.

co2estringrequired

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of CO₂ equivalent gas. All gas emissions are accounted here.

co2string

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of CO₂ gas.

methanestring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of methane gas.

nitrous_oxidestring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of nitrous oxide gas.

otherstring

Pattern: ^[0-9]+(\.[0-9]+)?$

Amount of other greenhouse gases.

methodologyarrayrequired

Summary of the methodology used to calculate emissions or any value which is a prerequisite.

string

imo_unavailable_container_ship_fallback

imo_unavailable_container_ship_trade_lane_fallback

flight_number_unavailable_fallback

invalid_flight_route_fallback

distance_calculation_detailsobjectrequirednullable

Information regarding why an alternative distance calculation method was used. null in case several resolved legs are presented.

vessel_trackingoneOfrequired
Vessel tracking details

carrier_schedule_stopsobjectrequirednullable

messagestringrequired

The human-readable message describing the details of how we used or failed to use carrier schedule stops to calculate the route.

The property is meant only for informational purposes and its exact format can change.

methodology_detailsoneOfrequired
Air freight transport

methodoneOfrequired
Non-parameterized other than sea

idstringrequired

The emission calculation unique identifier

is_shipmentbooleanrequired

When true, the emission estimate refers to an actual shipment of goods, will be included in Lune analytics and can be included in any CO2 emissions reporting.

This property exists to distinguish booking quotes or forecasts from actual shipments where goods are moved.

You can mark an estimate as shipment at any time.

shipped_atstring (date-time)required

The date and time of shipping the goods for the purpose of analytics (it doesn't affect emission calculations in any way).

If a value is provided when creating or updating an estimate we use the value. Otherwise defaults to the current time when creating estimates and remains unchanged when updating estimates.

This property must be formatted as RFC 3339, section 5.6 timestamp.

Examples:

2023-12-01T12:30:30.000Z
2023-12-01T12:30:30Z
2023-12-01T11:30:30+01.00

quoteoneOfrequired
Error response

requestobjectrequired

Parameters for estimating shipping emissions

shipmentoneOfrequired
Mass

namestring

A name to reference this calculation.

bundle_selectionarray

Bundle selection percentages.

The sum of all percentages must equal 100.

If not specified, the preconfigured allocation ratios are going to be used.

If, for each selection, percentage is not provided, the selection is divided equally (best effort) between bundles. percentage must be provided for all or none of the bundles.

object

Maps a bundle id to an allocation ratio

bundle_idstringrequired

The bundle's unique identifier

percentageoneOf
Selection percentage as integer

quantity_truncstring

Selects to which precision to truncate quantities specific to carbon offsetting.

g

kg

t

is_shipmentboolean

When true, the emission estimate refers to an actual shipment of goods, will be included in Lune analytics and can be included in any CO2 emissions reporting.

This property exists to distinguish booking quotes or forecasts from actual shipments where goods are moved.

You can mark an estimate as shipment at any time.

shipped_atstring (date-time)

The date and time of shipping the goods for the purpose of analytics (it doesn't affect emission calculations in any way).

If a value is provided when creating or updating an estimate we use the value. Otherwise defaults to the current time when creating estimates and remains unchanged when updating estimates.

This property must be formatted as RFC 3339, section 5.6 timestamp.

Examples:

2023-12-01T12:30:30.000Z
2023-12-01T12:30:30Z
2023-12-01T11:30:30+01.00

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

idempotency_keystring

Account-unique identifier provided by the client.

idempotency_key has two purposes:

Clients can safely retry estimate requests without accidentally performing the same operation multiple times.
Clients can use idempotency_key to reconcile estimates with entities on their system.

oneOf
Shipping

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

external_estimate_urlstring (https-url)requirednullable

An external accessible URL linking to a detailed page that provides complete information about the estimate.

sourcestring

Identifies the source used to create the estimate.

api

dashboard

csv

chain_io

ecotransit_csv

Sample response

Errors

This API operation can return the following errors:

HTTP status codeError code

400

api_version_invalid

400

bundle_selection_ratios_invalid

400

bundle_selection_bundle_invalid

400

order_value_invalid

400

bundle_id_invalid

400

id_invalid

400

distance_invalid

400

test_account_name_update_disallowed

400

bundle_selection_ratios_invalid_format

400

address_not_found

Create a shipping emission estimate (single)

Query parameters

Request body

namestring

bundle_selectionarray

object

bundle_idstringrequired

percentageoneOf@-webkit-keyframes mui-auto-fill{from{display:block;}}@keyframes mui-auto-fill{from{display:block;}}@-webkit-keyframes mui-auto-fill-cancel{from{display:block;}}@keyframes mui-auto-fill-cancel{from{display:block;}}Selection percentage as integer

quantity_truncstring

is_shipmentboolean

shipped_atstring (date-time)

metadataobject

idempotency_keystring

oneOf@-webkit-keyframes mui-auto-fill{from{display:block;}}@keyframes mui-auto-fill{from{display:block;}}@-webkit-keyframes mui-auto-fill-cancel{from{display:block;}}@keyframes mui-auto-fill-cancel{from{display:block;}}Shipping

Response

massobjectrequired

amountstringrequired

unitstringrequired

metadataobject

idempotency_keystring

vessel_inference_detailsoneOf@-webkit-keyframes mui-auto-fill{from{display:block;}}@keyframes mui-auto-fill{from{display:block;}}@-webkit-keyframes mui-auto-fill-cancel{from{display:block;}}@keyframes mui-auto-fill-cancel{from{display:block;}}Failed to infer the vessel

distanceobject

amountstringrequired

unitstringrequired

adjusted_distanceobject

amountstringrequired

unitstringrequired

distance_calculation_methodstringrequired.css-1hiz70q{margin:0;font-family:Helvetica Neue,Arial,sans-serif;font-size:14px;font-style:normal;font-weight:400;line-height:17px;letter-spacing:0em;text-align:left;color:#212121;color:#2864D9;}nullable

routeobjectrequirednullable

sourceobjectrequired

coordinatesobjectrequired

latnumberrequired

lonnumberrequired

legsarrayrequired

object

locationobjectrequired

labelstringrequirednullable

coordinatesobjectrequired

latnumberrequired

lonnumberrequired

distanceobjectrequired

amountstringrequired

unitstringrequired

adjusted_distanceobjectrequired

amountstringrequired

unitstringrequired

emission_factorobjectrequired

idstringrequired

namestringrequired

sourcestringrequired

source_versionstringrequired

publication_yearnumberrequired

numerator_unitstringrequired

denominator_unitoneOfrequired@-webkit-keyframes mui-auto-fill{from{display:block;}}@keyframes mui-auto-fill{from{display:block;}}@-webkit-keyframes mui-auto-fill-cancel{from{display:block;}}@keyframes mui-auto-fill-cancel{from{display:block;}}Currency code

created_atstring (date-time)required

regionstringrequired

categorystringrequirednullable

gas_emissionsobjectrequirednullable

co2estringrequired

co2string

methanestring

nitrous_oxidestring

otherstring

methodologyarrayrequired

string

distance_calculation_detailsobjectrequirednullable

vessel_trackingoneOfrequired@-webkit-keyframes mui-auto-fill{from{display:block;}}@keyframes mui-auto-fill{from{display:block;}}@-webkit-keyframes mui-auto-fill-cancel{from{display:block;}}@keyframes mui-auto-fill-cancel{from{display:block;}}Vessel tracking details

carrier_schedule_stopsobjectrequirednullable

messagestringrequired

methodology_detailsoneOfrequired@-webkit-keyframes mui-auto-fill{from{display:block;}}@keyframes mui-auto-fill{from{display:block;}}@-webkit-keyframes mui-auto-fill-cancel{from{display:block;}}@keyframes mui-auto-fill-cancel{from{display:block;}}Air freight transport

converted_shipmentobjectrequirednullable

amountstringrequired

unitoneOfrequired@-webkit-keyframes mui-auto-fill{from{display:block;}}@keyframes mui-auto-fill{from{display:block;}}@-webkit-keyframes mui-auto-fill-cancel{from{display:block;}}@keyframes mui-auto-fill-cancel{from{display:block;}}Mass

shipment_conversion_methodstringrequirednullable

resolved_legsarrayrequirednullable

object

massobjectrequired

amountstringrequired

unitstringrequired

percentageoneOf
Selection percentage as integer

oneOf
Shipping

vessel_inference_detailsoneOf
Failed to infer the vessel

distance_calculation_methodstringrequirednullable

denominator_unitoneOfrequired
Currency code

vessel_trackingoneOfrequired
Vessel tracking details

methodology_detailsoneOfrequired
Air freight transport

unitoneOfrequired
Mass

vessel_inference_detailsoneOf
Failed to infer the vessel

denominator_unitoneOfrequired
Currency code