# TT-005 · Customs mirror — method

**Grade: REPORTED** — counted by US customs authorities. Not observed by us, not modelled.

## What it measures
Monthly US goods trade with a partner country: exports, imports, balance, in US$ millions,
customs value, **all transport modes** (sea, air, land).

## Source
`https://www.census.gov/foreign-trade/balance/c{CTY}.html` — the US Census Bureau's published
country balance tables. Schedule C country codes — CORRECTED 2026-08-06 (the original seeding mislabeled
five of eight codes; caught when the corridor pages forced verification against the official
Schedule C list): India 5330, China 5700, Vietnam 5520, Singapore 5590, Indonesia 5600,
Burma 5460, Pakistan 5350, Afghanistan 5310. The stored monthly figures were always keyed by
code and are unaffected; only the display names were wrong. The published series
tt005.india.us-imports (5330) was correctly labeled throughout.

No API key. The richer port-level endpoint (`timeseries/intltrade/imports/porths`, which carries
`CNT_VAL_MO` — containerized vessel value by US port × origin country) **does** require a key;
that is a later upgrade, not a dependency.

## Cadence and revision
Monthly, roughly five weeks in arrears. **Census revises prior months.** The collector upserts on
`(cty, month)`, so a re-run silently adopts revisions. Any published figure must therefore be
pinned to the date it was retrieved.

## Coverage
1985-01 to present. 497 months for India.

## What it can and cannot answer
- **Can:** did US imports from a country actually rise or fall, and when.
- **Cannot:** which US port, which commodity, which vessel, sea versus air. All modes are pooled.

## Why this instrument exists
It shares no machinery with TT-002. TT-002 infers activity from vessel movements (AIS); this
counts customs declarations. When they disagree, at least one is wrong — and that disagreement
is more informative than either series alone.

## Known limits
- Total goods, not containerised sea freight — so it will never match a port-call series exactly.
- Country totals, not corridor-specific.
- HTML table scrape, not a versioned API: a layout change breaks the parse loudly (row count
  drops to zero and the run logs an error) rather than silently.

## Verification against TT-002
See `~/trimtab/findings/F-001-portwatch-india.md`. Through calendar 2024 the two instruments track
within ±10 index points. From 2025-03 they diverge by 27–58 points in the direction that cannot
be true, which is why TT-002's Indian series is currently marked unfit for publication.