Examples
Request examples in Node.js, Python, and Google Apps Script
This page shows how to retrieve tracking data for one number with GET /v2/tracking. Choose a language and replace YOUR_TOKEN with your API key.
Base URL for requests: https://tracking.timetocargo.com/v2.
More examples:
- Batch tracking — submit up to 500 numbers with
POST /v2/tracking/batchto create a tracking task. The API returns a task ID without waiting for tracking results. Retrieve its results later withGET /v2/tracking/batch. - Shipments — list tracked shipments, add or update a note, and archive or delete a record.
- Companies — get supported carriers, their SCAC codes, and available tracking types.
- Webhooks — receive tracking updates and verify their signatures.
Query parameters: api_key, company (AUTO or a carrier SCAC code), value (the number), and type (container, bl, or bk).
Request example
The example tracks a container and prints the result status and shipment summary.
Node.js 18+ with global fetch.
// Request tracking data for one number and read the result.
// Set the API URL and request parameters.
const API_BASE = "https://tracking.timetocargo.com/v2";
const url = new URL(`${API_BASE}/tracking`);
url.searchParams.set("api_key", "YOUR_TOKEN");
url.searchParams.set("company", "AUTO");
url.searchParams.set("value", "MSDU8368827");
url.searchParams.set("type", "container");
const res = await fetch(url, { headers: { Accept: "application/json" } });
// Check the HTTP response before using the result.
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
// Read JSON; success and status describe the request result.
const body = await res.json();
if (body.success === false) throw new Error(body.status_description || body.status);
console.log(body.status, body.data?.summary ?? null);Error handling
Handle HTTP failures, honor 429, and inspect status even when HTTP is 200. Do not log the API key.
// Request tracking data for one number and read the result.
// Set the API URL and request parameters.
const API_BASE = "https://tracking.timetocargo.com/v2";
async function track({ token, company, value, type }) {
const url = new URL(`${API_BASE}/tracking`);
url.searchParams.set("api_key", token);
url.searchParams.set("company", company);
url.searchParams.set("value", value);
url.searchParams.set("type", type);
const res = await fetch(url, {
headers: { Accept: "application/json" },
signal: AbortSignal.timeout(90_000),
});
if (res.status === 429) {
const retryAfter = res.headers.get("Retry-After");
throw new Error(`Rate limited. Retry-After: ${retryAfter ?? "not provided"}`);
}
// Check the HTTP response before using the result.
if (!res.ok) {
throw new Error(`HTTP ${res.status}`);
}
// Read JSON; success and status describe the request result.
const body = await res.json();
if (body.status === "INFO_NOT_FOUND" && body.success === true) return null;
if (body.success === false || body.status !== "OK") {
throw new Error(body.status_description ?? body.status);
}
return body.data;
}
const data = await track({
token: process.env.TIMETOCARGO_API_KEY,
company: "AUTO",
value: "MSDU8368827",
type: "container",
});
const summary = data?.summary;
const locations = data?.locations ?? [];
const pol = summary?.pol?.location != null ? locations[summary.pol.location] : null;
const lastActualEvent = data?.containers?.[0]?.events?.find((event) => event.actual);
console.log({
company: summary?.company?.full_name,
departure: pol?.name,
lastActualEvent,
});See the API reference for response schemas and parameters.
Last updated on