post
https://example.com/v6/cargo-footprint/
Table of Contents
Environments
OceanScore provides users with two distinct environments to separate testing from production operations:
🔧 Development Environment
https://dev.voyage.emissions.simulator.oceanscore.com/v6/cargo-footprint/- Intended for experimentation and testing
- Lower performance and a reduced dataset
- Use this to validate integrations and simulate API behavior without affecting production workloads
Production Environment
https://voyage.emissions.simulator.oceanscore.com/v6/cargo-footprint/- Optimized for live usage
- Accesses the full data and runs on faster servers
API Versioning
CargoFP uses URL-based versioning to ensure smooth transitions between updates.
- Active versions are always the latest (
vN) and previous (vN-1) - Version upgrades are communicated via email in advance
Current Active Versions
| Environment | v6 Endpoint URL |
|---|---|
| Development | https://dev.voyage.emissions.simulator.oceanscore.com/v6/cargo-footprint/ |
| Production | https://voyage.emissions.simulator.oceanscore.com/v6/cargo-footprint/ |
Legacy Version
| Environment | v5 Endpoint URL |
|---|---|
| Development | https://dev.voyage.emissions.simulator.oceanscore.com/v5/cargo-footprint/ |
| Production | https://voyage.emissions.simulator.oceanscore.com/v5/cargo-footprint/ |
OceanScore will maintain both current and previous versions active to allow for seamless upgrades.
Request Format
Required Fields
| Field | Type | Description |
|---|---|---|
imo_number | Integer | IMO number of the vessel (7 digits). Not mandatory if ship_name is provided |
departure_port_code | String | 5-letter UN/LOCODE of departure port |
arrival_port_code | String | 5-letter UN/LOCODE of arrival port |
cargo_weight_mt | Double | Cargo weight in metric tonnes (non-negative) |
cargo_reefer | Boolean | Indicates if cargo is refrigerated |
is_cargo_net_weight | Boolean | Indicates if cargo weight is net |
Optional Fields
| Field | Type | Description |
|---|---|---|
id | String | Optional tracking ID set by user |
departure_datetime | String | ISO 8601 format expected departure date/time |
arrival_datetime | String | ISO 8601 format expected arrival date/time |
ship_name | String | To identify the vessel if IMO number is not available |
match_type | String | See below for match type options |
departure_port_name | String | To identify the departure port if UNLOCODE is not available |
arrival_port_name | String | To identify the arrival port if UNLOCODE is not available |
⚠️ For Post-Voyage requests, departure_datetime and arrival datetime are mandatory.
Match Types
Controls how strictly ports must match for Post-Voyage data to be returned:
| Value | Description |
|---|---|
port | Requires full match with port visited by the ship (default) |
country | Matches by country if exact port isn’t matched |
none | Falls back to timestamp if no port/country match; still attempts match in descending order of strictness |
If matching fails, the API returns Pre-Voyage data instead.
Response Format
Metadata Fields
| Field | Type | Description |
|---|---|---|
id | String or Null | User-provided identification for tracking purposes |
data_origin | String | Source of data: calculated or ship_manager |
quality_flag | String | Type of data returned: pre_voyage or past_voyage |
imo_number | Integer | Vessel's unique identification number |
name | String | Name of the vessel as stored in OceanScore database at the time of the call |
ship_type | String | Type of ship (Container, Ro-Ro, General Cargo) |
distance_nm | Double | Distance sailed: Pre-Voyage = shortest feasible + 15% DAF; Post-Voyage = actual distance from AIS |
Emissions Data
| Field | Type | Description |
|---|---|---|
co2_well_to_tank_kg | Double | CO₂ Well-to-Tank emissions based on fuel production and consumption |
co2_tank_to_wake_kg | Double | CO₂ Tank-to-Wake emissions based on actual combustion |
co2_well_to_wake_kg | Double | Total CO₂ emissions (WtT + TtW) |
co2_equivalent_well_to_tank_kg | Double | CO₂ equivalent Well-to-Tank using RED Annex II GWP factors |
co2_equivalent_tank_to_wake_kg | Double | CO₂ equivalent Tank-to-Wake using RED Annex II GWP factors |
co2_equivalent_well_to_wake_kg | Double | Sum of CO₂e WtT and TtW |
nox_tank_to_wake_kg | Double | NOx emissions from engine load and NECA region rules |
sox_tank_to_wake_kg | Double | SOx emissions based on SECA region and Exhaust Gas Cleaning System onboard |
nmhc_tank_to_wake_kg | Double | Non-Methane Hydrocarbons from engine load and fuel type |
pm_tank_to_wake_kg | Double | Particulate Matter affected by fuel sulphur % and EGCS use |
total_energy_mj | Double | Total energy used in Megajoules (MJ) to carry the cargo |
Operational Factors
| Field | Type | Description |
|---|---|---|
average_speed_knots | Double | Weighted Voyage Average Sailing Speed while > 3 knots |
average_utilization_percent | Double | Weighted Voyage Average Gross Cargo as % of ship DWT while Sailing Speed > 3 knots |
average_utilization_percent_source | String | Source of utilization estimate: modelled, historical average, DWT Fallback |
percent_time_sailing | Double | % of voyage total time under propulsion where status is “Underway” |
The purpose of operational factors is to understand the main drivers of emissions and explain any outliers.
Net Cargo Calculations
| Field | Type | Description |
|---|---|---|
net_intensity_co2_equivalent_well_to_wake | Double | Intensity in gCO2e/tkm calculated based on net cargo onboard carried during the voyage |
net_transport_work_mt_km | Double | Sum of the products of distance traveled in kilometers and the net cargo carried for the voyage |
net_co2_equivalent_emissions_kg | Double | Total emissions resulting from the transport of a given amount of cargo |
is_in_accordance_with_iso_14083 | Boolean | Calculated in accordance with ISO 14083 (depending on the ship type) |