# Maersk Tracking

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/maersk/tracking` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/maersk-tracking |

## Description

Track a Maersk container or BOL: origin, destination, current milestone and full transport-plan events via browser rendering.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/maersk/tracking' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Container MMAU1155207 (Paranagua to Al Khoms)

```json
{
  "url": "https://www.maersk.com/tracking/MMAU1155207",
  "events": [
    {
      "date": "23 Mar 2026 16:29",
      "event": "Gate out Empty",
      "location": {
        "city": "Paranagua",
        "facility": "Maersk Depot Paranagua"
      },
      "position": 1,
      "is_current": false
    },
    {
      "date": "02 Apr 2026 18:49",
      "event": "Load on MAERSK LOTA / 614N",
      "vessel": "MAERSK LOTA / 614N",
      "position": 3,
      "is_current": false
    }
  ],
  "origin": "PARANAGUA",
  "destination": "AL KHOMS",
  "current_event": {
    "date": "02 Jun 2026 14:00",
    "event": "Empty container return",
    "position": 16,
    "is_current": true
  },
  "tracking_type": "Container",
  "tracking_number": "MMAU1155207"
}
```

## Documentation

## Overview
The **Maersk Tracking** endpoint returns the transport plan for a Maersk container or bill of lading: origin, destination, current milestone and the full event timeline.

Maersk tracking is a JavaScript SPA. Static HTML is empty, so this endpoint uses **browser rendering** on `maersk.com`, waits for the transport plan, and parses the rendered DOM. It does **not** call the official Maersk API.

Costs **2 credits** per call (browser rendering). `maersk.com` must be authorized for rendering.

## Quickstart
```
GET https://api.piloterr.com/v2/maersk/tracking?query=MMAU1155207
GET https://api.piloterr.com/v2/maersk/tracking?query=https://www.maersk.com/tracking/MMAU1155207
```

Via POST:
```
POST https://api.piloterr.com/v2/maersk/tracking
Content-Type: application/json

{"query": "MMAU1155207", "return_page_source": false}
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Container / BOL number, or full Maersk tracking URL |
| `return_page_source` | boolean | no | Return rendered HTML as `{"result": "..."}` instead of structured JSON (default: `false`) |

## Input formats
| Format | Example | Notes |
|---|---|---|
| Tracking number | `MMAU1155207` | Resolved to `https://www.maersk.com/tracking/{number}` |
| Full URL | `https://www.maersk.com/tracking/MMAU1155207` | Used as-is |
| Localized URL | `https://www.maersk.com/fr-fr/tracking/...` | Accepted when passed in full |

## Response fields
| Field | Type | Description |
|---|---|---|
| `tracking_number` | string | Container or document number |
| `tracking_type` | string | e.g. `Container` |
| `origin` | string | Origin port / city |
| `destination` | string | Destination port / city |
| `url` | string | Tracking page URL used |
| `current_event` | object | Current milestone (`position`, `event`, `date`, `is_current`) |
| `events` | array | Full transport plan, oldest first |
| `events[].position` | integer | Step index |
| `events[].event` | string | Milestone label |
| `events[].date` | string | Event date when shown |
| `events[].location` | object | `city` / `facility` when shown |
| `events[].vessel` | string | Vessel / voyage when mentioned in the label |
| `events[].is_current` | boolean | `true` for the current step |

## Error codes
| Code | Meaning |
|---|---|
| `400` | Empty or invalid `query` |
| `404` | No tracking data found in the rendered page |
| `500` | Rendering failed after retries |

## Notes
- One request = one tracking number (no pagination)
- A bare number always resolves to the English tracking URL on `maersk.com`
- Parsing relies on the rendered transport plan DOM

## Main use cases
- Track container milestones for logistics ops
- Feed ETA / event history into TMS or ERP workflows
- Alert when the current event changes (gate out, vessel departure, empty return, ...)