Hubs
This guide provides an explanation of how the Shipment API handles hubs, both autogenerated and manually defined, as well as their role in emissions calculations.
Overview
Hubs are key points in a transport chain, like modal shifts (e.g., road to rail, rail to sea) and transshipments (e.g., transferring goods between vessels at a container terminal) sites.
The Shipment API identifies these points and generates them automatically, on top of incorporating user-defined hubs, ensuring an accurate representation of the transport chain of a shipment and the associated emissions.
Autogenerated Hubs
Autogenerated hubs are included in the transport chain whenever the API detects a transition between transport legs.
When are hubs autogenerated?
-
Transshipment sites:
- Occur when goods shift between modes of transport (e.g., road to rail).
-
Maritime Container Terminals:
- Generated when goods are transferred between two sea legs or between a sea leg and another mode.
Example response for an autogenerated hub
{
"type": "hub",
"location": {
"locode": "FRMRS",
"coordinates": [
5.22142410278,
43.439271922
],
"city": "Marseille Provence Airport",
"country": "France",
"region": "Mediterranean/Black Sea"
},
"parameters": {},
"properties": {
"dataType": "default",
"source": "auto_generated",
"hubType": "maritime_container_terminal",
"orders": [
{
"weight": 300.0,
"type": "parcel",
"co2e": {
"total": 321,
"wtt": 64,
"ttw": 257
}
}
]
},
"co2e": {
"total": 321,
"wtt": 64,
"ttw": 257
}
},
Manual hubs
Manual hubs allow users to define specific points in the transport chain, representing custom operations (e.g., goods stored at a warehouse) that cannot be deduced from the transport chain itself.
Defining manual hubs
Users can include manual hubs in the input request as follows:
"transportChainElements": [
{
"type": "hub",
"hubType": "WAREHOUSE"
},
This will generate a response as follows, taken into consideration the location related to the next location.
{
"type": "hub",
"location": {
"locode": "FRLIO",
"coordinates": [
5.081111,
45.725556
],
"city": "Lyon Saint-ExupΓ©ry Airport",
"country": "France",
"region": "Mediterranean/Black Sea"
},
"parameters": {
"hubType": "WAREHOUSE"
},
"properties": {
"dataType": "default",
"source": "user_input",
"hubType": "warehouse",
"orders": [
{
"weight": 300.0,
"type": "parcel",
"co2e": {
"total": 13650,
"wtt": 2730,
"ttw": 10920
}
}
]
},
"co2e": {
"total": 13650,
"wtt": 2730,
"ttw": 10920
}
},
Autogenerated and manual hubs comparison
| Details | Manual hubs | Autogenerated hubs |
|---|---|---|
source | user_input | auto_generated |
| Use Case | Specific scenarios | Modal shifts, transshipments inferred |
| Defined By | User input | Shipment API logic |
| Flexibility | Fully manual | Fixed to detected transitions |
| Supported hub types | warehouse, storage_transhipment, liquid_bulk_terminal | transshipment_site, maritime_container_terminal |
Example with both autogenerated and manual hubs
Here is an example combining:
- a manual hub (
warehouse) - a modal shift between
roadandrailleg, generating atranshipment_sitehub - a modal shift between
railandsealeg, generating acontainer_maritime_terminalhub - a transshipment between two
sealegs, generating acontainer_maritime_terminalhub
{
"orders": [
{
"type": "parcel",
"weight": 300
}
],
"transportChainElements": [
{
"type": "hub",
"hubType": "warehouse"
},
{
"type": "leg",
"from": "FREBU",
"to": "FRLIO",
"mode": "road"
},
{
"type": "leg",
"from": "FRLIO",
"to": "FRFOS",
"mode": "rail"
},
{
"type": "leg",
"from": "FRFOS",
"to": "CNSHA",
"mode": "sea"
},
{
"type": "leg",
"from": "CNSHA",
"to": "KRICH",
"mode": "sea"
}
]
}
{
"parameters": {
"orders": [
{
"weight": 300.0,
"type": "parcel"
}
]
},
"co2e": {
"total": 67272,
"wtt": 12405,
"ttw": 54867,
"intensity": 0.01273
},
"transportChainElements": [
{
"type": "hub",
"location": {
"locode": "FREBU",
"coordinates": [
4.4,
45.43333333333333
],
"city": "Saint-Γtienne",
"country": "France",
"region": "Mediterranean/Black Sea"
},
"parameters": {
"hubType": "warehouse"
},
"properties": {
"dataType": "default",
"source": "user_input",
"hubType": "warehouse",
"orders": [
{
"weight": 300.0,
"type": "parcel",
"co2e": {
"total": 13650,
"wtt": 2730,
"ttw": 10920
}
}
]
},
"co2e": {
"total": 13650,
"wtt": 2730,
"ttw": 10920
}
},
{
"type": "leg",
"from": {
"locode": "FREBU",
"coordinates": [
4.4,
45.43333333333333
],
"city": "Saint-Γtienne",
"country": "France",
"region": "Mediterranean/Black Sea"
},
"to": {
"locode": "FRLIO",
"coordinates": [
4.834366996675094,
45.71740311038615
],
"city": "Lyon",
"country": "France",
"region": "Mediterranean/Black Sea"
},
"tradeLane": "Intra Mediterranean",
"mode": "road",
"parameters": {},
"properties": {
"dataType": "default",
"distance": {
"sfd": {
"total": 58819
},
"used": {
"total": 58819,
"source": "daf"
}
},
"model": {
"name": "sfd-direct-emissionfactors"
},
"region": "Europe",
"truck": {
"minSize": 0.0,
"maxSize": 3.5,
"loadFactor": null,
"emptyRunning": null,
"fuelType": "petrol",
"combinedEmptyRunningLoadFactor": 0.24
},
"orders": [
{
"weight": 300.0,
"type": "parcel",
"co2e": {
"total": 17116,
"wtt": 4147,
"ttw": 12970,
"intensity": 0.97
}
}
],
"carrier": null
},
"co2e": {
"total": 17116,
"wtt": 4147,
"ttw": 12970,
"intensity": 0.97
}
},
{
"type": "hub",
"location": {
"locode": "FRLIO",
"coordinates": [
4.834366996675094,
45.71740311038615
],
"city": "Lyon",
"country": "France",
"region": "Mediterranean/Black Sea"
},
"parameters": {},
"properties": {
"dataType": "default",
"source": "auto_generated",
"hubType": "transhipment_site",
"orders": [
{
"weight": 300.0,
"type": "parcel",
"co2e": {
"total": 390,
"wtt": 78,
"ttw": 312
}
}
]
},
"co2e": {
"total": 390,
"wtt": 78,
"ttw": 312
}
},
{
"type": "leg",
"from": {
"locode": "FRLIO",
"coordinates": [
5.081111,
45.725556
],
"city": "Lyon Saint-ExupΓ©ry Airport",
"country": "France",
"region": "Mediterranean/Black Sea"
},
"to": {
"locode": "FRFOS",
"coordinates": [
4.848286968176052,
43.407186268695995
],
"city": "Fos-sur-Mer",
"country": "France",
"region": "Mediterranean/Black Sea"
},
"tradeLane": "Intra Mediterranean",
"mode": "rail",
"parameters": {},
"properties": {
"dataType": "default",
"distance": {
"sfd": {
"total": 329107
},
"used": {
"total": 329107,
"source": "daf"
}
},
"model": {
"name": "sfd-direct-emissionfactors"
},
"orders": [
{
"weight": 300.0,
"type": "parcel",
"co2e": {
"total": 1560,
"wtt": 691,
"ttw": 869,
"intensity": 0.0158
}
}
]
},
"co2e": {
"total": 1560,
"wtt": 691,
"ttw": 869,
"intensity": 0.0158
}
},
{
"type": "hub",
"location": {
"locode": "FRFOS",
"coordinates": [
4.848286968176052,
43.407186268695995
],
"city": "Fos-sur-Mer",
"country": "France",
"region": "Mediterranean/Black Sea"
},
"parameters": {},
"properties": {
"dataType": "default",
"source": "auto_generated",
"hubType": "maritime_container_terminal",
"orders": [
{
"weight": 300.0,
"type": "parcel",
"co2e": {
"total": 321,
"wtt": 64,
"ttw": 257
}
}
]
},
"co2e": {
"total": 321,
"wtt": 64,
"ttw": 257
}
},
{
"type": "leg",
"from": {
"locode": "FRFOS",
"coordinates": [
4.848286968176052,
43.407186268695995
],
"city": "Fos-sur-Mer",
"country": "France",
"region": "Mediterranean/Black Sea"
},
"to": {
"locode": "CNSHA",
"coordinates": [
122.06550521343334,
30.61798396262171
],
"city": "Shanghai",
"country": "China",
"region": "North East Asia"
},
"tradeLane": "Asia to-from Mediterranean",
"mode": "sea",
"parameters": {},
"properties": {
"dataType": "default",
"distance": {
"sfd": {
"total": 16308330
},
"used": {
"total": 18754580,
"source": "daf",
"seca": 0
}
},
"model": {
"name": "sfd-direct-emissionfactors"
},
"vessel": {
"imo": null,
"name": "Asia to-from Mediterranean GLEC Representative Vessel",
"minTeu": null,
"maxTeu": null,
"fuelType": null
},
"tradeLane": "Asia to-from Mediterranean",
"orders": [
{
"weight": 300.0,
"type": "parcel",
"co2e": {
"total": 30089,
"wtt": 4110,
"ttw": 25979,
"intensity": 0.00615
}
}
]
},
"co2e": {
"total": 30089,
"wtt": 4110,
"ttw": 25979,
"intensity": 0.00615
}
},
{
"type": "hub",
"location": {
"locode": "CNSHA",
"coordinates": [
122.06550521343334,
30.61798396262171
],
"city": "Shanghai",
"country": "China",
"region": "North East Asia"
},
"parameters": {},
"properties": {
"dataType": "default",
"source": "auto_generated",
"hubType": "maritime_container_terminal",
"orders": [
{
"weight": 300.0,
"type": "parcel",
"co2e": {
"total": 321,
"wtt": 64,
"ttw": 257
}
}
]
},
"co2e": {
"total": 321,
"wtt": 64,
"ttw": 257
}
},
{
"type": "leg",
"from": {
"locode": "CNSHA",
"coordinates": [
122.06550521343334,
30.61798396262171
],
"city": "Shanghai",
"country": "China",
"region": "North East Asia"
},
"to": {
"locode": "KRICH",
"coordinates": [
126.597681,
37.440272
],
"city": "Inchon Krich",
"country": "Korea, Republic of",
"region": "North East Asia"
},
"tradeLane": "Intra NE Asia",
"mode": "sea",
"parameters": {},
"properties": {
"dataType": "default",
"distance": {
"sfd": {
"total": 913825
},
"used": {
"total": 1050899,
"source": "daf",
"seca": 54336
}
},
"model": {
"name": "sfd-direct-emissionfactors"
},
"vessel": {
"imo": null,
"name": "Intra NE Asia GLEC Representative Vessel",
"minTeu": null,
"maxTeu": null,
"fuelType": null
},
"tradeLane": "Intra NE Asia",
"orders": [
{
"weight": 300.0,
"type": "parcel",
"co2e": {
"total": 3824,
"wtt": 521,
"ttw": 3303,
"intensity": 0.01395
}
}
]
},
"co2e": {
"total": 3824,
"wtt": 521,
"ttw": 3303,
"intensity": 0.01395
}
}
]
}
Updated 1 day ago