API documentation. How to ask, and what comes back.

1Quick start

Every request goes to https://api.shipmenttrackingapi.com over HTTPS, and every answer is JSON.

First, get a key: sign in to the console with Google and create one. It is free. The key is shown once, so copy it then. Next, send a carrier and an array of tracking numbers.

curl https://api.shipmenttrackingapi.com/v1/track \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"carrier":"ups","trackingNumbers":["YOUR_TRACKING_NUMBER"]}'

const res = await fetch("https://api.shipmenttrackingapi.com/v1/track", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ carrier: "ups", trackingNumbers: ["YOUR_TRACKING_NUMBER"] }),
});

const body = await res.json();
if (!body.success) throw new Error(body.error.code);
for (const r of body.data.results) {
  console.log(r.trackingNumber, r.status ?? r.error.code);
}

import requests

res = requests.post(
    "https://api.shipmenttrackingapi.com/v1/track",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"carrier": "ups", "trackingNumbers": ["YOUR_TRACKING_NUMBER"]},
)

body = res.json()
if not body["success"]:
    raise SystemExit(body["error"]["code"])
for r in body["data"]["results"]:
    print(r["trackingNumber"], r.get("status") or r["error"]["code"])

<?php
$ch = curl_init("https://api.shipmenttrackingapi.com/v1/track");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode(["carrier" => "ups", "trackingNumbers" => ["YOUR_TRACKING_NUMBER"]]),
]);

$body = json_decode(curl_exec($ch), true);
if (!$body["success"]) exit($body["error"]["code"]);
foreach ($body["data"]["results"] as $r) {
    echo $r["trackingNumber"], " ", $r["status"] ?? $r["error"]["code"], "\n";
}

body := strings.NewReader(`{"carrier":"ups","trackingNumbers":["YOUR_TRACKING_NUMBER"]}`)
req, _ := http.NewRequest("POST", "https://api.shipmenttrackingapi.com/v1/track", body)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

res, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer res.Body.Close()

out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))

The answer has one result for each number. Read its status: it is always one of nine words. To send a request without writing code, open the Playground.

A lookup is not instant, so give your HTTP client a timeout of 60 seconds. Retries and timeouts has the details.

2Authentication

POST /v1/track needs your key in the Authorization header. GET /v1/carriers needs no key.

Authorization: Bearer YOUR_API_KEY

A key starts with sta_. Each account has one key. We store only a hash of it, so the console cannot show it to you again. If you lose it, or it leaks, replace it in the console. A deleted key can keep working for up to a minute.

The limits belong to the account, not to the key: a new key carries on with the same count.

Keep the key on your server. A key placed in a web page or a mobile app can be read by anyone who uses it.

3The request

POST /v1/track looks up one or more tracking numbers for one carrier. Send the body as JSON, with Content-Type: application/json.

{
  "carrier": "usps",
  "trackingNumbers": [
    "YOUR_TRACKING_NUMBER_1",
    "YOUR_TRACKING_NUMBER_2"
  ]
}

A request has four rules: one carrier per request, no more numbers than that carrier takes, no number twice, and every number 6 to 40 letters and digits. Carriers print their numbers with spaces, so strip them first. Break a rule and the whole request is rejected with a 400. The message names the rule and points to the number at fault.

Letters can be in either case. Each number comes back in uppercase, with leading and trailing spaces removed.

4The response

results has one entry for each number, in the order you sent them. An entry is either tracking data or an error for that one number. The HTTP status is 200 either way.

An example, not a real shipment. Four earlier scans are left out.

timeUnknown, location, estimatedDelivery and lastUpdated are left out when there is nothing to put in them.

Your code only has to read status. description is the carrier’s wording, written for people: show it, but do not build logic on it.

5When one number fails

One number without an answer does not fail the others. Its entry carries an error in place of status and events.

Of these errors, only TRACKING_NOT_FOUND makes the request count, the same as tracking data does.

6The nine statuses

A status is always one of these nine words, for the package as a whole and for each scan.

The words come from a table of what each carrier says, shown on the home page. The translation is automatic, and a status can be late, missing or wrong. Each scan also carries the carrier’s own words, in description.

7Carriers

GET /v1/carriers lists the carriers and how many tracking numbers each one takes in a request. It needs no key and is not counted.

curl https://api.shipmenttrackingapi.com/v1/carriers

Read maxTrackingNumbers from this response instead of writing the numbers into your code.

A request names one carrier, and the API does not work out the carrier from a number. For packages from two carriers, send two requests.

8Errors

When the whole request fails, the HTTP status says so, and the body has the same shape every time: a code your program can switch on and a message a person can read.

The answer to a UPS request that carried 2 numbers.

One exception: a body that is not valid JSON is refused before it reaches the API, with a plain 400 and no JSON.

An error for a single number is not in this table. It comes inside results with HTTP 200, as When one number fails describes.

Switch on code. The wording of a message can change.

9Limits

A request counts as one lookup when at least one number in it comes back with tracking data or with TRACKING_NOT_FOUND. A request where every entry is INVALID_TRACKING_NUMBER or CARRIER_ERROR is not counted. Neither is a request that was rejected with a 400, 429 or 503.

The answers to POST /v1/track carry headers that say where you stand.

The minute is the clock minute: the count starts again at second 0. Every request with a valid key uses one of the 30, whatever the answer. The month is the calendar month, in UTC.

The IP limit adds up every lookup from one address, whichever key made it. An IPv6 address is counted by its /64 network. If you share an outbound address with other people, as on a serverless platform or behind a shared NAT, send your requests through a static IP address of your own.

10Retries and timeouts

A lookup is not instant. In our tests a USPS request took 24 to 28 seconds, whether it carried 2 numbers or 35. Some take longer.

A request that runs too long comes back 503, is not counted, and can be sent again. Set your HTTP client’s timeout to 60 seconds: a client that gives up sooner can miss a result that was still counted.

Do not resend a 400, 401, 403 or 404 as it is. Fix the request first.

Send requests one after another. Requests sent at the same moment are more likely to come back 503. For a list longer than one request holds, this note has a loop that splits it and retries.

There are no webhooks. To follow a package, ask again later, and stop once it is delivered.

11For tools and agents

The same reference is published as two files that a program can read.