This article explains how to retrieve a location code (e.g., terminal or site code such as 9010 or 0705) from shipment events when working with the ShipmentData API. It focuses on identifying where the data resides in the response and how to interpret it.

Authentication Prerequisites

Before calling the ShipmentData API, you need an access token:

• Auth URL: https://account.nshiftportal.com/idp/connect/token
• Grant type: client_credentials
• Scope: public_api_portal_shipment_data

Once you exchange your client_id and client_secret for a token, you’ll use that token in the Authorization: Bearer header for your API calls.

Step 1: Get an Access Token

Use cURL to obtain your access token:

curl -X POST 'https://account.nshiftportal.com/idp/connect/token'   
   -H 'Content-Type: application/x-www-form-urlencoded'   
   -d 'grant_type=client_credentials'   
   -d 'client_id=<YOUR_CLIENT_ID>'   
   -d 'client_secret=<YOUR_CLIENT_SECRET>'

Example response:

{
  "access_token": "<JWT>",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "public_api_portal_shipment_data"
}

Step 2: Query Shipment Data by Barcode

To retrieve events that may contain location codes, use the Aggregated-by-Barcode endpoint.

curl -X POST 'https://api.nshiftportal.com/track/shipmentdata/Operational/Shipments/Aggregated/ByBarcode'   
-H "Authorization: Bearer <ACCESS_TOKEN>"   
-H "Content-Type: application/json"   
-d '{
    "query": "<BARCODE>",
    "startDate": "2025-08-24T00:00:00Z",
    "endDate": "2025-08-26T23:59:59Z",
    "pageSize": 20,
    "pageIndex": 0,
    "installationTags": [],
    "actorTags": [],
    "carrierTags": [],
    "dateRangeSource": 1
}'

The response includes shipment-level and package-level information, including events.

Where the Location Code Appears

The location field is included in some package-level events. It typically represents a carrier’s internal site or terminal code.

• Package-level events: shipment.lines[].packages[].events[].location (preferred)

When present, location appears alongside:

• cityName
• postalCode
• country

• Optionally, coordinates with latitude and longitude

   

Example: Response Snippet

Below is a simplified example of a response showing a package event with a location code:

[
  {
    "shipment": {
      "lines": [
        {
          "packages": [
            {
              "number": "00073123400271295954",
              "events": [
                {
                  "uuid": "b4e5a99b-0aee-41a2-11dd-b1e539a1a4d1",
                  "configurationName": "The delivery of the shipment item is in progress",
                  "normalizedStatusId": 2001,
                  "normalizedStatusName": "Out for delivery",
                  "date": "2025-08-26T09:16:14+02:00",
                  "cityName": "Aalborg",
                  "postalCode": "9000",
                  "country": "Denmark",
                  "location": "9010"
                }
              ]
            }
          ]
        }
      ]
    }
  }
]

In this example:

• The location code is 9010
• The event status is Out for delivery
• City and postal code provide additional context (Aalborg, 9000)

Interpreting the Location Code

• The location value is carrier-specific, not a postal code.
• Codes like 9010 or 0705 are identifiers for terminals or sorting hubs.
• Combine with cityName and postalCode to give users a clearer picture.