---
title: "Get the map data of a shipment"
method: GET
path: "/shipments/{shipment_id}/map"
tags: ["Shipments"]
---

# Get the map data of a shipment

`GET /shipments/{shipment_id}/map`

## Request

- Base URL: `https://trackberry.com/api/v1`
- URL: `https://trackberry.com/api/v1/shipments/{shipment_id}/map`
- Auth: HTTP bearer

Use this to draw a shipment's voyage on a map: the sea or air route split into the part already travelled and the part remaining, the carrier's ports, the vessel's upcoming calls, the recorded position trail and the vessel marker. It is the data behind the map on the shipment's page in Trackberry. Long lines are thinned and coordinates rounded to four decimals. When the carrier has published nothing to draw, `map` has the same shape and draws the shipment's legs between the places its own located tracking events put their ends; it is null only when nothing can be placed. Not paged.

## Path parameters

- `shipment_id` string, required

## Headers

- `Trackberry-Version` string

## Response `200`

The map data of the shipment.

- ShipmentMap: The data to draw one shipment's voyage on a map.
  - `object` 'shipment_map', required: Always `shipment_map`.
  - `shipment_id` string, required: The shipment this map belongs to.
  - `map` ShipmentMapData, required: What a map draws for one shipment. The keys are camelCase because they are the names the shipment page's own map reads. All longitudes share one continuous scale: they can run past 180 or below -180 when a route crosses the antimeridian, which map libraries draw correctly.
    - `routeSegments` object[], required: The route as lines, one per leg, in travel order.
      - `path` MapPoint[], required: The points of the line, in travel order.
        - `lat` number, required: Latitude in degrees.
        - `lng` number, required: Longitude in degrees. Not confined to -180 to 180; see `ShipmentMapData`.
      - `routeType` string, nullable, required: What the line crosses, for example `SEA`, `AIR` or `LAND`; `RAIL` marks an overland leg (rail or road) drawn between its two ends. Null when unknown.
    - `locations` object[], required: The carrier's ports on the route. Each item has `name`, `type` (for example `pol` for the port of loading, `pod` for the port of discharge or `transshipment`), `locode`, `country` and `coordinates` (a point with `lat` and `lng`); a key the carrier did not publish is left out.
    - `vesselCalls` object[], required: Upcoming calls of the vessel at ports the carrier's route does not name. Each item has `name`, `coordinates` and, when known, `locode` and `date` (for example `Due 12 Oct`). The vessel's own schedule, not the carrier's.
    - `routeSplit` object, required: Where the line stops being travelled and starts being remaining: `segmentIndex` and `pointIndex` name the point in `routeSegments`, `position` is its coordinates. An empty object when nothing says how far the cargo has come, in which case the whole route is remaining.
    - `positionTrail` object[], required: The vessel's recorded positions, oldest first.
      - `lat` number, required: Latitude in degrees.
      - `lng` number, required: Longitude in degrees.
      - `label` string, required: How long ago it was recorded, in words such as `about 3 hours ago`.
    - `vesselMarker` object, required: Where to put the vessel (or aircraft) marker: `lat`, `lng`, `source` (`fix` for a recorded position, `reported` for the carrier's estimate along its route, `port` for the last port seen when the cargo is on land), `seenAt` (how long ago, for a recorded position) and `heading` in compass degrees (null when unknown). An empty object when there is no position.
    - `vesselName` string, nullable, required: The vessel or flight the carrier names last. Null when it names none.
    - `airRoute` boolean, required: True when every line of the route is an air leg, so the marker is an aircraft.

## Other responses

- `400`: A parameter or header is invalid (`invalid_parameter`, with `param` naming it), a customer link cannot be made for this shipment (`not_shareable`), an uploaded file is empty, over 50 MB or of a type Trackberry does not read (`file_empty`, `file_too_large`, `unsupported_file_type`), an upload's container number is on more than one live shipment (`ambiguous_container`), an `Idempotency-Key` was already used for a different request (`idempotency_key_reused`) or `Trackberry-Version` names an unpublished version (`invalid_version`, with `param` set to `Trackberry-Version`). A parameter that must be a single value but was sent as an array or hash (`status[]=x`, `q[a]=1`) is also a 400.
- `401`: No token was sent (`missing_token`) or the token is wrong, expired, revoked, or its user left the organization (`invalid_token`). The response has a `WWW-Authenticate` header.
- `403`: The token may not do this. `insufficient_scope`: a write endpoint was called with a read-only token. `read_only_member`: a write endpoint was called by a token whose owner is now a read-only member of the organization. `revoke_not_allowed`: the link can only be revoked by an admin or by the member who made it. `billing_blocked`: an upload needed a new shipment and the organization's billing does not allow one.
- `404`: No such object in this organization (`resource_missing`). This is also the answer for an id of another organization, an id with the wrong prefix, or a malformed id, so the API never confirms that an object exists elsewhere.
- `429`: A rate limit was hit (`rate_limited`). Wait the number of seconds in `Retry-After`. A BI feed answers the same way (`feed_in_progress`) when another feed for the organization is still being produced.

---

[API](https://skmtc.dev/trackberry/apis/trackberry-api.md) · [All operations](https://skmtc.dev/trackberry/apis/trackberry-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trackberry/apis/trackberry-api/revisions/be06ee7c17f3?raw)