apis
/
collection and delivery
/
collection and delivery calculation

EcoTransIT World REST-Api (2025r3.0.10)

Official website of EcoTransIT World

Rate limit

Please Note: this Api uses rate limits: max. 100 requests/second and max 7 simultaneous connections are allowed!
Exceeding the rate limit will result in a http 429 error ("too many requests")

Authorization

EcoTransIT Rest Api uses the "Authorization Code Flow" for Authentication.
In the Header of your Api request set the authorization to Bearer followed by an access_token (see below how to get the token) like in the following curl request:

curl -X POST https://customer-name.ecotransit.org/etw-rest/calculateTransport \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer xxx-some-example-access-token-yyy' \
     -d '{"key": "value"}'

Authentication Server to get the access token from: https://customer-name.ecotransit.org/realms/ETW/protocol/openid-connect/token

Get Access Token

Please note: in order to get an access token and send requests to the REST API you need to contact our team to get a test account.
Visit get Access Token and provide username and password as given to you by the EcoTransIT staff.
After successful login you will receive an access token and a refresh token. Use this access token as bearer token in your calculateTransport request (see first code snippet in Authorization section)
Please note that the access token expires after a while. You can use the refresh token to get a new access token, like in the following curl request.

curl -X POST https://customer-name.ecotransit.org/realms/ETW/protocol/openid-connect/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "client_id=webservice-rest" \
     -d "client_secret=<my-client-secret>" \
     -d "grant_type=refresh_token" \
     -d "refresh_token=<my-refresh-token>"

⚠️ Warning: Store the refresh token at a safe place as it contains sensitive information!!

OpenId Endpoint Overview

An overview of the OpenId Endpoint Overview of the authorization server can be found here

Download OpenAPI description
OpenApi.json
OpenApi.yaml
Overview
E-mail

support@ecotransit.world

License

IVE Legal notice

Languages
Servers

https://customer-name.ecotransit.org/

calculate transport

calculate Emissions for specified Transport

Operations

Info

get general Information about the api

Operations

collection and delivery

Operations

collection and delivery calculation

Request

calculate a collection and delivery round ("milkrun") from json input

Bodyapplication/jsonrequired
accountingobject(accountingCoDe)
transportChainElementsArray of objects(transportChainElement)>= 2 itemsrequired

The shipmentIds of the loads/unloads of the first transportChainElement will be ommitted because the emissionPercentage for them will always be 0 by definition.

Example: [{"location":{"locationType":"ZIP_CODE","country":"DE","code":20539},"load":[{"cargo":{"unit":"TONS","amount":20}}]},{"location":{"locationType":"ZIP_CODE","country":"DE","code":30167},"unload":[{"cargo":{"unit":"TONS","amount":15},"freightUnitIdentifier":"terminalhannoverCustomerA","listEmissionsInResponse":true},{"cargo":{"unit":"TONS","amount":5},"freightUnitIdentifier":"terminalhannoverCustomerB","listEmissionsInResponse":true}]}]
transportChainElements[].​locationobject(location)
transportChainElements[].​loadArray of objects(distributionLoad)
transportChainElements[].​unloadArray of objects(distributionLoad)
transportChainElements[].​carriageParametersobject(ROAD)
settingsobject(settings)
curl -i -X POST \
  https://customer-name.ecotransit.org/etw-rest/calculateCollectionAndDelivery \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "transportChainElements": [
      {
        "location": {
          "locationType": "ZIP_CODE",
          "country": "DE",
          "code": 20539
        },
        "load": [
          {
            "cargo": {
              "unit": "TONS",
              "amount": 20
            }
          }
        ]
      },
      {
        "location": {
          "locationType": "ZIP_CODE",
          "country": "DE",
          "code": 30167
        },
        "unload": [
          {
            "cargo": {
              "unit": "TONS",
              "amount": 15
            },
            "freightUnitIdentifier": "terminalhannoverCustomerA",
            "listEmissionsInResponse": true
          },
          {
            "cargo": {
              "unit": "TONS",
              "amount": 5
            },
            "freightUnitIdentifier": "terminalhannoverCustomerB",
            "listEmissionsInResponse": true
          }
        ]
      }
    ],
    "settings": {
      "showRoute": "true"
    }
  }'

Responses

Successful operation

Bodyapplication/vnd.ecotransit.app.v2025r2+json
emissionsPerFreightUnitArray of objects(freightUnitResult)

Note that the emissions for the load/undload elements of the first transportChainElement from the request are not shown in the response because they are always 0 by definition!

transportOperationCategoryArray of objects(tceDistributionResult)

List of transport chain elements (TCE) showing the emissions for each leg for the whole freight

kmlFilestring(uri)

specifies the URL of the KML file that displays the route taken by the truck

Response
application/vnd.ecotransit.app.v2025r2+json
{
  "emissionsPerFreightUnit": [
    { … }
  ],
  "transportOperationCategory": [
    { … }
  ],
  "kmlFile": "http://example.com"
}