Create a shipment

In this tutorial we create a shipment which starts from Tampere-Pirkkala airport, and goes to Berlin Brandenburg airport through Helsinki airport by airplane.

Prerequisites

A valid HERE account user
A valid Tracking project
A claimed device

Log in user

Create geofences

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

curl -X POST \
    'https://tracking.api.here.com/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://tracking.api.here.com/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://tracking.api.here.com/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.

curl -X POST \
    'https://tracking.api.here.com/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://tracking.api.here.com/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://tracking.api.here.com/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.

curl -X POST \
    'https://tracking.api.here.com/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":"air",
                "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":"air",
                "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"
}

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://tracking.api.here.com/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.

Create a Shipment