Vehicles Data Dictionary¶
This document describes the fields available in the Vehicles API endpoints (/api/vehicles/). For filtering, ordering, and pagination, see the Vehicles API Reference.
Overview¶
Vehicles provide a solicitation-centric grouping of multiple IDVs. Each vehicle represents a unique (solicitation_identifier, agency identifier) pair and can expand into the underlying IDVs via response shaping.
In federal data, each IDV award is a vehicle. In practice, people often think of a "vehicle" as the solicitation that produced many IDV awards (one per awardee). We model that higher-level grouping explicitly.
Note: The full set of fields is available via the shape query parameter. The base response includes a subset of commonly-used fields. See Response Shaping for details.
Update Frequency¶
Vehicle data is refreshed periodically by the Tango ingest pipeline.
Fields¶
| Field | Type | Description | Source |
|---|---|---|---|
uuid | UUID | Stable identifier for the vehicle in Tango. Deterministic from solicitation_identifier + agency identifier derived from the IDV key. | Tango |
solicitation_identifier | String | Solicitation identifier shared by the underlying IDVs. | FPDS (via awards) |
is_synthetic_solicitation | Boolean | true for GWAC-orphan vehicles whose solicitation identifier was recovered via the ACRO: prefix convention. | Tango |
agency_id | String | Agency identifier derived from the IDV award key suffix (award-key convention). | Tango |
program_acronym | String | Program acronym (e.g., ALLIANT, OASIS) when present. | Tango |
organization_id | UUID | Best-effort mapping to a canonical Tango Organization, for consistent agency joins/filtering. | Tango (derived) |
organization | Object | Live awarding-org snapshot: {organization_id, office_code, office_name, agency_code, agency_name, department_code, department_name}. Resolved at request time via the office cache. Select as a leaf token (shape=...,organization); not currently sub-selectable. | Tango |
vehicle_type | Object | Aggregated IDV type for the vehicle, derived from underlying IDVs. Returned as {code, description} (e.g., {code: "A", description: "GWAC"}). | FPDS (via awards) |
who_can_use | Object | Choice indicating which agencies may order against the vehicle. Returned as {code, description}. | FPDS (via awards) |
type_of_idc | Object | Aggregated IDC type for the vehicle. Returned as {code, description} (e.g., {code: "A", description: "Indefinite Delivery / Requirements"}). | FPDS (via awards) |
contract_type | Object | Aggregated contract type for the vehicle. Returned as {code, description} (e.g., {code: "J", description: "Firm Fixed Price"}). | FPDS (via awards) |
description | String | Longest common substring across the vehicle's IDV descriptions. | FPDS (via awards) |
descriptions | Array[String] | Set of distinct descriptions found across the underlying IDVs. | FPDS (via awards) |
fiscal_year | Integer | Representative fiscal year for the vehicle (derived from the underlying IDVs). | FPDS (via awards) |
award_date | Date | Earliest IDV award date associated with the vehicle. | FPDS (via awards) |
latest_award_date | Date | Most recent IDV award date associated with the vehicle. | Tango |
last_date_to_order | Date | Latest order-by date across the vehicle's IDVs. | FPDS (via awards) |
idv_count | Integer | Number of IDV awards in the vehicle (precomputed rollup). | Tango |
awardee_count | Integer | Number of unique awardees across the vehicle's IDVs. | Tango |
order_count | Integer | Total number of child awards/orders under the vehicle's IDVs (precomputed rollup). | Tango |
total_obligated | Decimal | Sum of obligations across child awards/orders (precomputed rollup). | Tango |
vehicle_obligations | Decimal | Sum of obligations across child awards/orders under the vehicle's IDVs (computed at query time). | Tango |
vehicle_contracts_value | Decimal | Sum of total contract value across child awards/orders under the vehicle's IDVs (computed at query time). | Tango |
solicitation_title | String | Title of the solicitation from the latest SAM.gov notice (via linked Opportunity). | SAM.gov (via opportunities) |
solicitation_description | String | Description of the solicitation from the latest SAM.gov notice (via linked Opportunity). | SAM.gov (via opportunities) |
solicitation_date | Date | First notice date from the linked SAM.gov Opportunity. | SAM.gov (via opportunities) |
opportunity_id | UUID | Foreign key to the linked SAM.gov Opportunity (if any). | Tango |
naics_code | Integer | NAICS code from the linked SAM.gov Opportunity. | SAM.gov (via opportunities) |
psc_code | String | Product/Service Code from the linked SAM.gov Opportunity. | SAM.gov (via opportunities) |
set_aside | String | Set-aside type from the linked SAM.gov Opportunity. | SAM.gov (via opportunities) |
Legacy fields¶
The following fields are kept on the API for backward compatibility — recomputed from the underlying IDVs at request time. They are not formally deprecated today (no Deprecation response header, no sunset date) because there are no first-class replacements yet for agency_details.funding_office or for the unique competition_details keys (extent_competed, set_aside, solicitation_procedures, number_of_offers_received). Where a replacement exists, it's listed below.
| Field | Type | Notes / partial replacement |
|---|---|---|
agency_details | Object | Awarding side is covered by the live organization object. Funding side (agency_details.funding_office) has no replacement at the vehicle grain — aggregate from /api/vehicles/<uuid>/orders/ (each order carries funding_organization_id) for funding analysis. |
competition_details | Object | Competition fields are also surfaced under the underlying IDVs (see awardees(...)). |
opportunity (expansion) | Object | Top-level solicitation_* fields and opportunity_id cover the common cases without a join. The full opportunity(...) expansion remains supported with the complete Opportunity field/expand surface (restored to pre-cutover parity). |
Expansions (via shape)¶
awardees¶
Expands to the underlying IDVs that make up the vehicle. Each IDV in the response carries vehicle-specific rollups: order_count, idv_obligations, idv_contracts_value. Supports nested orders(...) to expand each IDV's task orders.
metrics¶
Bundles 12 computed metrics under a single nested object. Available fields:
| Field | Type | Description |
|---|---|---|
avg_offers_received | Float | Average number of offers received across the vehicle's IDVs. |
award_concentration_hhi | Float | Herfindahl-Hirschman Index for award concentration across awardees. |
order_concentration_hhi | Float | HHI for task-order concentration across recipients. |
competed_rate | Float | Fraction of obligations that were competed. |
using_agency_count | Integer | Number of distinct agencies that have ordered against the vehicle. |
avg_order_value | Float | Average task-order obligated amount. |
max_order_value | Float | Largest single task-order obligated amount. |
top_recipient_share | Float | Share of obligations going to the largest single recipient. |
recent_obligations_24mo | Float | Sum of obligations in the trailing 24 months. |
recent_orders_24mo | Integer | Count of task orders in the trailing 24 months. |
days_since_last_order | Integer | Days since the most recent task order. |
obligation_to_ceiling_ratio | Float | Obligated-to-ceiling ratio (when ceiling is known). |
Use ?shape=...,metrics(*) to include all of them, or pick a subset (e.g. metrics(competed_rate,top_recipient_share)).
organization¶
The canonical 7-key office payload (organization_id, office_code, office_name, agency_code, agency_name, department_code, department_name). Both forms work and return the same payload:
?shape=...,organization— bare leaf?shape=...,organization(*)— expand (also supports field selection, e.g.organization(agency_name,office_name))
Example:
/api/vehicles/<vehicle-uuid>/?shape=uuid,solicitation_identifier,organization(*),metrics(*),awardees(key,uuid,piid,recipient(display_name,uei))
Sub-endpoints¶
/api/vehicles/<vehicle-uuid>/awardees/¶
Returns the IDV awardees for the vehicle, with vehicle-specific rollups (order_count, idv_obligations, idv_contracts_value) appended. Supports the awardees/IDV shaping vocabulary.
/api/vehicles/<vehicle-uuid>/orders/¶
Returns task orders (child contracts) under the vehicle's IDVs. Optimized for fast pagination over very large vehicles.
Supports ?ordering=... with award_date (default), obligated, or total_contract_value. Prefix with - for descending.
Search¶
- Vehicle list search:
GET /api/vehicles/?search=...searches across vehicle metadata and aggregated award search terms via full-text search. - Awardee-within-vehicle filtering:
GET /api/vehicles/<vehicle-uuid>/?shape=...,awardees(...)&search=...filters the expanded awardees (the vehicle itself is not filtered on detail).
Ordering¶
The list endpoint accepts ?ordering= with one of vehicle_obligations, latest_award_date, awardee_count, vehicle_contracts_value, total_obligated, award_date, last_date_to_order, fiscal_year, idv_count, or order_count. Prefix with - for descending; combine with commas for multi-field sort. See Vehicles API Reference — Ordering for usage notes.