Border Crossings
Monthly inbound crossings at U.S. land ports on the Canadian and Mexican borders, split by mode (trucks, trains, personal vehicles, pedestrians). From the Bureau of Transportation Statistics.
border_crossings — the dataset name to pass to the Obscura API.
What one row means
One row is BTS's reported inbound-crossing count for a single freight mode (Trucks or Trains) at a single US land port of entry for a single observation month, from the "Border Crossing/Entry Data" Socrata feed (data.bts.gov/resource/keg4-3bc2.json).
One row per (port_code, period_start, measure).
Point-in-time availability
Every Obscura dataset carries available_date: the calendar day the publisher made the row
available, day-of, with no session rounding. It is the one column a backtest filters on, and it means the
same thing on every dataset in the catalog.
For border_crossings: published: available_date = period_start (observation month) shifted to month-end + 70 days, BTS's real publication lag for the keg4-3bc2 feed. DB-generated (STORED), read-only.
Refresh cadence
Obscura refreshes border_crossings daily — the most frequent scheduled job that re-collects or re-exports it. This is Obscura's own pipeline cadence, not the upstream publisher's release schedule; when a row became public is recorded per row in available_date.
Schema — 10 columns
The full public column list for border_crossings, with the meaning of every field. The same
schema is served unauthenticated at https://api.obscura.trade/v1/catalog/border_crossings.
| Column | Type | Description |
|---|---|---|
| port_code | text · not null | BTS port-of-entry code (e.g. '3802' = Port Huron, '0104' = Jackman); part of the composite primary key with period_start and measure. |
| period_start | date · not null | First day of the observation month (rehomed from the old, misused available_date). A period/event date, NOT when it became public. |
| measure | text · not null | Crossing/freight mode kept by this collector — 'Trucks' or 'Trains', a subset of BTS's full measure list. Part of the composite primary key. |
| value | bigint | Count of inbound crossings of that measure/mode at that port for the observation month; NOT a cumulative or YTD figure. |
| port_name | text | Human-readable BTS port-of-entry name (e.g. 'Jackman', 'Port Huron'). |
| state | text | US state in which the port of entry sits. |
| border | text | `US-Canada Border` | `US-Mexico Border`. |
| latitude | double precision | Latitude of the port of entry in decimal degrees. |
| longitude | double precision | Longitude of the port of entry in decimal degrees. |
| available_date | date | PUBLIC-availability date = period_start shifted by BTS's real publication lag (month-end + 70 days). DB-generated, read-only; the point-in-time column to filter/join on — NEVER the observation month itself. |
Access border_crossings
Two delivery paths, one identifier. Both require an Obscura account and an active subscription; the catalog entry and the schema above are public.
import obscura
client = obscura.Client("obs_live_…")
df = client.query(
dataset="border_crossings",
symbols=["NVDA", "AAPL"],
start="2024-01-01",
)Create a free account Browse all 95 datasets
Frequently asked questions
What is in the border_crossings dataset?
Monthly inbound crossings at U.S. land ports on the Canadian and Mexican borders, split by mode (trucks, trains, personal vehicles, pedestrians). From the Bureau of Transportation Statistics. One row is BTS's reported inbound-crossing count for a single freight mode (Trucks or Trains) at a single US land port of entry for a single observation month, from the "Border Crossing/Entry Data" Socrata feed (data.bts.gov/resource/keg4-3bc2.json).
How do I avoid look-ahead bias with border_crossings?
Filter on border_crossings.available_date, the day the publisher made the row public. For this dataset that date is derived as follows — published: available_date = period_start (observation month) shifted to month-end + 70 days, BTS's real publication lag for the keg4-3bc2 feed. DB-generated (STORED), read-only. A query of the form WHERE available_date <= '<as-of date>' never sees a row before it existed.
In what formats can I get border_crossings?
As a Parquet bulk export (POST https://api.obscura.trade/v1/download) or as JSON from the typed query API (POST https://api.obscura.trade/v1/query), both with dataset="border_crossings". The column schema is public at https://api.obscura.trade/v1/catalog/border_crossings.
Can I filter border_crossings by company or symbol?
Yes. border_crossings carries port_name, the column the API's symbols filter resolves against.
How often is border_crossings updated?
Obscura refreshes border_crossings on a daily schedule — that is the most frequent scheduled job that re-collects or re-exports the table. It is Obscura's own pipeline cadence, not the upstream publisher's release schedule; when the publisher makes a row available is described by the availability rule above, and is recorded per row in available_date.