Create a Shipment

In this tutorial we create a shipment which starts from Tampere, and goes to Berlin Brandenburg via Helsinki by road. We are getting an updated ETA prediction along the route.

Prerequisites

Log in user

Create geofences

Create three geofences for Tampere-Pirkkala, Helsinki, and Berlin Brandenburg airports.

To create a geofence, send a request to the geofences endpoint.

curl -X POST \
    'https://{tcHost}/geofences/v2' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
        "name":"Tampere–Pirkkala Airport",
        "description":"Area around Tampere–Pirkkala airport",
        "type":"circle",
        "definition": {
            "center": {
                "lat": "61.415278",
                "lng": "23.587778"
            },
            "radius": 3000
        }
    }'

{
  "message": "created",
  "id": "7d5ef384-a0bb-4c32-a0f2-d6ee2b761483"
}

curl -X POST \
    'https://{tcHost}/geofences/v2' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
        "name":"Helsinki Airport",
        "description":"Area around Helsinki airport",
        "type":"circle",
        "definition": {
            "center": {
                "lat": "60.317222",
                "lng": "24.963333"
            },
            "radius": 3000
        }
    }'

{
  "message": "created",
  "id": "6e551fae-2687-11ec-af55-00155ddd7ddb"
}

curl -X POST \
    'https://{tcHost}/geofences/v2' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
        "name":"Berlin Brandenburg airport",
        "description":"Area around Berlin Brandenburg airport",
        "type":"circle",
        "definition": {
            "center": {
                "lat": "52.366667",
                "lng": "13.503333"
            },
            "radius": 3000
        }
    }'

{
  "message": "created",
  "id": "c20df606-281d-11ec-90fc-00155ddd7ddb"
}

Create locations

Create three locations for Tampere-Pirkkala, Helsinki, and Berlin Brandenburg airports, and assign the geofences that were created in the previous section to the corresponding locations. To create a location, send a request to the locations endpoint.

curl -X POST \
    'https://{tcHost}/locations/v4' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
        "name":"Tampere–Pirkkala airport"
        "description":"Tampere–Pirkkala airport"
        "location": {
            "lat": "61.415278",
            "lng": "23.587778"
        },
        "address": {
            "street":"Tornikaari 50",
            "city":"Pirkkala",
            "postalCode":"33960",
            "country":"Finland"
        },
        "geofenceId":"7d5ef384-a0bb-4c32-a0f2-d6ee2b761483"
    }'

{
  "locationId": "LOC-f79d965d-9124-446d-b0b4-f71ae793f602"
}

curl -X POST \
    'https://{tcHost}/locations/v4' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
        "name":"Helsinki airport"
        "description":"Helsinki airport"
        "location": {
            "lat": "60.317222",
            "lng": "24.963333"
        },
        "address": {
            "street":"Lentoasemantie 1",
            "city":"Vantaa",
            "postalCode":"01530",
            "country":"Finland"
        },
        "geofenceId":"6e551fae-2687-11ec-af55-00155ddd7ddb"
    }'

{
  "locationId": "LOC-7e814132-2821-11ec-ba1d-00155ddd7ddb"
}

curl -X POST \
    'https://{tcHost}/locations/v4' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
        "name":"Berlin Brandenburg airport"
        "description":"Berlin Brandenburg airport"
        "location": {
            "lat": "52.366667",
            "lng": "13.503333"
        },
        "address": {
            "street":"Willy-Brandt-Platz",
            "city":"Schönefeld",
            "postalCode":"12529",
            "country":"Germany"
        },
        "geofenceId":"c20df606-281d-11ec-90fc-00155ddd7ddb"
    }'

{
  "locationId": "LOC-878c8e9e-2821-11ec-8fc2-00155ddd7ddb"
}

Create shipment

Create a shipment, assigning the locations to the segments of the shipment. The trackingId refers to the claimed device which is assigned to all the segments of the shipment. As the locations were already assigned with the geofences and the device is being assigned to the segments, the segment state transitions will be automated. The autoStart is set true, and therefore the shipment is set to start once the device leaves the geofence of the first location, which corresponds to the origin of the shipment. Note that the shipment transportation mode is road (as indicated by the "transportMode":"truck" property). To create a shipment, send a request to the shipments endpoint.

curl -X POST \
    'https://{tcHost}/shipments/v4' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
        "name":"From Tampere-Pirkkala to Berlin Brandenburg",
        "description":"A shipment from the Tampere-Pirkkala airport to the Berlin Brandenburg airport",
        "autoStart": "true",
        "segments": [
            {
                "name":"From Tampere-Pirkkala to Helsinki",
                "description":"Origin of the shipment",
                "transportMode":"truck",
                "trackingId":"{trackingId}",
                "origin":"LOC-f79d965d-9124-446d-b0b4-f71ae793f602",
                "destination":"LOC-7e814132-2821-11ec-ba1d-00155ddd7ddb",
                "providedEtd":"2021-10-01T06:30:00Z",
                "providedEta":"2021-10-01T07:30:00Z"
            },
            {
                "name":"Dwelling at Helsinki",
                "description":"Waypoint of the shipment where shipment dwells",
                "transportMode":"undefined",
                "trackingId":"{trackingId}",
                "origin":"LOC-7e814132-2821-11ec-ba1d-00155ddd7ddb",
                "destination":"LOC-7e814132-2821-11ec-ba1d-00155ddd7ddb",
                "providedEtd":"2021-10-01T06:30:00Z",
                "providedEta":"2021-10-01T22:45:00Z"
            },
            {
                "name":"From Helsinki to Brandenburg",
                "description":"Destination of the shipment",
                "transportMode":"truck",
                "trackingId":"{trackingId}",
                "origin":"LOC-7e814132-2821-11ec-ba1d-00155ddd7ddb",
                "destination":"LOC-878c8e9e-2821-11ec-8fc2-00155ddd7ddb",
                "providedEtd":"2021-10-01T22:45:00Z",
                "providedEta":"2021-10-02T01:15:00Z"
            }
        ],
        "providedEtd":"2021-10-01T06:30:00Z",
        "providedEta":"2021-10-02T01:15:00Z"
    }'

{
  "shipmentId": "SHP-a79ee6bf-436c-4684-9be6-48b084a94228"
}

Get shipment details with ETA prediction

Shipment details, along with predicted ETA, can be obtained via the Get shipment details API call. The predicted ETA is available for the entire shipment, which is defined by calculatedEta shipment property, and for each shipment segment separately, defined by the calculatedEtd and calculatedEta segment properties.

Create shipment plan from a shipment

The shipment can be also transformed into a shipment plan from which new shipments can be created.

curl -X POST \
    'https://{tcHost}/shipments/v4/plans' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
        "shipmentId":"SHP-a79ee6bf-436c-4684-9be6-48b084a94228"
    }'

{
  "shipmentPlanId": "SHPP-736b28d4-2836-11ec-91b6-00155ddd7ddb"
}

The created shipments will be available via the Shipment Tracking web.