Skip to content

Forecasts

Forecasts are procurement forecasts exposed at /api/forecasts/. For field definitions, see the Forecasts Data Dictionary. For which agency sources we ingest (HHS, DHS, GSA, COMMERCE, DOE, ED, TREASURY, DOI, DOL, DOT, USDA, VA, NRC, NSF), see Forecasts we track.

Endpoints

  • GET /api/forecasts/ (list + filtering + search + ordering)
  • GET /api/forecasts/{pk}/ (detail)

Response Shaping

Forecasts default to the shaping pipeline — all responses go through shaping even without ?shape=. Use ?shape= to customize which fields are returned.

  • List default: id, source_system, external_id, agency, title, description, anticipated_award_date, fiscal_year, naics_code, is_active, status, primary_contact, place_of_performance, estimated_period, set_aside, contract_vehicle, organization(*)
  • Detail default: Same as list, plus raw_data and display(*)

The organization(*) expand is the canonical 7-key office payload, resolved deterministically from the forecast's agency text against Tango's department-level agency aliases. All 14 agency values currently in the data resolve: HHS, DHS, DOI, GSA, DOE, ED, DOT, VA, DOL, NRC, NSF, COMMERCE, TREASURY, USDA. A forecast whose agency value matches no department alias returns organization: null.

See Response Shaping for full syntax and the Forecasts Data Dictionary for field definitions.

Filtering

Core filters (multi-value filters accept | for OR; date filters require YYYY-MM-DD format — invalid dates or inverted ranges return 400, see Date filters):

Param What it does
agency Filter by agency acronym.
source_system Filter by source system identifier.
naics_code Filter by exact NAICS.
naics_starts_with Filter by NAICS prefix (e.g. 54).
fiscal_year Filter by exact fiscal year.
fiscal_year_gte, fiscal_year_lte Fiscal year range.
award_date_after, award_date_before Anticipated award date range (YYYY-MM-DD).
modified_after, modified_before Modified-in-Tango date range (YYYY-MM-DD).
status Status (case-insensitive, partial match).
search Full-text search over title/description (vector-backed).

Ordering

Forecasts support ordering= with a strict allowlist:

  • anticipated_award_date
  • fiscal_year
  • title

Examples:

  • Soonest award first: GET /api/forecasts/?ordering=anticipated_award_date
  • Most recent fiscal year first: GET /api/forecasts/?ordering=-fiscal_year

Pagination

Forecasts use standard page-number pagination:

  • page (default 1)
  • limit (max 100)

SDK examples

See also: Full SDK method reference — tango-python methods · tango-node methods.

import os

from tango import ShapeConfig, TangoClient

client = TangoClient(api_key=os.environ["TANGO_API_KEY"])
resp = client.list_forecasts(
    agency="GSA",
    naics_starts_with="54",
    ordering="-anticipated_award_date",
    limit=10,
    shape=ShapeConfig.FORECASTS_MINIMAL,
)

for f in resp.results:
    print(f.title, f.anticipated_award_date)

import { ShapeConfig, TangoClient } from "@makegov/tango-node";

const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY });
const resp = await client.listForecasts({
  agency: "GSA",
  naics_starts_with: "54",
  ordering: "-anticipated_award_date",
  limit: 10,
  shape: ShapeConfig.FORECASTS_MINIMAL,
});

for (const f of resp.results) {
  console.log(f.title, f.anticipated_award_date);
}
Report an issue with this page