USAspending Awards
Federal contracts and grants from USAspending: recipient, amount, agency and purpose.
usaspending_awards — the dataset name to pass to the Obscura API.
What one row means
One federal contract or grant award as most recently observed by USAspending.gov's keyless `spending_by_award` search API, deduplicated on the award's stable id; `category` tags whether the row came from the collector's contract query or its grant query, each sorted by Award Amount descending and capped to the top results inside the trailing lookback window. The table only ever holds the largest awards seen in-window per category, not a full census of federal spending.
One row per award_key (primary key, no auto-increment) — USAspending's generated_internal_id for the award, falling back to the raw Award ID field when generated_internal_id is absent.
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 usaspending_awards: published: available_date = COALESCE(captured_date, (synced_at AT TIME ZONE 'UTC')::date), the day this collector captured the award_key via USAspending's spending_by_award search. Equal to the ingestion day on a live run; on a bronze replay it is the original capture day, never the replay day.
Refresh cadence
Obscura refreshes usaspending_awards 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 — 28 columns
The full public column list for usaspending_awards, with the meaning of every field. The same
schema is served unauthenticated at https://api.obscura.trade/v1/catalog/usaspending_awards.
| Column | Type | Description |
|---|---|---|
| award_key | text · not null | Primary key. USAspending's stable generated_internal_id for the award; falls back to the raw "Award ID" API field when generated_internal_id is missing from the result row. Rows without either are dropped and never reach the table. |
| award_id | text | Human-readable award identifier (e.g. a PIID/FAIN string) from the API's "Award ID" field. Nullable — some result rows omit it even when generated_internal_id (the award_key) is present. |
| recipient_name | text | Name of the awardee organization or individual, from the API's "Recipient Name" field. Free text as returned by USAspending — not normalized, deduped, or joined against any recipient/entity master table in this repo. Nullable. |
| award_amount | double precision | Dollar value of the award from the API's "Award Amount" field (total obligated-to-date for contracts, total assistance amount for grants). This is the sort key the collector queries on, so the table only ever contains the largest awards per category within the lookback window, never a representative sample. Nullable when the API omits it. |
| awarding_agency | text | Name of the federal department/agency that made the award (e.g. "Department of Energy"), from the API's "Awarding Agency" field. Nullable; updated on every re-sync. |
| awarding_agency_id | bigint | USAspending's stable numeric toptier-agency id for the awarding agency, from the API's always-returned "awarding_agency_id" field (e.g. 930 for Department of Energy). A real join key for the awarding-agency entity across USAspending endpoints, far more reliable than the free-text `awarding_agency` name. Nullable. |
| awarding_sub_agency | text | Awarding sub-agency name (finer attribution than `awarding_agency`), from the API's "Awarding Sub Agency" field. Nullable. |
| funding_agency | text | Name of the federal agency that funded the award (may differ from the awarding agency), from the API's "Funding Agency" field. Nullable. |
| funding_sub_agency | text | Funding sub-agency name (finer attribution than `funding_agency`), from the API's "Funding Sub Agency" field. Nullable. |
| award_type | text | Human-readable award instrument/type from the API's "Award Type" field (e.g. "Contract", specific IDV or grant sub-types). Distinct from `category`, which only encodes which of the two collector queries produced the row. Nullable. |
| contract_award_type | text | Contract instrument type from the API's "Contract Award Type" field (e.g. "DEFINITIVE CONTRACT"). Populates the instrument type that the minimal request left `award_type` null for. Nullable (grant awards omit it). |
| recipient_uei | text | 12-character SAM.gov Unique Entity Identifier for the recipient, from the API's "Recipient UEI" field. Canonical cross-dataset entity id (successor to DUNS). Nullable. |
| recipient_id | text | USAspending's internal recipient hash id from the API's "recipient_id" field (e.g. "6e7a895c-...-C"). Join key for USAspending's recipient endpoints; not a public/registry identifier. Nullable. |
| total_outlays | double precision | Dollars actually disbursed against the award, from the API's "Total Outlays" field. A distinct measure from `award_amount` (obligated dollars); can be negative on de-obligations. Nullable. |
| description | text | Free-text description of the award's purpose, from the API's "Description" field. Nullable. |
| period_start | date | Period-of-performance start date from the API's "Start Date" field (the day work begins; a natural event date, NOT the public-availability date). Nullable. |
| period_end | date | Period-of-performance end date from the API's "End Date" field (the day work is scheduled to end). Nullable. |
| last_date_to_order | date | Last date on which orders may be placed against the award (IDVs), from the API's "Last Date to Order" field. Nullable; usually null for non-IDV awards. |
| naics_code | text | NAICS industry code from the API's "NAICS" object's `code` (e.g. "561210"). One NAICS per award (1:1). Nullable. |
| naics_description | text | Human-readable NAICS industry description from the API's "NAICS" object's `description`. Nullable. |
| psc_code | text | Product/Service Code from the API's "PSC" object's `code` (e.g. "M181"). One PSC per award (1:1). Nullable. |
| psc_description | text | Human-readable PSC description from the API's "PSC" object's `description`. Nullable. |
| place_of_performance_state | text | Place-of-performance US state (or territory) code from the API's "Place of Performance State Code" field (e.g. "NM"). Nullable. |
| place_of_performance_country | text | Place-of-performance ISO-ish country code from the API's "Place of Performance Country Code" field (e.g. "USA"). Nullable. |
| place_of_performance_zip5 | text | Place-of-performance 5-digit ZIP from the API's "Place of Performance Zip5" field (e.g. "87185"). Nullable. |
| category | text · not null | Award category the search ran under: "contract" (award_type_codes A/B/C/D) or "grant" (02/03/04/05). Set by the task itself, not returned by the API; on re-sync it is overwritten with whichever category last matched the award_key. |
| captured_date | date | The UTC calendar day the `spending_by_award` page carrying this award was CAPTURED — the day the award became knowable to us. `Utc::now().date_naive()` on a live run, `BronzeObject::captured_day()` on a bronze replay, so re-parsing a months-old page keeps its original date instead of stamping the replay day. Distinct from `period_start`/`period_end` (the award's own performance span). NULL on rows written before migration 000175, where `available_date` falls back to `synced_at::date` — the same value for a live capture. |
| available_date | date | PUBLIC-availability date, the day this collector first observed the award_key. STORED generated column: COALESCE(captured_date, (synced_at AT TIME ZONE 'UTC')::date). DB-generated, read-only; the point-in-time column to filter/join on. |
Access usaspending_awards
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="usaspending_awards",
start="2024-01-01",
)Create a free account Browse all 95 datasets
Frequently asked questions
What is in the usaspending_awards dataset?
Federal contracts and grants from USAspending: recipient, amount, agency and purpose. One federal contract or grant award as most recently observed by USAspending.gov's keyless `spending_by_award` search API, deduplicated on the award's stable id; `category` tags whether the row came from the collector's contract query or its grant query, each sorted by Award Amount descending and capped to the top results inside the trailing lookback window. The table only ever holds the largest awards seen in-window per category, not a full census of federal spending.
How do I avoid look-ahead bias with usaspending_awards?
Filter on usaspending_awards.available_date, the day the publisher made the row public. For this dataset that date is derived as follows — published: available_date = COALESCE(captured_date, (synced_at AT TIME ZONE 'UTC')::date), the day this collector captured the award_key via USAspending's spending_by_award search. Equal to the ingestion day on a live run; on a bronze replay it is the original capture day, never the replay day. A query of the form WHERE available_date <= '<as-of date>' never sees a row before it existed.
In what formats can I get usaspending_awards?
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="usaspending_awards". The column schema is public at https://api.obscura.trade/v1/catalog/usaspending_awards.
How often is usaspending_awards updated?
Obscura refreshes usaspending_awards 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.