# Shipment route

> The Container Tracking API response holds three levels of route data to draw a shipment on a map — the route block for POL and POD, the locations list for every port, and routeData.routeSegments for a possible path.

To display the route of a shipment in your own application, parse the response of the Container Tracking API endpoint [`GET /shipment`](/en/api/container-tracking/reference/get-shipment-detail), retrieve the coordinates you need and pass them to a map tool. The response offers three levels of detail: the `route` block for the key locations, the `locations` list for every location, and `routeData.routeSegments` for a possible path between them.

## Port of loading and port of discharge

To display only the port of loading (POL) and the port of discharge (POD), use the `route` block of the response. It is a simplified view of the shipment made of four locations:

- `prepol` — the first location of the shipment, before the port of loading;
- `pol` — the port of loading;
- `pod` — the port of discharge;
- `postpod` — the last location of the shipment, after the port of discharge.

Each one carries the location, with its coordinates, and a date.

::callout{type="warning"}
The date of each `route` location is the date of the first event known at that location. For the POL it is most often the gate in of the container; for the POD it is usually the vessel arrival. For the date of a specific event, read the events in `containers[].events`.
::

```json
{
  "route": {
    "prepol": {
      "location": {
        "name": "Elland",
        "state": "England",
        "country": "United Kingdom",
        "countryCode": "GB",
        "locode": "GBEND",
        "coordinates": { "lat": 53.41, "lng": -1.5 },
        "timezone": "Europe/London"
      },
      "date": "2024-08-12T05:00:00+01:00",
      "actual": true,
      "predictiveEta": null
    },
    "pol": {
      "location": {
        "name": "LIVERPOOL",
        "state": "England",
        "country": "United Kingdom",
        "countryCode": "GB",
        "locode": "GBLIV",
        "coordinates": { "lat": 53.4224, "lng": -3.00837 },
        "timezone": "Europe/London"
      },
      "date": "2024-08-13T04:18:00+01:00",
      "actual": true,
      "predictiveEta": null
    },
    "pod": {
      "location": {
        "name": "MONTREAL",
        "state": "Quebec",
        "country": "Canada",
        "countryCode": "CA",
        "locode": "CAMTR",
        "coordinates": { "lat": 45.557, "lng": -73.5167 },
        "timezone": "America/Toronto"
      },
      "date": "2024-08-23T06:34:00-04:00",
      "actual": true,
      "predictiveEta": null
    },
    "postpod": {
      "location": {
        "name": "VANCOUVER",
        "state": "British Columbia",
        "country": "Canada",
        "countryCode": "CA",
        "locode": "CAVAN",
        "coordinates": { "lat": 49.3036, "lng": -123.048 },
        "timezone": "America/Vancouver"
      },
      "date": "2024-09-06T02:48:01-07:00",
      "actual": false,
      "predictiveEta": null
    }
  }
}
```

## Every location of the shipment

To display every location the shipment visits, transhipment ports included, and to label them or link them in order, use the `locations` list of the response. It gives every location of the shipment, with its coordinates.

::callout{type="info"}
Shipping lines rarely include intermediate port calls in their container tracking data, so the `locations` list of the Container Tracking API rarely contains them.
::

```json
{
  "locations": [
    {
      "name": "LIVERPOOL",
      "state": "England",
      "country": "United Kingdom",
      "countryCode": "GB",
      "locode": "GBLIV",
      "coordinates": { "lat": 53.4224, "lng": -3.00837 },
      "timezone": "Europe/London"
    },
    {
      "name": "Elland",
      "state": "England",
      "country": "United Kingdom",
      "countryCode": "GB",
      "locode": "GBEND",
      "coordinates": { "lat": 53.41, "lng": -1.5 },
      "timezone": "Europe/London"
    },
    {
      "name": "MONTREAL",
      "state": "Quebec",
      "country": "Canada",
      "countryCode": "CA",
      "locode": "CAMTR",
      "coordinates": { "lat": 45.557, "lng": -73.5167 },
      "timezone": "America/Toronto"
    },
    {
      "name": "Brampton",
      "state": "Ontario",
      "country": "Canada",
      "countryCode": "CA",
      "locode": "CABRP",
      "coordinates": { "lat": 43.6834, "lng": -79.7663 },
      "timezone": "America/Toronto"
    },
    {
      "name": "VANCOUVER",
      "state": "British Columbia",
      "country": "Canada",
      "countryCode": "CA",
      "locode": "CAVAN",
      "coordinates": { "lat": 49.3036, "lng": -123.048 },
      "timezone": "America/Vancouver"
    }
  ]
}
```

## Possible route of the shipment

To display a route the vessel could follow from the port of loading to the port of discharge, stops at transhipment ports included, use `routeData.routeSegments`. It is returned when the request parameter `route` is `true`, its default value.

The route segments are a succession of paths between locations. Each segment holds a `path` — an array of coordinates — and a `routeType`, `SEA` or `LAND`. Together they draw a possible route of the shipment, free to display on a map.

::callout{type="info"}
The route segments take into account the latest data known about the voyage of the container, not the current position of the vessel. The current position is given by `routeData.coordinates`.
::

The excerpt below keeps the first coordinates of one segment out of five; a real path holds many more points.

```json
{
  "routeData": {
    "routeSegments": [
      {
        "path": [
          { "lat": 53.41042, "lng": -2.97761 },
          { "lat": 53.40698, "lng": -2.88649 },
          { "lat": 53.40112, "lng": -2.79663 }
        ],
        "routeType": "LAND"
      }
    ]
  }
}
```

## Crossing the 180th meridian

Map tools such as Mapbox draw a route crossing the Pacific Ocean the wrong way round: between a point at longitude `135` and a point at longitude `-157`, the line runs across the whole map instead of crossing the 180th meridian.

To avoid it, in a path that crosses the 180th meridian, add 360 to the longitude of every point where it becomes negative. The free test shipment `ZZZZ0000000` lets you test the correction.

This path, as returned by the API:

```json
{
  "path": [
    { "lat": 33.2347, "lng": 135.7899 },
    { "lat": 37.12, "lng": -157.5674 }
  ]
}
```

becomes, once corrected:

```json
{
  "path": [
    { "lat": 33.2347, "lng": 135.7899 },
    { "lat": 37.12, "lng": 202.4326 }
  ]
}
```

The Mapbox tutorial [Draw a line across the 180th meridian](https://docs.mapbox.com/mapbox-gl-js/example/line-across-180th-meridian/) shows the same correction in JavaScript.
