Aggregate federal spending by state, county, or congressional district. Useful for per-capita analysis, regional comparisons, and mapping federal investment patterns. Filter by keyword, award type, agency, recipient, NAICS code, Assistance Listing, PSC, DEF code, place of performance or recipient location, or date range. scope picks the location results are grouped by, separately from the location filters: the counties of one state are geo_layer county with filters.place_of_performance_location set to that state and scope place_of_performance. Areas are ranked by obligation and capped at limit; to retrieve specific areas, including ones ranked past the cap, list their codes in shape_codes — a 2-letter postal code for state, a 5-digit state + county FIPS code for county, or a 4-digit state FIPS + district number for district — NOT place names. Resolve a state, county, or district name to its code with usaspending_autocomplete_filters type=location. Chain per-capita results with Census population data for meaningful comparisons.
View input schema
{
"type": "object",
"properties": {
"scope": {
"type": "string",
"enum": [
"place_of_performance",
"recipient_location"
],
"description": "Which location to aggregate by: place_of_performance (where work is done) or recipient_location (where the recipient is based)"
},
"geo_layer": {
"type": "string",
"enum": [
"state",
"county",
"district"
],
"description": "Geographic granularity: state (states, DC, and territories), county (county-level), or district (congressional district)"
},
"filters": {
"description": "Optional filters to scope the spending aggregation. With neither date bound, results use USAspending's available coverage without a date filter.",
"type": "object",
"properties": {
"keywords": {
"description": "Full-text keyword filters; each effective term needs at least three characters, including significant whitespace",
"type": "array",
"items": {
"type": "string"
}
},
"award_type_codes": {
"description": "Award type codes: A/B/C/D (contracts), IDV_A–IDV_E (IDVs), 02–05 (grants), 06/10 (direct payments), 07/08 (loans), 09/11 (insurance and other assistance), -1 (unspecified). Groups may be mixed here. Omit to aggregate every type.",
"type": "array",
"items": {
"type": "string"
}
},
"agency_name": {
"description": "Awarding top-tier or sub-tier agency name. Use the matched name from usaspending_autocomplete_filters type=awarding_agency, or toptier_name to select the whole parent department. A sub-tier name shared by several parents matches under all parents. Exact case-insensitive names and unambiguous abbreviations resolve to the directory spelling.",
"type": "string"
},
"funding_agency_name": {
"description": "Funding top-tier or sub-tier agency name. Use the matched name from usaspending_autocomplete_filters type=awarding_agency. Exact case-insensitive names and unambiguous abbreviations resolve to the directory spelling. When agency_name is also supplied, awards must match both roles.",
"type": "string"
},
"recipient_id": {
"description": "recipient_id from usaspending_search_recipients: hexadecimal 8-4-4-4-12 hash plus uppercase -P, -C, or -R; hash letters normalize to lowercase; empty is unset. A -P recipient ID covers awards USAspending attributes to that parent. Historical parent attribution can vary. For the entity’s own awards, use the returned -C ID for awards recorded with a parent or the returned -R ID for awards recorded without one. Check both when usaspending_search_recipients returns both. Use returned IDs directly.",
"type": "string"
},
"naics_codes": {
"description": "NAICS codes: canonical 2, 4, or 6 digits; recognized ASCII integer aliases normalize whitespace, plus, leading zeros and digit underscores; unclassified spellings remain provider-validated",
"type": "array",
"items": {
"type": "string"
}
},
"assistance_listings": {
"description": "Filter by Assistance Listing (CFDA) program numbers, e.g. [\"15.507\"]: two digits, a dot, then three digits or capital letters (11.67A). Matches an award when any of its listings equals one of these exactly; several values match any of them. A matching award's primary listing can differ from the one requested, and amounts cover the whole award, not that listing's share. Only assistance awards (grants, direct payments, loans, other assistance) carry listings, so a call whose award types are all contracts or IDVs — including a contract default — is rejected as assistance_listings_type_mismatch. Use usaspending_autocomplete_filters type=cfda to look up numbers.",
"type": "array",
"items": {
"type": "string",
"pattern": "^\\d{2}\\.[0-9A-Z]{3}$",
"description": "Assistance Listing number, e.g. 15.507"
}
},
"psc_codes": {
"description": "Filter by Product and Service Codes (PSC), e.g. [\"Y1NE\"]: 1–4 letters or digits, sent uppercased. A shorter code covers every code under it (\"Y1\" covers \"Y1NE\"); several values match any of them. Only contracts and IDVs carry a PSC, so a call whose award types are all assistance types is rejected as psc_codes_type_mismatch, and pairing psc_codes with assistance_listings matches nothing, since no award carries both. Use usaspending_autocomplete_filters type=psc to look up codes.",
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9A-Za-z]{1,4}$",
"description": "Product and Service Code or prefix, e.g. Y1NE or Y1"
}
},
"def_codes": {
"description": "Filter by Disaster Emergency Fund Codes (DEF), e.g. [\"Z\"], or [\"L\", \"M\", \"N\", \"O\", \"P\"] for COVID-19: 1–3 letters or digits, sent uppercased. Discover codes with usaspending_autocomplete_filters type=def_code. Matches awards of any type funded under any of these codes. Amounts cover the whole matching award, not the share funded by the code, and DEF-filtered totals can be negative. An unknown code is rejected with the list of codes USAspending accepts.",
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9A-Za-z]{1,3}$",
"description": "Disaster Emergency Fund Code, e.g. Z or L"
}
},
"place_of_performance_location": {
"description": "Filter by place of performance — where the work is done. Takes codes, not place names — resolve a state or county name to its code with usaspending_autocomplete_filters type=location. Blank fields are ignored, and an all-blank object is no location filter. The location sent is echoed as applied_location.",
"type": "object",
"properties": {
"country": {
"description": "ISO 3166-1 alpha-3 country code (e.g., USA); USA when omitted. A US territory code — PRI, GUM, VIR, ASM, MNP — is sent as USA with the territory as state.",
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^[A-Za-z]{3}$"
}
]
},
"state": {
"description": "Under USA (the default): a US state, DC, territory, freely associated state, or armed-forces code as a 2-letter postal code (NM, PR, FM, AE) or 2-digit FIPS code (35). Under another country: that country's own 2-letter subdivision code (ON with CAN).",
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^(?:[A-Za-z]{2}|\\d{2})$"
}
]
},
"county": {
"description": "US county FIPS code: 3 digits with state (049 with state NM), or the 5-digit state + county code (35049, Santa Fe County, NM), whose first two digits set the state — the form usaspending_spending_by_geography county rows carry as shape_code.",
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^(?:\\d{3}|\\d{5})$"
}
]
},
"city": {
"description": "City name",
"type": "string"
}
},
"additionalProperties": false
},
"recipient_location": {
"description": "Filter by recipient location — where the recipient is based, which can differ from where the work is done. Takes codes, not place names — resolve a state or county name to its code with usaspending_autocomplete_filters type=location. Blank fields are ignored, and an all-blank object is no location filter. The location sent is echoed as applied_recipient_location.",
"type": "object",
"properties": {
"country": {
"description": "ISO 3166-1 alpha-3 country code (e.g., USA); USA when omitted. A US territory code — PRI, GUM, VIR, ASM, MNP — is sent as USA with the territory as state.",
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^[A-Za-z]{3}$"
}
]
},
"state": {
"description": "Under USA (the default): a US state, DC, territory, freely associated state, or armed-forces code as a 2-letter postal code (NM, PR, FM, AE) or 2-digit FIPS code (35). Under another country: that country's own 2-letter subdivision code (ON with CAN).",
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^(?:[A-Za-z]{2}|\\d{2})$"
}
]
},
"county": {
"description": "US county FIPS code: 3 digits with state (049 with state NM), or the 5-digit state + county code (35049, Santa Fe County, NM), whose first two digits set the state — the form usaspending_spending_by_geography county rows carry as shape_code.",
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^(?:\\d{3}|\\d{5})$"
}
]
},
"city": {
"description": "City name",
"type": "string"
}
},
"additionalProperties": false
},
"time_period_start": {
"description": "Start of time period (YYYY-MM-DD), 2007-10-01 or later. Given alone, the period runs through today (UTC).",
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"description": "Date as YYYY-MM-DD; month and day may be unpadded"
}
]
},
"time_period_end": {
"description": "End of time period (YYYY-MM-DD). Given alone, the period starts at 2007-10-01, the earliest searchable date.",
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"description": "Date as YYYY-MM-DD; month and day may be unpadded"
}
]
}
},
"additionalProperties": false
},
"limit": {
"default": 50,
"description": "Maximum geographic areas to return, ranked by aggregated_amount descending. Default 50, no maximum. The upstream endpoint is not paginated — it returns every matching area in one response — so this caps client-side. A nationwide county query matches over 3,000 areas; raise limit to see them all, or use shape_codes to retrieve one ranked past the cap.",
"type": "integer",
"minimum": 1
},
"shape_codes": {
"description": "Return only these areas (1–500 codes), in the shape_code form this tool returns for geo_layer: 2-letter postal code for state (\"NY\"), 5-digit state + county FIPS for county (\"36117\" is Wayne County, NY), or 4-digit state FIPS + 2-digit district number for district (\"3623\" is NY-23, \"5600\" is Wyoming's at-large seat). usaspending_autocomplete_filters type=location resolves a state, county, or district name to its code. Selection runs over every area the filters matched, so it reaches areas ranked past limit; selected areas stay ranked by aggregated_amount and capped at limit. A code that matches no area is named in the notice.",
"minItems": 1,
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"pattern": "^(?:[A-Za-z]{2}|\\d{4,5})$",
"description": "One area code: 2-letter postal code (e.g. \"NY\"), 5-digit county FIPS (e.g. \"36117\"), or 4-digit district code (e.g. \"3623\")"
}
},
"subawards": {
"default": false,
"description": "Include subaward data instead of prime award data",
"type": "boolean"
}
},
"required": [
"scope",
"geo_layer"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}