Guides

Migrate from v2.0 to v2.1

A dedicated guide to migrate your Multimodal Shipment API

Suggest Edits

πŸ‘

Notice

The v2.0 is still maintained, but the v2.1 adheres to the ISO-14083.

What are the benefits of migrating?

  • v2.1 is fully ISO-14083 compliant.
  • v2.0 won't get any new features.
  • It enhances COβ‚‚e calculations and features for greater precision across all modes.
  • Updates in methodology transparency make the new version easier to adopt and integrate into your workflows.

βš™οΈ How to migrate?

Start by selecting the API version

To use v2.1, you need to include a header to specify the version. Use the Accept-Version header with the value 2.1 to access the new version as shown below:

curl --request POST \
  --url https://api.searoutes.com/shipment/v2/report/co2 \
  --header 'Accept-Version: 2.1' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <your-api-key>' \
  --data '{
  <your_data>
  }

1️⃣ Passing a request

Our v2.1 input contract contains the following structured objects:

  • legs
  • orders
  • details

We will go through the changes for each of those objects to help you translate your existing requests to the new contract.

To simplify building requests, you can now pass all the enum values as lower case or upper case. This applies for example to order types, container size type codes, fuel types, aircraft types, hub types, modes, inland vessel types, etc.

Legs

Thelegsfield has been replaced with transportChainElements, introducing two types of transportChainElements:

  1. leg
  2. hub

To translate your old leg object to the new transportChainElement, there are two cases:

Case 1:

If leg.mode value is sea, air , road, rail or inland-water:

  • add type=leg
  • Also update the mode "inland-water" to "inland_water"
{
    "from": "FRMRS",
    "to": "BEANR",
    "mode": "sea"
}

{
    "type": "leg",
    "from": "FRMRS",
    "to": "BEANR",
    "mode": "sea"
}

Case 2:

Ifleg.modevalue is hub:

  • Add a"type" : "hub" field
  • Hub types such asTRANSHIPMENT_SITE and MARITIME_CONTAINER_TERMINAL are now automatically generated. 🚫 Manual addition of these hub types is no longer supported.
  • The details.hubType field has also moved to hubType.
{
    "mode": "hub",
    "details": {
        "hubType": "WAREHOUSE"
    }
}

{
    "type": "hub",
    "hubType": "warehouse"
}

Let's summarize the changes by transforming entire legs object


"legs": [
    {
        "from": "CNSHA",
        "to": "FRFOS",
        "mode": "sea"
    },
    {
        "mode": "hub",
        "details": {
            "hubType": "MARITIME_CONTAINER_TERMINAL"
        }
    },
    {
        "mode": "inland-water",
        "from": "FRFOS",
        "to": "FRLIO"
    },
    {
        "mode": "hub",
        "details": {
            "hubType": "WAREHOUSE"
        }
    }
]


"transportChainElements": [
    {
        "type": "leg",
        "from": "CNSHA",
        "to": "FRFOS",
        "mode": "sea"
    },
    {
        "type": "leg",
        "mode": "inland_water",
        "from": "FRFOS",
        "to": "FRLIO"
    },
    {
        "type": "hub",
        "hubType": "warehouse"
    }
]

No other change is needed πŸ₯³

Orders

The type field no longer supports these values CONTAINER, UNIT_LOAD, and PALLET. These were previously aliases for other types, but aliases are no longer supported.

Apply the following replacement:

v2.0v2.1
CONTAINERFCL
UNIT_LOADparcel
PALLETparcel
sizeTypeCodecontainerSizeTypeCode
quantityis now renamed nContainers ⚠️ only impacts requests with order types FCL. For other requests, it will be ignored so you can remove it.

Examples:

{
    "type": "FCL",
    "quantity": 3,
    "sizeTypeCode": "20GP"
}

{
    "type": "FCL",
    "nContainers": 3,
    "containerSizeTypeCode": "20GP"
}

🚧

LCL order type is not compatible with air mode legs anymore

If you have this, you must change the order type to parcel. This change will help you get more accurate COβ‚‚e emissions when your requests contain legs of other modes than air.

{
    "orders": [
        {
            "weight": 1500,
            "type": "LCL"
        }
    ],
    "legs": [
        {
            "from": "CNSHA",
            "to": "FRFOS",
            "mode": "air"
        }
    ]
}

{
    "orders": [
        {
            "weight": 1500,
            "type": "parcel"
        }
    ],
    "transportChainElements": [
        {
            "type": "leg",
            "from": "CNSHA",
            "to": "FRFOS",
            "mode": "air"
        }
    ]
}

Details

The details field at root level has been removed. This means that:

  • The API no longer accepts a carrier object in details.carrier
  • You will need to add the carrier to each relevant leg in leg.details.carrier.

{
    "details": {
        "carrier": {
            "scac": "MAEU"
        }
    },
    "orders": [
        {
            "weight": 1500,
            "type": "LCL"
        }
    ],
    "legs": [
        {
            "from": "CNSHA",
            "to": "FRFOS",
            "mode": "sea"
        }
    ]
}

{
    "orders": [
        {
            "weight": 1500,
            "type": "LCL"
        }
    ],
    "legs": [
        {
            "from": "CNSHA",
            "to": "FRFOS",
            "mode": "sea",
            "details": {
                "carrier": {
                    "scac": "MAEU"
                }
            }
        }
    ]
}

All the other fields (referenceNumber, id, status, client) do not impact the calculation, you can pass them in the metadata object if you need them to help identifying your shipment.

Query parameters

The generateCertificate parameter is no longer supported, as certificates are not available in v2.1. They might return later in a new form.

Complete example

{
    "details": {
        "carrier": {
            "scac": "MAEU"
        },
        "referenceNumber": "myShipment123"
    },
    "orders": [
        {
            "type": "PALLET",
            "weight": 300
        },
        {
            "type": "CONTAINER",
            "quantity": 4,
            "sizeTypeCode": "40GP"
        }
    ],
    "legs": [
        {
            "mode": "hub",
            "details": {
                "hubType": "WAREHOUSE"
            }
        },
        {
            "from": "CNSHA",
            "to": "BEANR",
            "mode": "sea"
        },
        {
            "mode": "hub",
            "details": {
                "hubType": "MARITIME_CONTAINER_TERMINAL"
            }
        },
        {
            "from": "BEANR",
            "to": "NOOSL",
            "mode": "sea"
        },
        {
            "mode": "hub",
            "details": {
                "hubType": "TRANSHIPMENT_SITE"
            }
        },
        {
            "from": "NOOSL",
            "to": "Trondheim",
            "mode": "road"
        }
    ]
}

{
    "orders": [
        {
            "type": "parcel",
            "weight": 300
        },
        {
            "type": "FCL",
            "nContainers": 4,
            "containerSizeTypeCode": "40GP"
        }
    ],
    "transportChainElements": [
        {
            "type": "hub",
            "hubType": "warehouse"
        },
        {
            "type": "leg",
            "from": "CNSHA",
            "to": "BEANR",
            "mode": "sea",
            "details": {
                "carrier": {
                    "scac": "MAEU"
                }
            }
        },
        {
            "type": "leg",
            "from": "BEANR",
            "to": "NOOSL",
            "mode": "sea",
            "details": {
                "carrier": {
                    "scac": "MAEU"
                }
            }
        },
        {
            "type": "leg",
            "from": "NOOSL",
            "to": "Trondheim",
            "mode": "road"
        }
    ],
    "metadata": {
        "referenceNumber": "myShipment123"
    }
}

πŸͺ„Main differences when passing a request

v2.0v2.1Change type
Enum values are case-sensitiveEnum values are insensitive to case
hubType values : TRANSHIPMENT_SITE, MARITIME_CONTAINER_TERMINAL, WAREHOUSE, STORAGE_TRANSHIPMENT, LIQUID_BULK_TERMINALhubType values : warehouse, storage_transhipment, liquid_bulk_terminal

Removed

order.type values :CONTAINER, FCL, LCL, UNIT_LOAD, PALLET, PARCELorder.type values : FCL, LCL, parcel

Removed

details.carrier/

Removed

details/

Removed

leg.mode="air" + order.type="LCL"\ returns 200http status 400

Removed

Query parameter generateCertificate/

Removed

/transportChainElement.type

Added

leg.mode="hub"transportChainElement.type="hub"

Changed

leg.details.hubTypetransportChainElement.hubType

Changed

legstransportChainElements

Renamed

order.sizeTypeCodeorder.containerSizeTypeCode

Renamed

order.quantityorder.nContainers

Renamed

leg.mode="inland-water"transportChaineElement.mode="inland_water"

Renamed


2️⃣ Getting a response

The response contract has also been adjusted to match the changes made in the input and now includes additional information about the hubs calculation.

Input alignement

The parameters field in the response now contains exactly the fields that you passed: if you didn't pass a specific key, you won't see it in the response.

The legs object becomes transportChainElements.

In this new field, we match the body input changes:

  • The elements of the transportChainElements lists contain a type that can either be hub or leg
  • In the transportChainElements, properties.orders[*].sizeTypeCode becomes properties.orders[*].containerSizeTypeCode
  • inland-water legs become inland_water

The parameters objects are updated to match your input.

How to handle the new transportChainElements

To give you transparency on the details of the calculation of the hubs emissions respecting the new ISO norm, transportChainElements of type hub are automatically added.

You can identify easily the hubs that were automatically added by checking that type="hub" and source="auto_generated" (as opposed to source="user_input" for the hubs you entered). Note that the source field is only added in hub elements.

Example:

{
    "orders": [
        {
            "type": "FCL",
            "nContainers": 4,
            "containerSizeTypeCode": "40GP"
        }
    ],
    "transportChainElements": [
        {
            "type": "hub",
            "hubType": "warehouse"
        },
        {
            "type": "leg",
            "from": "CNSHA",
            "to": "BEANR",
            "mode": "sea",
            "details": {
                "carrier": {
                    "scac": "MAEU"
                }
            }
        },
        {
            "type": "leg",
            "from": "BEANR",
            "to": "NOOSL",
            "mode": "sea",
            "details": {
                "carrier": {
                    "scac": "MAEU"
                }
            }
        }
    ]
}

{
    "parameters": {
        "orders": [
            {
                "type": "fcl",
                "containerSizeTypeCode": "40gp",
                "nContainers": 4.0
            }
        ]
    },
    "co2e": {
		...
    },
    "transportChainElements": [
        {
            "type": "hub",
            "location": {
                "locode": "CNSHA",
				...
            },
            "properties": {
                "source": "user_defined",
                "hubType": "warehouse",
				...
            },
			...
        },
        {
            "type": "leg",
            "from": {
                "locode": "CNSHA",
				...
            },
            "to": {
                "locode": "BEANR",
				...
            },
			...
        },
        {
            "type": "hub",
            "location": {
                "locode": "BEANR",
				...
            },
            "properties": {
                "source": "auto_generated",
                "hubType": "maritime_container_terminal",
				...
            }
			...
        },
        {
            "type": "leg",
            "from": {
                "locode": "BEANR",
				...
            },
            "to": {
                "locode": "NOOSL",
				...
            },
			...
        }
    ]
}

We pass as input 3 transport chain elements:

  • A warehouse hub
  • A maritime leg from CNSHA to BEANR
  • A maritime leg from BEANR to NOOSL

We get in response 4 transport chain elements:

  • The warehouse hub passed as input, easy to spot with the properties.source="user_input"
  • The maritime leg from CNSHA to BEANR
  • An auto generated hub in BEANR, with properties.source="auto_generated"
  • The maritime leg from BEANR to NOOSL

πŸ’‘A hub with the appropriate type will be automatically added between each pair of consecutive legs.

The case of enum

We now return every enum value in lowercase snake_case. This applies to the fuel types, container size type codes, order types, transport chain elements types, transport modes, data types, distance sources, hub types, hub sources, inland vessel types, aircraft types, etc. This applies to all enum except our model names.

Miscellaneous changes

The distance field in the legs objects is now a brand new object with more information. It contains the old distanceand secaIntersection fields along with the shortest feasible distance (sfd) and the details about the distance used for the COβ‚‚e calculation.

Possible values for distance.used.source are :

  • ais
  • schedules
  • user_input
  • daf (Distance Adjustment Factor), which provides information about the source of the distance used for the COβ‚‚e calculation.
{
    ...,
    "properties": {
        ...,
        "distance": 4477931,
        "secaIntersection": 872150
    }
}

{
    ...,
    "properties": {
        "distance": {
            "sfd": {
                "total": 3893853
            },
            "used": {
                "total": 4477931,
                "source": "DAF",
                "seca": 872150
            }
        }
    }
}

In transportChainElement[*].properties for a road leg, you will no longer find a carrierScac field, but a carrier object with a scac field if relevant or null if no carrier was taken into account.

The field transportChainElement.orders[*].nTEU is now never returned for parcel orders and always returned for FCL and LCL orders and named nTeu.

v2.0v2.1Change type
leg.properties.containerSizeTypeCode

Removed

transportChainElement.type

Added

transportChainElement.properties.distance.used.source

Added

transportChainElement.properties.source

Added

transportChainElement.properties.distance

Added

leg.properties.distancetransportChainElement.properties.distance.used.total

Changed

Added

leg.properties.secaIntersectiontransportChainElement.properties.distance.used.seca

Changed

leg.properties.orders[*].nTEUtransportChainElement.orders[*].nTeu

Changed

leg[*].properties.carrierScac for road legstransportChainElement[*].properties.carrier.scac

Changed

legstransportChainElements

Renamed

Changed

leg.properties.orders[*].sizeTypeCodetransportChainElement.properties.orders[*].containerSizeTypeCode

Renamed

ENUM_VALUEenum_value

Renamed

transportChainElement.orders[*].nTEUtransportChainElement.orders[*].nTeu

Renamed

transportChainElement.properties.vessel.minTEUtransportChainElement.properties.vessel.minTeu

Renamed

transportChainElement.properties.vessel.maxTEUtransportChainElement.properties.vessel.maxTeu

Renamed

transportChainElement.properties.truck.fueltransportChainElement.properties.truck.fuelType

Renamed

πŸ‘‹

Need support?

If you have questions about the migration process or need technical support, don't hesitate in reaching us out to [email protected]

Updated 8 days ago