USAspending API ReferenceIndependent
Try the API

Spending By Category

POST/api/v2/search/spending_by_category/
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 returns a list of the top results of specific categories sorted by the total amounts in descending order.

Request

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

Request body

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

  • categoryenum (string)Required
    Allowed values
    • awarding_agency
    • awarding_subagency
    • cfda
    • country
    • county
    • defc
    • district
    • federal_account
    • funding_agency
    • funding_subagency
    • naics
    • object_class
    • program_activity
    • psc
    • recipient_duns
    • recipient_parent_duns
    • state_territory
    • tas
  • filtersobject · AdvancedFilterObjectRequired24 fields

    The filters to find with said category

    • keywordsarray of string

      Example ["transport"]

    • descriptionstring
    • time_periodarray of TimePeriodObject

      See TimePeriodObject for the TimePeriodObject definition by individual category.

    • place_of_performance_scopeenum (string)
      Allowed values
      • domestic
      • foreign
    • 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 (string)
      Allowed values
      • domestic
      • foreign
    • 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
    • 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

  • pagenumber

    The page of results to return based on the limit

  • spending_levelenum (string)

    Group the spending by level. This also determines what data source is used for the totals.

    Allowed values
    • transactions
    • awards
    • subawards
    • award_financial Only supported by the defc category; filters to an award(s) and uses obligation and outlays from the linked File C records

    Default transactions

  • subawardsboolean

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

Try it

Runs against the live API. Responses are real data.

POST/api/v2/search/spending_by_category/

Response · 200

  • categorystringRequired
  • spending_levelenum (string)Required

    Spending level value that was provided in the request.

    Allowed values
    • transactions
    • awards
    • subawards
  • resultsarray of CategoryResultRequired6 fields
    • idnumberRequired

      The id is the database key.

    • recipient_idstringNullable

      A unique identifier for the recipient which includes the recipient hash and level.

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

Example response
{
  "category": "",
  "spending_level": "transactions",
  "results": [
    {
      "id": 0,
      "name": null,
      "code": null,
      "amount": 0,
      "total_outlays": null
    }
  ],
  "limit": 0,
  "page_metadata": {
    "page": 0,
    "hasNext": false
  },
  "messages": []
}

Recent changes

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

Loading…