Spending by Geography
usaspending_spending_by_geographyRead-onlyIdempotent
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, or date range. 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 place names to these codes using a geocoding server (Census or OpenStreetMap) first. Chain per-capita results with Census population data for meaningful comparisons.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"scope": "<scope>",
"geo_layer": "<geo_layer>"
},
"name": "usaspending_spending_by_geography"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum geographic areas to return, ranked by aggregated_amount descending (1–500). 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; use shape_codes to retrieve one ranked past the cap. | |
| scope | Yes | Which location to aggregate by: place_of_performance (where work is done) or recipient_location (where the recipient is based) | |
| filters | No | Optional filters to scope the spending aggregation | |
| geo_layer | Yes | Geographic granularity: state (states, DC, and territories), county (county-level), or district (congressional district) | |
| subawards | No | Include subaward data instead of prime award data | |
| shape_codes | No | 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). 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The limit that was applied. | |
| error | No | Present when the call failed. Absent on success. | |
| scope | No | Location scope used for aggregation | |
| shown | No | Number of geographic areas returned. | |
| total | No | Number of geographic areas returned | |
| notice | No | How to reach areas omitted by limit, which shape_codes matched no area, which time-period bound was filled in when only the other was supplied, and — when the filters matched no area — any Assistance Listing, PSC, or DEF codes sent and how to broaden filters. Absent when none applies. | |
| results | No | Spending totals by geographic area | |
| geo_layer | No | Geographic granularity used | |
| truncated | No | True when the area list was capped at limit. | |
| area_count | No | Number of geographic areas returned | |
| applied_scope | No | Location scope applied: place_of_performance or recipient_location | |
| applied_keywords | No | Keyword filters applied (comma-separated) | |
| applied_def_codes | No | DEF codes sent, uppercased (comma-separated) | |
| applied_geo_layer | No | Geographic granularity applied: state, county, or district | |
| applied_psc_codes | No | PSC codes sent, uppercased (comma-separated) | |
| truncationCeiling | No | Obligation amount of the lowest-ranked area shown — an upper bound on omitted ones. | |
| applied_agency_name | No | Awarding agency name filter applied | |
| applied_naics_codes | No | NAICS code filters applied (comma-separated) | |
| applied_shape_codes | No | Area codes listed in shape_codes, letters uppercased and duplicates removed (comma-separated) | |
| applied_recipient_id | No | Normalized recipient hash and level sent | |
| total_areas_available | No | Number of geographic areas the filters matched, before shape_codes selection and limit were applied | |
| applied_time_period_end | No | End of the time period sent (YYYY-MM-DD), including a filled-in end | |
| applied_time_period_start | No | Start of the time period sent (YYYY-MM-DD), including a filled-in start | |
| applied_award_type_default | No | Disclosure that no filters were supplied, so award_type_codes defaulted to the complete set. Absent when the caller supplied at least one filter. | |
| applied_assistance_listings | No | Assistance Listing numbers sent (comma-separated) |