Spending By State Territory

Request

curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_category/state_territory/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "recipient_id": "1c3edaaa-611b-840c-bf2b-fd34df49f21f-P",
    "time_period": [
      {
        "start_date": "2019-09-28",
        "end_date": "2020-09-28"
      }
    ]
  },
  "category": "state_territory",
  "limit": 5,
  "page": 1,
  "spending_level": "transactions"
}'

Request body

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

• filtersobject · FilterObjectRequired23 fields

  The filters to find with said category

  • keywordsarray of string

    Example ["transport"]

  • descriptionstring
  • time_periodarray of TimePeriodObject

    This TimePeriodObject can fall into different categories based on the request.

    • if subawards true

      See the Subaward Search category defined in SubawardSearchTimePeriodObject

    • otherwise

      See the Transaction Search category defined in TransactionSearchTimePeriodObject

  • place_of_performance_scopeenum (string)
    Allowed values

    • domestic
    • foreign
  • place_of_performance_locationsarray of LocationObject

    These fields are defined in the StandardLocationObject

  • agenciesarray of AgencyObject3 fields

    • typeenum (string)Required
      Allowed values

      • awarding
      • funding
    • tierenum (string)Required
      Allowed values

      • toptier
      • subtier
    • namestringRequired

      Example Department of Defense

  • recipient_search_textarray of string

    Example ["Hampton"]

  • recipient_idstring

    A unique identifier for the recipient which includes the recipient hash and level. This filter is not supported by subawards.

  • recipient_scopeenum (string)
    Allowed values

    • domestic
    • foreign
  • recipient_locationsarray of LocationObject

    These fields are defined in the StandardLocationObject

  • recipient_type_namesarray of string

    Example ["category_business"]

  • 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

      Example 1000000

  • program_numbersarray of string

    Example ["10.331"]

  • naics_codesobject · NAICSCodeObject2 fields

    • requirearray of string

      Example ["33"]

    • excludearray of string

      Example ["3333"]

  • 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"]

  • tas_codesarray of TASCodeObject2 fields

    • requirearray of string

      Example ["[`091`]"]

    • excludearray of string

      Example ["[[`091`","`091-0800`]]"]

  • 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

  • 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.

• limitnumber

  The number of results to include per page

  Example 5

• pagenumber

  The page of results to return based on the limit

  Example 1

• 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

• subawardsboolean

  Determines whether Prime Awards or Sub Awards are searched. This field will be depreciated soon.

Response · 200

• categorystringRequired

  Example state_territory

• spending_levelenum (string)Required

  Spending level value that was provided in the request.

  Allowed values

  • transactions
  • awards
  • subawards
• resultsarray of CategoryResultRequired5 fields

  • idnumberRequired

    The id is the database key.

  • namestringRequiredNullable
  • codestringRequiredNullable

    code is a user-displayable code (such as a program activity or NAICS code, but not a database ID). When no such code is relevant, return a null.

  • amountnumberRequired
  • total_outlaysnumberRequiredNullable
• limitnumberRequired

  Example 10

• page_metadataobject · PageMetadataObject2 fields

  • pagenumberRequired
  • hasNextbooleanRequired
• messagesarray of string

  An array of warnings or instructional directives to aid consumers of this endpoint with development and debugging.

{
    "category": "state_territory",
    "spending_level": "transactions",
    "limit": 10,
    "page_metadata": {
        "page": 1,
        "next": 2,
        "previous": null,
        "hasNext": false,
        "hasPrevious": false
    },
    "results": [
        {
            "amount": 31470304471.74,
            "code": "USA",
            "id": null,
            "name": "UNITED STATES",
            "total_outlays": null,
        },
        {
            "amount": 20912107.43,
            "code": "ZAF",
            "id": null,
            "name": "SOUTH AFRICA",
            "total_outlays": null,
        }
    ],
    "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."
    ]
}

Recent changes

• March 18, 2025DEV-11927: Update recipient_id description on API contracts where present
• February 12, 2025DEV-11522: Update API documentation
• January 9, 2025DEV-11398: Updating contracts to remove spaces
• January 9, 2025DEV-11398: Updating Contracts and spending by category view
• January 9, 2025DEV-11551: Update API Contracts

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