Create a shipping emission estimate (multi-leg)
HTTPPOST to /v1/estimates/shipping/multi-legEach leg can be fulfilled by a different method, eg a truck, a plane or other options.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.
mggkgtRequest body
Parameters for estimating multi-leg shipping emissions
shipmentoneOfrequiredMass
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.
legsarrayrequired
An array representing all the legs of a shipment.
oneOfShipping
Shipping
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
percentageoneOfSelection percentage as integer
Selection percentage as integer
quantity_truncstring
Selects to which precision to truncate quantities specific to carbon offsetting.
gkgtis_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_keyto reconcile estimates with entities on their system.
Response
An emission estimate result for a transport involving multiple legs.
Lune's API returns both the total emissions and per-leg emissions (in the legs
property).
The ordering of the legs in the estimate is the same as the ordering of the inputs.
An error with estimating any of the legs will result in the whole estimation process failing completely (we don't provide partial estimates in light of a failure).
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
legsarrayrequired
An array representing a leg's emission estimate.
Returned in the same order as the request.
object
massobjectrequired
amountstringrequired
Pattern: ^[0-9]+(\.[0-9]+)?$
unitstringrequired
Unit, t for tonne, kg for kilogram, g for gram, mg for milligram
mggkgtmetadataobject
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_keyto reconcile estimates with entities on their system.
vessel_inference_detailsoneOfFailed to infer the vessel
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
kmminmadjusted_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
kmminmdistance_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_distancegreat_circle_distance_x2sea_distance_algorithmmapboxuser_inputrouteobjectrequirednullable
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
kmminmadjusted_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
kmminmemission_factorobjectrequired
idstringrequired
The emission factor unique identifier
namestringrequired
The emission factor name
sourcestringrequired
epaexiobaseecoinventbeislunesource_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
gkgtdenominator_unitoneOfrequiredCurrency code
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_fallbackimo_unavailable_container_ship_trade_lane_fallbackflight_number_unavailable_fallbackinvalid_flight_route_fallbackdistance_calculation_detailsobjectrequirednullable
Information regarding why an alternative distance calculation method was used.
null in case several resolved legs are presented.
vessel_trackingoneOfrequiredVessel tracking details
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_detailsoneOfrequiredAir freight transport
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
unitoneOfrequiredMass
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_typeaverage_cargo_typeresolved_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
mggkgtmetadataobject
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_keyto reconcile estimates with entities on their system.
vessel_inference_detailsoneOfFailed to infer the vessel
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
kmminmadjusted_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
kmminmdistance_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_distancegreat_circle_distance_x2sea_distance_algorithmmapboxuser_inputrouteobjectrequirednullable
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
kmminmadjusted_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
kmminmemission_factorobjectrequired
idstringrequired
The emission factor unique identifier
namestringrequired
The emission factor name
sourcestringrequired
epaexiobaseecoinventbeislunesource_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
gkgtdenominator_unitoneOfrequiredCurrency code
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_fallbackimo_unavailable_container_ship_trade_lane_fallbackflight_number_unavailable_fallbackinvalid_flight_route_fallbackdistance_calculation_detailsobjectrequirednullable
Information regarding why an alternative distance calculation method was used.
null in case several resolved legs are presented.
vessel_trackingoneOfrequiredVessel tracking details
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_detailsoneOfrequiredAir freight transport
Air freight transport
methodoneOfrequiredNon-parameterized other than sea
Non-parameterized other than sea
distanceobjectrequired
amountstringrequired
Pattern: ^[0-9]+(\.[0-9]+)?$
unitstringrequired
Unit, km for kilometers, mi for miles
kmminmadjusted_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
kmminmrequestobjectrequired
Parameters for estimating multi-leg shipping emissions
shipmentoneOfrequiredMass
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.
legsarrayrequired
An array representing all the legs of a shipment.
oneOfShipping
Shipping
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
percentageoneOfSelection percentage as integer
Selection percentage as integer
quantity_truncstring
Selects to which precision to truncate quantities specific to carbon offsetting.
gkgtis_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_keyto reconcile estimates with entities on their system.
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.
apidashboardcsvchain_ioecotransit_csvmassobjectrequired
amountstringrequired
Pattern: ^[0-9]+(\.[0-9]+)?$
unitstringrequired
Unit, t for tonne, kg for kilogram, g for gram, mg for milligram
mggkgtmetadataobject
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_keyto reconcile estimates with entities on their system.
idstringrequired
The emission calculation unique identifier
quoteoneOfrequiredError response
Error response
Errors
This API operation can return the following errors:400api_version_invalid400bundle_selection_ratios_invalid400bundle_selection_bundle_invalid400order_value_invalid400bundle_id_invalid400id_invalid400distance_invalid400test_account_name_update_disallowed400bundle_selection_ratios_invalid_format400address_not_foundGet a shipping emission estimate (multi-leg)
HTTPGET to /v1/estimates/shipping/multi-leg/{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.
mggkgtResponse
An emission estimate result for a transport involving multiple legs.
Lune's API returns both the total emissions and per-leg emissions (in the legs
property).
The ordering of the legs in the estimate is the same as the ordering of the inputs.
An error with estimating any of the legs will result in the whole estimation process failing completely (we don't provide partial estimates in light of a failure).
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
legsarrayrequired
An array representing a leg's emission estimate.
Returned in the same order as the request.
object
massobjectrequired
amountstringrequired
Pattern: ^[0-9]+(\.[0-9]+)?$
unitstringrequired
Unit, t for tonne, kg for kilogram, g for gram, mg for milligram
mggkgtmetadataobject
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_keyto reconcile estimates with entities on their system.
vessel_inference_detailsoneOfFailed to infer the vessel
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
kmminmadjusted_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
kmminmdistance_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_distancegreat_circle_distance_x2sea_distance_algorithmmapboxuser_inputrouteobjectrequirednullable
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
kmminmadjusted_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
kmminmemission_factorobjectrequired
idstringrequired
The emission factor unique identifier
namestringrequired
The emission factor name
sourcestringrequired
epaexiobaseecoinventbeislunesource_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
gkgtdenominator_unitoneOfrequiredCurrency code
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_fallbackimo_unavailable_container_ship_trade_lane_fallbackflight_number_unavailable_fallbackinvalid_flight_route_fallbackdistance_calculation_detailsobjectrequirednullable
Information regarding why an alternative distance calculation method was used.
null in case several resolved legs are presented.
vessel_trackingoneOfrequiredVessel tracking details
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_detailsoneOfrequiredAir freight transport
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
unitoneOfrequiredMass
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_typeaverage_cargo_typeresolved_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
mggkgtmetadataobject
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_keyto reconcile estimates with entities on their system.
vessel_inference_detailsoneOfFailed to infer the vessel
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
kmminmadjusted_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
kmminmdistance_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_distancegreat_circle_distance_x2sea_distance_algorithmmapboxuser_inputrouteobjectrequirednullable
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
kmminmadjusted_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
kmminmemission_factorobjectrequired
idstringrequired
The emission factor unique identifier
namestringrequired
The emission factor name
sourcestringrequired
epaexiobaseecoinventbeislunesource_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
gkgtdenominator_unitoneOfrequiredCurrency code
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_fallbackimo_unavailable_container_ship_trade_lane_fallbackflight_number_unavailable_fallbackinvalid_flight_route_fallbackdistance_calculation_detailsobjectrequirednullable
Information regarding why an alternative distance calculation method was used.
null in case several resolved legs are presented.
vessel_trackingoneOfrequiredVessel tracking details
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_detailsoneOfrequiredAir freight transport
Air freight transport
methodoneOfrequiredNon-parameterized other than sea
Non-parameterized other than sea
distanceobjectrequired
amountstringrequired
Pattern: ^[0-9]+(\.[0-9]+)?$
unitstringrequired
Unit, km for kilometers, mi for miles
kmminmadjusted_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
kmminmrequestobjectrequired
Parameters for estimating multi-leg shipping emissions
shipmentoneOfrequiredMass
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.
legsarrayrequired
An array representing all the legs of a shipment.
oneOfShipping
Shipping
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
percentageoneOfSelection percentage as integer
Selection percentage as integer
quantity_truncstring
Selects to which precision to truncate quantities specific to carbon offsetting.
gkgtis_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_keyto reconcile estimates with entities on their system.
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.
apidashboardcsvchain_ioecotransit_csvmassobjectrequired
amountstringrequired
Pattern: ^[0-9]+(\.[0-9]+)?$
unitstringrequired
Unit, t for tonne, kg for kilogram, g for gram, mg for milligram
mggkgtmetadataobject
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_keyto reconcile estimates with entities on their system.
idstringrequired
The emission calculation unique identifier
quoteoneOfrequiredError response
Error response
Errors
This API operation can return the following errors:401404429503service_unavailableUpdate a shipping emission estimate (multi-leg)
HTTPPUT to /v1/estimates/shipping/multi-leg/{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.
mggkgtRequest body
Parameters for estimating multi-leg shipping emissions
shipmentoneOfrequiredMass
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.
legsarrayrequired
An array representing all the legs of a shipment.
oneOfShipping
Shipping
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
percentageoneOfSelection percentage as integer
Selection percentage as integer
quantity_truncstring
Selects to which precision to truncate quantities specific to carbon offsetting.
gkgtis_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_keyto reconcile estimates with entities on their system.
Response
An emission estimate result for a transport involving multiple legs.
Lune's API returns both the total emissions and per-leg emissions (in the legs
property).
The ordering of the legs in the estimate is the same as the ordering of the inputs.
An error with estimating any of the legs will result in the whole estimation process failing completely (we don't provide partial estimates in light of a failure).
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
legsarrayrequired
An array representing a leg's emission estimate.
Returned in the same order as the request.
object
massobjectrequired
amountstringrequired
Pattern: ^[0-9]+(\.[0-9]+)?$
unitstringrequired
Unit, t for tonne, kg for kilogram, g for gram, mg for milligram
mggkgtmetadataobject
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_keyto reconcile estimates with entities on their system.
vessel_inference_detailsoneOfFailed to infer the vessel
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
kmminmadjusted_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
kmminmdistance_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_distancegreat_circle_distance_x2sea_distance_algorithmmapboxuser_inputrouteobjectrequirednullable
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
kmminmadjusted_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
kmminmemission_factorobjectrequired
idstringrequired
The emission factor unique identifier
namestringrequired
The emission factor name
sourcestringrequired
epaexiobaseecoinventbeislunesource_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
gkgtdenominator_unitoneOfrequiredCurrency code
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_fallbackimo_unavailable_container_ship_trade_lane_fallbackflight_number_unavailable_fallbackinvalid_flight_route_fallbackdistance_calculation_detailsobjectrequirednullable
Information regarding why an alternative distance calculation method was used.
null in case several resolved legs are presented.
vessel_trackingoneOfrequiredVessel tracking details
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_detailsoneOfrequiredAir freight transport
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
unitoneOfrequiredMass
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_typeaverage_cargo_typeresolved_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
mggkgtmetadataobject
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_keyto reconcile estimates with entities on their system.
vessel_inference_detailsoneOfFailed to infer the vessel
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
kmminmadjusted_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
kmminmdistance_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_distancegreat_circle_distance_x2sea_distance_algorithmmapboxuser_inputrouteobjectrequirednullable
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
kmminmadjusted_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
kmminmemission_factorobjectrequired
idstringrequired
The emission factor unique identifier
namestringrequired
The emission factor name
sourcestringrequired
epaexiobaseecoinventbeislunesource_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
gkgtdenominator_unitoneOfrequiredCurrency code
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_fallbackimo_unavailable_container_ship_trade_lane_fallbackflight_number_unavailable_fallbackinvalid_flight_route_fallbackdistance_calculation_detailsobjectrequirednullable
Information regarding why an alternative distance calculation method was used.
null in case several resolved legs are presented.
vessel_trackingoneOfrequiredVessel tracking details
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_detailsoneOfrequiredAir freight transport
Air freight transport
methodoneOfrequiredNon-parameterized other than sea
Non-parameterized other than sea
distanceobjectrequired
amountstringrequired
Pattern: ^[0-9]+(\.[0-9]+)?$
unitstringrequired
Unit, km for kilometers, mi for miles
kmminmadjusted_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
kmminmrequestobjectrequired
Parameters for estimating multi-leg shipping emissions
shipmentoneOfrequiredMass
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.
legsarrayrequired
An array representing all the legs of a shipment.
oneOfShipping
Shipping
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
percentageoneOfSelection percentage as integer
Selection percentage as integer
quantity_truncstring
Selects to which precision to truncate quantities specific to carbon offsetting.
gkgtis_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_keyto reconcile estimates with entities on their system.
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.
apidashboardcsvchain_ioecotransit_csvmassobjectrequired
amountstringrequired
Pattern: ^[0-9]+(\.[0-9]+)?$
unitstringrequired
Unit, t for tonne, kg for kilogram, g for gram, mg for milligram
mggkgtmetadataobject
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_keyto reconcile estimates with entities on their system.
idstringrequired
The emission calculation unique identifier
quoteoneOfrequiredError response
Error response
Errors
This API operation can return the following errors:400api_version_invalid400bundle_selection_ratios_invalid400bundle_selection_bundle_invalid400order_value_invalid400bundle_id_invalid400id_invalid400distance_invalid400test_account_name_update_disallowed400bundle_selection_ratios_invalid_format400address_not_foundUpdate a multi-leg shipping emission estimate's annotations
HTTPPATCH to /v1/estimates/shipping/multi-leg/{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`
`is_shipment` with optional `shipped_at`, `metadata` and `idempotency_key`
Response
An emission estimate result for a transport involving multiple legs.
Lune's API returns both the total emissions and per-leg emissions (in the legs
property).
The ordering of the legs in the estimate is the same as the ordering of the inputs.
An error with estimating any of the legs will result in the whole estimation process failing completely (we don't provide partial estimates in light of a failure).
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
legsarrayrequired
An array representing a leg's emission estimate.
Returned in the same order as the request.
object
massobjectrequired
amountstringrequired
Pattern: ^[0-9]+(\.[0-9]+)?$
unitstringrequired
Unit, t for tonne, kg for kilogram, g for gram, mg for milligram
mggkgtmetadataobject
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_keyto reconcile estimates with entities on their system.
vessel_inference_detailsoneOfFailed to infer the vessel
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
kmminmadjusted_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
kmminmdistance_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_distancegreat_circle_distance_x2sea_distance_algorithmmapboxuser_inputrouteobjectrequirednullable
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
kmminmadjusted_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
kmminmemission_factorobjectrequired
idstringrequired
The emission factor unique identifier
namestringrequired
The emission factor name
sourcestringrequired
epaexiobaseecoinventbeislunesource_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
gkgtdenominator_unitoneOfrequiredCurrency code
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_fallbackimo_unavailable_container_ship_trade_lane_fallbackflight_number_unavailable_fallbackinvalid_flight_route_fallbackdistance_calculation_detailsobjectrequirednullable
Information regarding why an alternative distance calculation method was used.
null in case several resolved legs are presented.
vessel_trackingoneOfrequiredVessel tracking details
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_detailsoneOfrequiredAir freight transport
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
unitoneOfrequiredMass
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_typeaverage_cargo_typeresolved_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
mggkgtmetadataobject
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_keyto reconcile estimates with entities on their system.
vessel_inference_detailsoneOfFailed to infer the vessel
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
kmminmadjusted_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
kmminmdistance_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_distancegreat_circle_distance_x2sea_distance_algorithmmapboxuser_inputrouteobjectrequirednullable
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
kmminmadjusted_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
kmminmemission_factorobjectrequired
idstringrequired
The emission factor unique identifier
namestringrequired
The emission factor name
sourcestringrequired
epaexiobaseecoinventbeislunesource_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
gkgtdenominator_unitoneOfrequiredCurrency code
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_fallbackimo_unavailable_container_ship_trade_lane_fallbackflight_number_unavailable_fallbackinvalid_flight_route_fallbackdistance_calculation_detailsobjectrequirednullable
Information regarding why an alternative distance calculation method was used.
null in case several resolved legs are presented.
vessel_trackingoneOfrequiredVessel tracking details
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_detailsoneOfrequiredAir freight transport
Air freight transport
methodoneOfrequiredNon-parameterized other than sea
Non-parameterized other than sea
distanceobjectrequired
amountstringrequired
Pattern: ^[0-9]+(\.[0-9]+)?$
unitstringrequired
Unit, km for kilometers, mi for miles
kmminmadjusted_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
kmminmrequestobjectrequired
Parameters for estimating multi-leg shipping emissions
shipmentoneOfrequiredMass
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.
legsarrayrequired
An array representing all the legs of a shipment.
oneOfShipping
Shipping
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
percentageoneOfSelection percentage as integer
Selection percentage as integer
quantity_truncstring
Selects to which precision to truncate quantities specific to carbon offsetting.
gkgtis_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_keyto reconcile estimates with entities on their system.
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.
apidashboardcsvchain_ioecotransit_csvmassobjectrequired
amountstringrequired
Pattern: ^[0-9]+(\.[0-9]+)?$
unitstringrequired
Unit, t for tonne, kg for kilogram, g for gram, mg for milligram
mggkgtmetadataobject
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_keyto reconcile estimates with entities on their system.
idstringrequired
The emission calculation unique identifier
quoteoneOfrequiredError response
Error response
Errors
This API operation can return the following errors:400api_version_invalid400bundle_selection_ratios_invalid400bundle_selection_bundle_invalid400order_value_invalid400bundle_id_invalid400id_invalid400distance_invalid400test_account_name_update_disallowed400bundle_selection_ratios_invalid_format400address_not_found