Guess the carrier from a tracking number.

// guess-carrier.mjs: which carrier could this tracking number belong to?
// Returns the number to send and the carriers to try, most likely first.
export function guessCarrier(input) {
  const s = String(input).replace(/[^0-9A-Za-z]/g, "").toUpperCase();
  const answer = (carriers, number = s) => ({ number, carriers });

  // UPS: 1Z and 16 more characters, or T and 10 digits.
  if (/^1Z[0-9A-Z]{16}$/.test(s)) return answer(upsCheck(s) ? ["ups"] : []);
  if (/^T\d{10}$/.test(s)) return answer(["ups"]);

  // USPS international: 13 characters that end in US.
  if (/^[A-Z]{2}\d{9}US$/.test(s)) return answer(s10Check(s) ? ["usps"] : []);

  if (!/^\d+$/.test(s)) return answer([]);

  // USPS: starts with 91 to 95 and ends in a check digit. A scanned label
  // puts 420 and a 5- or 9-digit ZIP in front. That part is not the number.
  const tails = s.startsWith("420") ? [s.slice(12), s.slice(8)] : [s];
  const shaped = tails.filter((t) => /^9[1-5]/.test(t) && [22, 26, 30].includes(t.length));
  const usps = shaped.find(mod10);
  if (usps) return answer(["usps"], usps);
  if (shaped.length > 0) return answer([], shaped[0]); // the check digit fails

  // Digits alone: only the length is left to go on.
  const byLength = { 9: ["ups"], 10: ["dhl"], 12: ["fedex", "ups"], 15: ["fedex"] };
  return answer(byLength[s.length] ?? []);
}

// USPS Publication 199, section 4.6: weights 3, 1, 3, 1 ... from the right.
function mod10(digits) {
  let sum = 0;
  for (let i = digits.length - 2, weight = 3; i >= 0; i--, weight = 4 - weight) {
    sum += Number(digits[i]) * weight;
  }
  return (10 - (sum % 10)) % 10 === Number(digits.at(-1));
}

// UPU standard S10, section 5.4: weights 8 6 4 2 3 5 9 7 on the eight digits.
function s10Check(s) {
  const weights = [8, 6, 4, 2, 3, 5, 9, 7];
  const sum = weights.reduce((total, weight, i) => total + weight * Number(s[i + 2]), 0);
  const check = 11 - (sum % 11);
  return (check === 10 ? 0 : check === 11 ? 5 : check) === Number(s[10]);
}

// UPS does not publish this one. Letters count as A=2, B=3 ... H=9, I=0, J=1 ...
function upsCheck(s) {
  let sum = 0;
  for (let i = 2; i < 17; i++) {
    const code = s.charCodeAt(i);
    const value = code < 65 ? code - 48 : (code - 63) % 10;
    sum += i % 2 === 0 ? value : value * 2;
  }
  return (10 - (sum % 10)) % 10 === Number(s[17]);
}

# guess_carrier.py: which carrier could this tracking number belong to?
import re


def guess_carrier(text):
    """Return the number to send and the carriers to try, most likely first."""
    s = re.sub(r"[^0-9A-Za-z]", "", str(text)).upper()

    def answer(carriers, number=s):
        return {"number": number, "carriers": carriers}

    # UPS: 1Z and 16 more characters, or T and 10 digits.
    if re.fullmatch(r"1Z[0-9A-Z]{16}", s):
        return answer(["ups"] if ups_check(s) else [])
    if re.fullmatch(r"T[0-9]{10}", s):
        return answer(["ups"])

    # USPS international: 13 characters that end in US.
    if re.fullmatch(r"[A-Z]{2}[0-9]{9}US", s):
        return answer(["usps"] if s10_check(s) else [])

    if not re.fullmatch(r"[0-9]+", s):
        return answer([])

    # USPS: starts with 91 to 95 and ends in a check digit. A scanned label
    # puts 420 and a 5- or 9-digit ZIP in front. That part is not the number.
    tails = [s[12:], s[8:]] if s.startswith("420") else [s]
    shaped = [t for t in tails if re.match(r"9[1-5]", t) and len(t) in (22, 26, 30)]
    usps = next((t for t in shaped if mod10(t)), None)
    if usps:
        return answer(["usps"], usps)
    if shaped:
        return answer([], shaped[0])  # the check digit fails

    # Digits alone: only the length is left to go on.
    by_length = {9: ["ups"], 10: ["dhl"], 12: ["fedex", "ups"], 15: ["fedex"]}
    return answer(by_length.get(len(s), []))


def mod10(digits):
    """USPS Publication 199, section 4.6: weights 3, 1, 3, 1 ... from the right."""
    total = sum(int(d) * (3 if i % 2 == 0 else 1) for i, d in enumerate(reversed(digits[:-1])))
    return (10 - total % 10) % 10 == int(digits[-1])


def s10_check(s):
    """UPU standard S10, section 5.4: weights 8 6 4 2 3 5 9 7 on the eight digits."""
    total = sum(w * int(d) for w, d in zip((8, 6, 4, 2, 3, 5, 9, 7), s[2:10]))
    check = 11 - total % 11
    return {10: 0, 11: 5}.get(check, check) == int(s[10])


def ups_check(s):
    """UPS does not publish this one. Letters count as A=2, B=3 ... H=9, I=0, J=1 ..."""
    total = 0
    for i, c in enumerate(s[2:17]):
        value = int(c) if c.isdigit() else (ord(c) - 63) % 10
        total += value if i % 2 == 0 else value * 2
    return s[17].isdigit() and (10 - total % 10) % 10 == int(s[17])

// track-any.mjs: Node 18 or later. Tries each candidate until one has data.
import { guessCarrier } from "./guess-carrier.mjs";

const API = "https://api.shipmenttrackingapi.com/v1";
const headers = {
  Authorization: "Bearer YOUR_API_KEY",
  "Content-Type": "application/json",
};
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

export async function trackAny(input) {
  const { number, carriers } = guessCarrier(input);
  for (const carrier of carriers) {
    let res;
    for (let attempt = 1; attempt <= 3; attempt++) {
      res = await fetch(`${API}/track`, {
        method: "POST",
        headers,
        body: JSON.stringify({ carrier, trackingNumbers: [number] }),
        signal: AbortSignal.timeout(60_000),
      });
      if (res.status !== 503) break; // a 503 was not counted: send it again
      await sleep(5_000);
    }
    const body = await res.json();
    const result = body.success ? body.data.results[0] : body;
    if (!result.error) return { carrier, ...result };

    // INVALID_TRACKING_NUMBER: not a number that carrier uses. Not counted.
    // TRACKING_NOT_FOUND: the carrier has no record. That lookup counted.
    const { code } = result.error;
    if (code !== "INVALID_TRACKING_NUMBER" && code !== "TRACKING_NOT_FOUND") {
      throw new Error(code);
    }
  }
  return null; // no guess, or no carrier had it
}

# track_any.py: Python 3, with the requests package.
import time
import requests
from guess_carrier import guess_carrier

API = "https://api.shipmenttrackingapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}


def track_any(text):
    """Try each candidate until one has tracking data."""
    guess = guess_carrier(text)
    for carrier in guess["carriers"]:
        for attempt in range(3):
            res = requests.post(
                f"{API}/track",
                headers=HEADERS,
                json={"carrier": carrier, "trackingNumbers": [guess["number"]]},
                timeout=60,
            )
            if res.status_code != 503:  # a 503 was not counted: send it again
                break
            time.sleep(5)
        body = res.json()
        result = body["data"]["results"][0] if body["success"] else body
        if "error" not in result:
            return {"carrier": carrier, **result}

        # INVALID_TRACKING_NUMBER: not a number that carrier uses. Not counted.
        # TRACKING_NOT_FOUND: the carrier has no record. That lookup counted.
        code = result["error"]["code"]
        if code not in ("INVALID_TRACKING_NUMBER", "TRACKING_NOT_FOUND"):
            raise RuntimeError(code)
    return None  # no guess, or no carrier had it