Spending by Geography

POST/api/v2/search/spending_by_geography/

Powers Advanced Search on usaspending.gov How Advanced Search works

This endpoint supports the advanced search page and allow for complex filtering for specific subsets of spending data.

This endpoint takes award filters, and returns aggregated obligation amounts in different geographic areas.

Request

curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_geography/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "keywords": [
      "Filter is required"
    ]
  },
  "scope": "place_of_performance",
  "geo_layer": "state"
}'

Request body

The filters object is shared by every search endpoint. The filter object explains each filter with examples.

filtersobject · AdvancedFilterObjectRequired25 fields
- keywordsarray of string
  Example ["transport"]
- descriptionstring
- time_periodarray of TimePeriodObject
  This TimePeriodObject can fall into different categories based on the request.
  - if spending_level is subawards or subawards is true
    
    See the Subaward Search category defined in SubawardSearchTimePeriodObject
  - otherwise
    
    See the Transaction Search category defined in TransactionSearchTimePeriodObject
- place_of_performance_scopeenum (array)
  Allowed values
  - ["The **default** value below only applies to `geo_layer` values of `county`","`district` and `state`."]
  - domestic
  - foreign
  Default domestic
- place_of_performance_locationsarray of LocationObject
  These fields are defined in the StandardLocationObject
- agenciesarray of AgencyObject4 fields
  - typeenum (string)Required
    Allowed values
    awarding
    funding
  - tierenum (string)Required
    Allowed values
    toptier
    subtier
  - namestringRequired
  - toptier_namestring
    Only applicable when tier is subtier. Ignored when tier is toptier. Provides a means by which to scope subtiers with common names to a specific toptier. For example, several agencies have an "Office of Inspector General". If not provided, subtiers may span more than one toptier.
- recipient_search_textarray of string
  Example ["[`Hampton`","`Roads`]",["Text searched across a recipient’s name","UEI","and DUNS"]]
- recipient_scopeenum (array)
  Allowed values
  - ["The **default** value below only applies to `geo_layer` values of `county`","`district` and `state`."]
  - domestic
  - foreign
  Default domestic
- recipient_locationsarray of LocationObject
  These fields are defined in the StandardLocationObject
- recipient_type_namesarray of string
  Example ["[`category_business`","`sole_proprietorship`]"]
- award_type_codesarray
  List of filterable award types
  Default 02
- award_idsarray of string
  Award IDs surrounded by double quotes (e.g. "SPE30018FLJFN") will perform exact matches as opposed to the default, fuzzier full text matches. Useful for Award IDs that contain spaces or other word delimiters.
  Example ["[`SPE30018FLGFZ`","`SPE30018FLJFN`]"]
- award_amountsarray of AwardAmounts2 fields
  - lower_boundnumber
  - upper_boundnumber
- program_numbersarray of string
  Example ["10.331"]
- naics_codesobject · NAICSCodeObject2 fields
  - requirearray of string
  - excludearray of string
- tas_codesarray of TASCodeObject2 fields
  - requirearray of string
    Example ["[`091`]"]
  - excludearray of string
    Example ["[[`091`","`091-0800`]]"]
- psc_codesenum (PSCCodeObject)
  Supports new PSCCodeObject or legacy array of codes.
- contract_pricing_type_codesarray of string
  Example ["J"]
- set_aside_type_codesarray of string
  Example ["NONE"]
- extent_competed_type_codesarray of string
  Example ["A"]
- treasury_account_componentsarray of TreasuryAccountComponentsObject7 fields
  - atastringNullable
    Allocation Transfer Agency Identifier - three characters
  - aidstringRequired
    Agency Identifier - three characters
  - bpoastringNullable
    Beginning Period of Availability - four digits
  - epoastringNullable
    Ending Period of Availability - four digits
  - astringNullable
    Availability Type Code - X or null
  - mainstringRequired
    Main Account Code - four digits
  - substringNullable
    Sub-Account Code - three digits
- object_classarray of string
- program_activityarray of number
- program_activitiesarray of ProgramActivityObject
  A filter option that supports filtering by a program activity name or code. Please note that if this filter is used at least one of the members of the object, ProgramActivityObject, need to be provided.
- def_codesarray of DEFC
  If the def_codes provided are in the COVID-19 or IIJA group, the query will only return results of transactions where the action_date is on or after the enactment date of the public law associated with that disaster code.
subawardsboolean
True when you want to group by Subawards instead of Awards. Defaulted to False.
spending_levelenum (string)
Group the spending by level. This also determines what data source is used for the totals.
Allowed values
- transactions
- awards
- subawards
Default transactions
scopeenum (string)Required
When fetching transactions, use the primary place of performance or recipient location
Allowed values
- place_of_performance
- recipient_location
geo_layerenum (string)Required
Set the type of areas in the response
Allowed values
- state
- county
- district
- country
geo_layer_filtersarray of string
List of U.S. state codes, U.S. county codes, U.S. Congressional districts, or ISO 3166-1 alpha-3 country codes to show results for.

Try it

Runs against the live API. Responses are real data.

POST/api/v2/search/spending_by_geography/

Request body

Response · 200

scopestring
geo_layerstring
spending_levelenum (string)Required
Spending level value that was provided in the request.
Allowed values
- transactions
- awards
- subawards
resultsarray of GeographyTypeResult6 fields
- aggregated_amountnumberRequired
- display_namestringRequired
- shape_codestringRequired
- populationnumberRequiredNullable
- per_capitanumberRequiredNullable
- total_outlaysnumber
messagesarray of string
An array of warnings or instructional directives to aid consumers of this endpoint with development and debugging.

Example response

{
  "scope": "place_of_performance",
  "geo_layer": "state",
  "spending_level": "transactions",
  "results": [
    {
      "shape_code": "ND",
      "aggregated_amount": 4771026.93,
      "display_name": "North Dakota",
      "population": 762062,
      "per_capita": 6.26
    },
    {
      "shape_code": "NV",
      "aggregated_amount": 26928552.59,
      "display_name": "Nevada",
      "population": 3080156,
      "per_capita": 8.74
    },
    {
      "shape_code": "OH",
      "aggregated_amount": 187505278.16,
      "display_name": "Ohio",
      "population": 11689100,
      "per_capita": 16.04
    }
  ],
  "messages": [
    "For searches, time period start and end dates are currently limited to an earliest date of 2007-10-01.  For data going back to 2000-10-01, use either the Custom Award Download feature on the website or one of our download or bulk_download API endpoints as listed on https://api.usaspending.gov/docs/endpoints.",
    "The 'subawards' field will be deprecated in the future. Set 'spending_level' to 'subawards' instead. See documentation for more information."
  ]
}

Recent changes

April 24, 2025DEV-10281: Add object_class back for unmentioned contracts in slack thread
April 24, 2025DEV-10821: Remove object_class from search endpoint api contracts
January 9, 2025DEV-11551: Update API Contracts
January 2, 2025Mentioned in the January 2, 2025 release notes
December 17, 2024DEV-11400: Update api contracts for search_by_geography

Generated from contracts/v2/search/spending_by_geography.md in the USAspending API repo.