# calculate Transport from json input

request for emission calculations

Endpoint: POST /etw-rest/calculateTransport
Version: 2025r4.1.4
Security: oAuth2AuthorizationCode

## Request fields (application/json):

  - `transportID` (string)
    Only Informational. Will also occur in Response. Use this to identify/tag/descripe your Requests

  - `transportDate` (object)
    Input: Only relevant for sea with routing "ais-based" (default) and air routing 
For longer trips the transportDate shall specify the arrival date
Output: Same as provided in the request or otherwise set to default

  - `transportDate.year` (integer, required)
    year in 4 digit notation
    Example: "2022"

  - `transportDate.month` (integer)
    month as number - e.g. "3" for march
    Example: "3"

  - `transportDate.day` (integer)
    day of the month
    Example: "27"

  - `cargo` (object, required)
    Example: {"unit":"TONS","amount":42}

  - `accounting` (object)
    Only available for air, sea and cooled transport (trucks, container trains and Clean Cargo container ships)

  - `accounting.air` (object)

  - `accounting.air.variant` (string, required)
    | Option   | Description                                           |
|----------|-------------------------------------------------------|
| none     | Belly plane allocation on the base of EN16258(Default) |
| Icao     | Belly plane allocation on the base of ICAO/IATA methodology |
| Skailark | Belly plane allocation on the base of Skailark methodology |
    Enum: "NONE", "ICAO", "SKAILARK"

  - `accounting.sea` (object)

  - `accounting.sea.variant` (string, required)
    | Option                       | Description                                                        |
|------------------------------|--------------------------------------------------------------------|
| none                         | Sea ship calculation on the base of the ETW bottom-up methodology           |
| CLEAN_CARGO_TRADELANE        | Sea ship calculation on the base of the Clean Cargo methodology (default) |
| CLEAN_CARGO_TRADELANE_REEFER | Sea ship calculation on the base of the Clean Cargo methodology as reefer container |
| CLEAN_CARGO_PORTPAIR         | Sea ship calculation on the base of the Clean Cargo methodology using port pair|
| CLEAN_CARGO_PORTPAIR_REEFER  | Sea ship calculation on the base of the Clean Cargo methodology as reefer container and using port pair|
    Enum: "NONE", "CLEAN_CARGO_TRADELANE", "CLEAN_CARGO_TRADELANE_REEFER", "CLEAN_CARGO_PORTPAIR", "CLEAN_CARGO_PORTPAIR_REEFER"

  - `accounting.sea.aggregationMethod` (string)
    Defines how to aggregate accounting data for sea transport - per tradelane, per vessel size; or only for specified vessel (vesselPrecise)
    Enum: "TRADELANE", "VESSEL_SIZE", "VESSEL_PRECISE"

  - `accounting.sea.cleanCargoTimeFrame` (string)
    if not provided last available year is set as default
    Example: "2023"

  - `accounting.cooledTransport` (object)
    only for trucks, container trains and Clean Cargo (container ships).

  - `accounting.cooledTransport.value` (boolean, required)
    Example: true

  - `transportChainElements` (array, required)
    Example: [{"elementType":"TRANSPORT","route":{"origin":[{"locationType":"ZIP_CODE","country":"DE","code":"20539"}],"destination":[{"locationType":"ZIP_CODE","country":"DE","code":"30167"}]},"mainCarriage":{"transportMode":"ROAD"}}]

  - `settings` (object)

  - `settings.automaticTranshipmentDetection` (object)
    It is possible to activate the automatic detection and calculation of the emissions
associated to transhipment activities. 
Although this is mandatory as per the ISO 14083, it is not calculated by default
on the EcoTransIT World and has to be activated explicitly by the user

  - `settings.automaticTranshipmentDetection.handlingType` (string, required)
    Key      | Description |
  ---    | --- |
DRY | Dry Bulk |
LIQUID | Liquid Bulk |
PIECE | Piece goods / Break Bulk |
PALLET | Freight on pallets |
CONTAINER | Freight in containers |
RORO | Vehicle based Roll-On Roll-Off |
    Enum: "DRY", "LIQUID", "PIECE", "PALLET", "CONTAINER", "RORO"

  - `settings.automaticTranshipmentDetection.mode` (string, required)
    Key      | Description |
  ---    | --- |
DISABLED | Transhipments are not considered (default) |
ALWAYS | All potential transhipments are considered |
INTERMODAL_CHANGE | Only intermodal transhipments are considered |
    Enum: "DISABLED", "ALWAYS", "INTERMODAL_CHANGE"

  - `settings.useLocationAliasTable` (boolean)
    Defines whether a previously uploaded alias table for locations should be used

  - `settings.blockingList` (object)

  - `settings.blockingList.canals` (array)
    Enum: "KIEL", "SUEZ", "PANAMA"

  - `settings.skipFaultySection` (string)
    The skipFaultySection attribute enables an automatically skip of a section (transport chain element) if there was an
issue, like a wrong locode. This can be useful, if the input data often has issues within the
pre-carriage but the main carriage (e.g. as second section) can be calculated. In this case the
skipFaultySection disables the respective section but calculates the rest of the transport chain 
| Keys   | Values |
| ---    | ---    |
| FIRST  | Skips only the first section if it creates an issue |
| LAST   | Skips only the last section if it creates an issue. |
| BOTH   | Skips the first and/or last section if it creates an issue |
    Enum: "FIRST", "LAST", "BOTH"

  - `settings.output` (object)

  - `settings.output.infoLevel` (string)
    Enum: "STANDARD", "DETAILED"

  - `settings.output.splitCarriage` (object)
    Every change within one of the criteria creates an additional mainCarriage leg in the transport chain element of the response.

  - `settings.output.splitCarriage.frontiers` (boolean)
    Splits the carriage when crossing country borders.

  - `settings.output.splitCarriage.rail` (object)

  - `settings.output.splitCarriage.rail.traction` (boolean, required)
    Splits the carriage on railTraction change. For example if part of the track is not electrified. It is recommended to set this to true
    Example: true

  - `settings.output.createKml` (boolean)
    If true, the response will include a Url to a KML file. The KML file will contain the route of the transport chain elements. 
The route can then be displayed for example in google earth. The shown routing is simplified, while for the calculation the proper routing has been used.

  - `settings.errorHandling` (object)
    Map/dictionary to specify how EcotransIT World should handle errors. 
The key of the map specifies the problem, e.g. "NotMatchingFlightNumber" 
Via option you can specify how to handle the problem.

  - `customDescription` (object)
    any desired information can be defined here (as a map / dictionary of string/string key-value pairs) and will also be shown in the response. 
Can be specified as follows: 
{ 
"someKey": "someValue", 
"anotherKey": "anotherValue" 
}
    Example: {"information1":"Hello","information2":"World!"}

## Response 200 fields (application/vnd.ecotransit.app.v2025r2+json):

  - `transportID` (string)
    Only Informational. Displays transportID as specified earlier in the request.

  - `transportDate` (object)
    Input: Only relevant for sea with routing "ais-based" (default) and air routing 
For longer trips the transportDate shall specify the arrival date
Output: Same as provided in the request or otherwise set to default

  - `transportDate.year` (integer, required)
    year in 4 digit notation
    Example: "2022"

  - `transportDate.month` (integer)
    month as number - e.g. "3" for march
    Example: "3"

  - `transportDate.day` (integer)
    day of the month
    Example: "27"

  - `cargo` (object, required)
    Example: {"unit":"TONS","amount":42}

  - `accounting` (object)
    Only available for air, sea and cooled transport (trucks, container trains and Clean Cargo container ships)

  - `accounting.air` (object)

  - `accounting.air.variant` (string, required)
    | Option   | Description                                           |
|----------|-------------------------------------------------------|
| none     | Belly plane allocation on the base of EN16258(Default) |
| Icao     | Belly plane allocation on the base of ICAO/IATA methodology |
| Skailark | Belly plane allocation on the base of Skailark methodology |
    Enum: "NONE", "ICAO", "SKAILARK"

  - `accounting.sea` (object)

  - `accounting.sea.variant` (string, required)
    | Option                       | Description                                                        |
|------------------------------|--------------------------------------------------------------------|
| none                         | Sea ship calculation on the base of the ETW bottom-up methodology           |
| CLEAN_CARGO_TRADELANE        | Sea ship calculation on the base of the Clean Cargo methodology (default) |
| CLEAN_CARGO_TRADELANE_REEFER | Sea ship calculation on the base of the Clean Cargo methodology as reefer container |
| CLEAN_CARGO_PORTPAIR         | Sea ship calculation on the base of the Clean Cargo methodology using port pair|
| CLEAN_CARGO_PORTPAIR_REEFER  | Sea ship calculation on the base of the Clean Cargo methodology as reefer container and using port pair|
    Enum: "NONE", "CLEAN_CARGO_TRADELANE", "CLEAN_CARGO_TRADELANE_REEFER", "CLEAN_CARGO_PORTPAIR", "CLEAN_CARGO_PORTPAIR_REEFER"

  - `accounting.sea.aggregationMethod` (string)
    Defines how to aggregate accounting data for sea transport - per tradelane, per vessel size; or only for specified vessel (vesselPrecise)
    Enum: "TRADELANE", "VESSEL_SIZE", "VESSEL_PRECISE"

  - `accounting.sea.cleanCargoTimeFrame` (string)
    if not provided last available year is set as default
    Example: "2023"

  - `accounting.cooledTransport` (object)
    only for trucks, container trains and Clean Cargo (container ships).

  - `accounting.cooledTransport.value` (boolean, required)
    Example: true

  - `kmlFile` (string)
    specifies the URL of the KML file that contains the route of the transport chain elements.

  - `notifications` (array)

  - `notifications.key` (string, required)

  - `notifications.level` (string)
    Enum: "INFO", "WARNING"

  - `notifications.category` (string)
    Enum: "LOCATION", "PARAMETER", "INTERNAL", "ROUTING", "ERROR_HANDLING", "CONFIGURATION"

  - `notifications.message` (string, required)
    Example: "Flight number(s) LH123 are related to origin location airport:MUC."

  - `notifications.action` (string)

  - `notifications.values` (object)
    map with values to make message more machine readable
    Example: {"flightNumber":"LH123","originLocation":"MUC"}

  - `resultsPerTransportChainElement` (array, required)

  - `resultsPerTransportChainElement.numberOfTransportChainElement` (string)
    indicating the number of the transport chain element (tce), if there is more than one
    Example: "tce 1 of 3"

  - `resultsPerTransportChainElement.customDescription` (string)
    Informational data as provided in the request by the user.

  - `resultsPerTransportChainElement.preCarriageResults` (array)
    one transportChainElement may have several pre/post/mainCarriageResults, e.g. when a flight requires stopovers

  - `resultsPerTransportChainElement.mainCarriageResults` (array, required)
    one transportChainElement may have several pre/post/mainCarriageResults, e.g. when a flight requires stopovers

  - `resultsPerTransportChainElement.postCarriageResults` (array)
    one transportChainElement may have several pre/post/mainCarriageResults, e.g. when a flight requires stopovers

  - `customDescription` (object)
    customerDescription as provided in the original request

  - `debug` (object)
    debug output only visible to EcoTransIT-Staff members

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    a URI reference that identifies the problem via an errorKey. URI is not resolvable at the moment, but might be in the future
    Enum: "LOCATION", "PARAMETER", "INTERNAL", "ROUTING", "ERROR_HANDLING", "CONFIGURATION"

  - `title` (string, required)
    a short, human-readable summary of the error
    Example: "Location not found"

  - `status` (integer, required)
    indicating the HTTP status code
    Example: 400

  - `detail` (string, required)
    human-readable explanation specific to this occurrence of the problem
    Example: "could not find Location for IATA code: ZZZ"

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem
    Example: "/calculateTransport"

  - `action` (string)
    proposed action to solve the problem
    Example: "Verify location existence or define another location."

  - `timestamp` (string)
    date and time (in UTC) when the error occurred (YYYY-MM-DD)
    Example: "2024-06-30T06:39:25Z"

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    a URI reference that identifies the problem via an errorKey. URI is not resolvable at the moment, but might be in the future
    Enum: "LOCATION", "PARAMETER", "INTERNAL", "ROUTING", "ERROR_HANDLING", "CONFIGURATION"

  - `title` (string, required)
    a short, human-readable summary of the error
    Example: "Location not found"

  - `status` (integer, required)
    indicating the HTTP status code
    Example: 400

  - `detail` (string, required)
    human-readable explanation specific to this occurrence of the problem
    Example: "could not find Location for IATA code: ZZZ"

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem
    Example: "/calculateTransport"

  - `action` (string)
    proposed action to solve the problem
    Example: "Verify location existence or define another location."

  - `timestamp` (string)
    date and time (in UTC) when the error occurred (YYYY-MM-DD)
    Example: "2024-06-30T06:39:25Z"