GnistAI GnistAI
Log in

Getting Started with USASpending

U.S. federal spending data — contracts, grants, and agency budgets.

All Tutorials   |   Overview   |   Playground   |   MCP   |   REST API   |   Home
Economics

Data source: USASpending.gov

Overview

USASpending wraps USASpending.gov, handling authentication, pagination, and rate limits for you. This tutorial covers all 6 tools with working code examples you can copy and run.

Prerequisites

  1. Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
  2. Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config 
{
  "mcpServers": {
    "gnist-usaspending": {
      "url": "https://context.gnist.ai/mcp/usaspending/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (6)

search_awards

Search USASpending.gov for federal awards (contracts, grants, loans, direct payments). USASpending.gov is the official source for US federal government spending data, covering $6–7 trillion annually from FY2008–present, updated nightly. Args: query: Keywords to search for (e.g. "Lockheed Martin", "cybersecurity", "COVID-19 relief"). award_type: Filter by award category. Values: "contracts" (default), "grants", "loans", "direct_payments". agency: Filter by awarding agency name (e.g. "Department of Defense", "Department of Health and Human Services"). date_from: Only include awards starting on or after this date (YYYY-MM-DD). date_to: Only include awards starting on or before this date (YYYY-MM-DD). limit: Number of results to return (1–50, default 10). Sorted by award amount descending. Returns: Dict with 'count', 'has_next', and 'awards' list. Each award includes award_id, recipient_name, award_amount, awarding_agency, start/end dates, description, and NAICS industry classification.

ParameterTypeRequiredDescription
querystringrequiredKeywords to search for (e.g. "Lockheed Martin", "cybersecurity", "COVID-19 relief").
award_typeanyoptionalFilter by award category. Values: "contracts" (default), "grants", "loans", "direct_payments".
agencyanyoptionalFilter by awarding agency name (e.g. "Department of Defense", "Department of Health and Human Services").
date_fromanyoptionalOnly include awards starting on or after this date (YYYY-MM-DD).
date_toanyoptionalOnly include awards starting on or before this date (YYYY-MM-DD).
limitintegeroptionalNumber of results to return (1–50, default 10). Sorted by award amount descending. (default: 10)
curl -X POST "https://context.gnist.ai/mcp/usaspending/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_awards", "arguments": {"query": "Lockheed Martin"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/usaspending/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'Lockheed Martin'}, 'name': 'search_awards'}},
)
print(resp.json())

get_award

Fetch detailed information for a specific federal award. Use the generated_internal_id from search_awards results (e.g. "CONT_AWD_N0001917C0001_9700_-NONE-_-NONE-") to look up full details including recipient info, subaward data, contracting details, and place of performance. Args: award_id: The generated_unique_award_id or generated_internal_id from search results. Returns: Dict with full award details: obligation amounts, recipient, agencies, NAICS/PSC codes, subaward count, place of performance, and period of performance dates.

ParameterTypeRequiredDescription
award_idstringrequiredThe generated_unique_award_id or generated_internal_id from search results.
curl -X POST "https://context.gnist.ai/mcp/usaspending/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_award", "arguments": {"award_id": "12345"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/usaspending/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'award_id': '12345'}, 'name': 'get_award'}},
)
print(resp.json())

get_recipient

Search for or fetch a federal award recipient (contractor, grantee, etc.). Search by name/keyword to find recipients, or pass a recipient_id (from search_awards results) to get a full profile with alternate names, business types, and location. Args: keyword: Recipient name or keyword to search (e.g. "Raytheon", "Johns Hopkins"). recipient_id: Specific recipient hash ID for full profile lookup (e.g. "6cf5fb1b-4988-d087-5dc1-70939d8fc6c4-C"). limit: Number of search results (1–50, default 10). Ignored when using recipient_id. Returns: Dict with 'count', 'total', and 'recipients' list. Each includes name, UEI, total award amount, and (for profile lookups) business types, location, and alternate names.

ParameterTypeRequiredDescription
keywordanyoptionalRecipient name or keyword to search (e.g. "Raytheon", "Johns Hopkins").
recipient_idanyoptionalSpecific recipient hash ID for full profile lookup (e.g. "6cf5fb1b-4988-d087-5dc1-70939d8fc6c4-C").
limitintegeroptionalNumber of search results (1–50, default 10). Ignored when using recipient_id. (default: 10)
curl -X POST "https://context.gnist.ai/mcp/usaspending/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_recipient", "arguments": {"keyword": "Raytheon"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/usaspending/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'keyword': 'Raytheon'}, 'name': 'get_recipient'}},
)
print(resp.json())

get_agency_spending

Fetch budgetary resources for a US federal agency. Common toptier agency codes: - "097" — Department of Defense - "075" — Department of Health and Human Services - "012" — Department of Agriculture - "069" — Department of Transportation - "089" — Department of Energy - "028" — Social Security Administration Args: agency_code: Three-digit toptier agency code (e.g. "097" for DoD). fiscal_year: Federal fiscal year (Oct–Sep). Omit for most recent available. Returns: Dict with toptier_code, fiscal_year, agency_budgetary_resources (total budget authority), agency_total_obligated (committed), agency_total_outlayed (spent), and total_budgetary_resources (all-government total for comparison).

ParameterTypeRequiredDescription
agency_codestringrequiredThree-digit toptier agency code (e.g. "097" for DoD).
fiscal_yearanyoptionalFederal fiscal year (Oct–Sep). Omit for most recent available.
curl -X POST "https://context.gnist.ai/mcp/usaspending/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_agency_spending", "arguments": {"agency_code": "097"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/usaspending/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'agency_code': '097'}, 'name': 'get_agency_spending'}},
)
print(resp.json())

spending_by_geography

Aggregate federal spending by geographic area (state, county, or congressional district). Useful for analyzing where federal money flows — e.g. which states receive the most defense contracts, or where COVID relief grants were concentrated. Args: keywords: Search terms to filter spending (e.g. ["cybersecurity"], ["COVID-19", "relief"]). geo_layer: Geographic granularity. Values: "state", "county", "district" (congressional district). Default "state". scope: What location to aggregate by. Values: "place_of_performance" (where work happens), "recipient_location" (where recipient is based). Default "place_of_performance". award_type: Filter by category: "contracts", "grants", "loans", "direct_payments". Omit for all types. date_from: Start date filter (YYYY-MM-DD). date_to: End date filter (YYYY-MM-DD). Returns: Dict with 'scope', 'geo_layer', 'count', and 'results' list. Each result includes shape_code (state/county/district code), display_name, aggregated_amount, population, and per_capita spending.

ParameterTypeRequiredDescription
keywordslist[string]requiredSearch terms to filter spending (e.g. ["cybersecurity"], ["COVID-19", "relief"]).
geo_layerstringoptionalGeographic granularity. Values: "state", "county", "district" (congressional district). Default "state". (default: state)
scopestringoptionalWhat location to aggregate by. Values: "place_of_performance" (where work happens), "recipient_location" (where recipient is based). Default "place_of_performance". (default: place_of_performance)
award_typeanyoptionalFilter by category: "contracts", "grants", "loans", "direct_payments". Omit for all types.
date_fromanyoptionalStart date filter (YYYY-MM-DD).
date_toanyoptionalEnd date filter (YYYY-MM-DD).
curl -X POST "https://context.gnist.ai/mcp/usaspending/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "spending_by_geography", "arguments": {"keywords": "[\"cybersecurity\"]"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/usaspending/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'keywords': '["cybersecurity"]'},
            'name': 'spending_by_geography'}},
)
print(resp.json())

report_feedback

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

ParameterTypeRequiredDescription
feedbackstringrequired
feedback_typestringoptional (default: general)
curl -X POST "https://context.gnist.ai/mcp/usaspending/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/usaspending/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_awards to find items, then get_award to get full details. This two-step pattern is common for exploring data before drilling down.
Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.
Date range filtering
Use date range parameters to narrow results to a specific time window. Dates are typically in YYYY-MM-DD format.

FAQ

What data does USASpending provide?

U.S. federal spending data — contracts, grants, and agency budgets. It exposes 6 tools: search_awards, get_award, get_recipient, get_agency_spending, spending_by_geography, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the USASpending API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.

Next Steps

Interactive Playground
Try tools in your browser — no setup required.
Full Reference
Complete docs for all 6 tools.

Related Tutorials

Economic Indicators
Tutorial
BLS (Bureau of Labor Statistics)
Tutorial
DST (Statistics Denmark)
Tutorial
ESCO (Skills & Occupations)
Tutorial
Eurostat
Tutorial
Commodity Prices
Tutorial