SeaRates to Vizion Container Tracking API

Architectural shift

In SeaRates every request is a fresh lookup, and you own the schedule, the cache, and the deduplication. In Vizion you create a reference once and Vizion keeps it updated. Read those updates by push to a callback URL or by pull from the updates endpoint. Both return the same payload, so every mapping below applies either way.

Quick comparison

The API key moves from a query parameter to the X-API-Key request header. SeaRates keys do not carry over. Contact Vizion sales for a key.

curl -X GET "https://tracking.searates.com/tracking\
?api_key=YOUR_SEARATES_KEY\
&number=MRKU9465770\
&sealine=MAEU\
&type=CT"

curl -X POST https://prod.vizionapi.com/references \
  -H "X-API-Key: YOUR_VIZION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"container_id": "MRKU9465770",
       "carrier_code": "MAEU"}'

Replace per-request lookups with a reference lifecycle. Vizion decides when to check each data source and makes every new update available by push and by pull.

POST /references
{
  "container_id": "MRKU9465770",
  "carrier_code": "MAEU",
  "callback_url": "https://your-server.com/vizion-webhook"
}

POST https://your-server.com/vizion-webhook

GET /references/{referenceId}/updates

DELETE /references/{referenceId}

One SeaRates poll request becomes one reference creation.

SeaRates stores locations, vessels, and facilities in top-level arrays referenced by integer ID. Vizion inlines full objects on each milestone. Your ID-resolution code can be deleted.

SeaRates event.description values are free text and vary by carrier. Vizion maps them to a standardized set of roughly 130 descriptions and keeps the carrier's original string in raw_description. SeaRates strings are case-insensitive, and new ones appear over time.

The milestone lists live in the API docs. Core milestones are the eight Vizion makes an effort to provide for every reference. Standardized milestones are the full set your SeaRates descriptions resolve into.

Both APIs identify carriers by SCAC, and most codes are identical. Vizion supports 61 carriers in total; 29 of those have a dedicated carrier_code value.

Optional. SeaRates has no webhooks. Vizion can POST updates to an HTTPS endpoint you expose. Skip this section if you are staying on the polling path. Use callback_url to receive everything, or the webhooks array to subscribe to specific events and sources.

POST /references
{
  "container_id": "MRKU9465770",
  "carrier_code": "MAEU",
  "callback_url": "https://your-server.com/vizion-webhook"
}

POST /references
{
  "container_id": "MRKU9465770",
  "carrier_code": "MAEU",
  "webhooks": [
    {
      "callback_url": "https://your-server.com/vizion-webhook",
      "events": ["reference_update", "estimated_event_alerts"],
      "sources": ["carrier", "terminal"]
    }
  ]
}

Payload structure

{
  "id": "update-uuid",
  "status": "data_received",
  "reference_id": "ref-uuid",
  "organization_id": "org-uuid",
  "created_at": "2026-08-11T14:30:00.000Z",
  "payload": {
    "container_id": "MRKU9465770",
    "carrier_scac": "MAEU",
    "container_iso": "40' HIGH CUBE",
    "origin_port": { "name": "Shanghai", "country": "China", "unlocode": "CNSHA", ... },
    "destination_port": { "name": "Los Angeles", "country": "United States", "unlocode": "USLAX", ... },
    "milestones": [
      {
        "timestamp": "2026-08-10T08:14:00.000+08:00",
        "description": "Loaded on vessel",
        "raw_description": "Loaded to Vessel",
        "vessel": "MAERSK SELETAR",
        "vessel_imo": "9778791",
        "voyage": "234W",
        "planned": false,
        "mode": "Vessel",
        "source": "carrier",
        "location": {
          "name": "Shanghai",
          "country": "China",
          "unlocode": "CNSHA",
          "geolocation": { "latitude": 31.2304, "longitude": 121.4737 }
        }
      }
    ]
  }
}

POST /webhooks/trigger/test
{ "callback_url": "https://your-server.com/vizion-webhook" }

Features with no SeaRates equivalent.

SeaRates features that work differently, or that Vizion handles internally instead of exposing.

SeaRates returns HTTP 200 for both success and failure and puts the error in the envelope. Vizion uses standard HTTP status codes. Replace checks on response.status == "error" and message-string matching with status-code checks.

Migration checklist

Every migration does the base path. Then pick one branch. The polling path is shorter because there is no endpoint for Vizion to call.

API documentation