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, TREASURY, DOI, DOL, DOT, VA, NRC), 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 using a 12-acronym alias map covering: HHS, DHS, DOI, GSA, DOE, DOT, VA, DOL, NRC, NSF, COMMERCE, TREASURY. Forecasts whose agency value doesn't map to one of these 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