USAspending API ReferenceIndependent
Try the API

Spending by Award

POST/api/v2/search/spending_by_award/
Powers Advanced Search on usaspending.gov How Advanced Search works

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

This endpoint takes award filters and fields, and returns the fields of the filtered awards.

Request

curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_award/' \
  -H 'Content-Type: application/json' \
  -d '{
  "subawards": false,
  "limit": 10,
  "page": 1,
  "filters": {
    "award_type_codes": [
      "A",
      "B",
      "C"
    ],
    "time_period": [
      {
        "start_date": "2018-10-01",
        "end_date": "2019-09-30"
      }
    ]
  },
  "fields": [
    "Award ID",
    "Recipient Name",
    "Start Date",
    "End Date",
    "Award Amount",
    "Awarding Agency",
    "Awarding Sub Agency",
    "Contract Award Type",
    "Award Type",
    "Funding Agency",
    "Funding Sub Agency"
  ]
}'

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.

    • 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

        Example Office of Inspector General

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

        Example Department of the Treasury

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

      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_codesenum (NAICSCodeObject)
    • 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

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

    • object_classesarray of string

      A filter option that supports filtering by object class codes (not names). Only for 'awards'.

    • def_codesarray of DEFC

      If the def_codes provided are in the COVID-19 or IIJA group and the subaward flag is set to False, the query will only return prime awards that have at least one File C record with the supplied DEFC and also have non-zero COVID-19 or IIJA related obligations or outlays. If the def_codes provided are in the COVID-19 or IIJA group and the subaward parameter is set to True, the query will only return results that have a sub_action_date on or after the enactment date of the public law associated with that disaster code.

      • Example: Providing the Z DEF code and setting the subaward parameter to True will only return results where the sub_action_date is on or after 11/15/2021 since this is the enactment date of the public law associated with disaster code Z.
    • award_unique_idstring
  • fieldsarrayRequired

    The SpendingByAward API can accept any of the following fields based on whether awards or subawards are being searched. Awards are searched by default, however the subawards can be searched by setting the subawards field to "True".

  • limitnumber

    How many results are returned. If no limit is specified, the limit is set to 10.

  • orderenum (string)

    Indicates what direction results should be sorted by. Valid options include asc for ascending order or desc for descending order.

    Allowed values
    • desc
    • asc

    Default desc

  • pagenumber

    The page number that is currently returned.

  • sortstring

    Optional parameter indicating what value results should be sorted by. Valid options are any of the fields in the JSON objects in the response. Defaults to the first field provided.

  • subawardsboolean

    True when you want to group by Subawards instead of Awards.

    Default false

  • last_record_unique_idnumber

    The unique id of the last record in the results set. Used in the experimental Elasticsearch API functionality.

  • last_record_sort_valuestring

    The value of the last record that is being sorted on. Used in the experimental Elasticsearch API functionality.

  • spending_levelenum (string)

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

    Allowed values
    • awards
    • subawards

    Default awards

Try it

Runs against the live API. Responses are real data.

POST/api/v2/search/spending_by_award/

Response · 200

  • spending_levelenum (string)Required

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

    Allowed values
    • awards
    • subawards

    Default awards

  • limitnumberRequired
  • resultsarray of SpendingByAwardResponseRequired52 fields
    • internal_idnumberRequired
    • Award Amountnumber
    • Total Outlaysnumber
    • Award IDstring
    • Award TypestringNullable
    • Awarding Agency CodestringNullable
    • Awarding AgencystringNullable
    • awarding_agency_idnumberNullable
    • Awarding Sub Agency CodestringNullable
    • Awarding Sub AgencystringNullable
    • Base Obligation Datestring
    • CFDA NumberstringNullable

      Assistance awards only

    • Contract Award Typestring

      Procurement awards only

    • DescriptionstringNullable
    • End Datestring
    • Funding Agency CodestringNullable
    • Funding AgencystringNullable
    • Funding Sub Agency CodestringNullable
    • Funding Sub AgencystringNullable
    • generated_internal_idstring
    • Issued DatestringNullable
    • Last Date to OrderstringNullable

      Procurement IDVs only

    • Last Modified Datestring
    • Loan Valuenumber

      Assistance awards only

    • Period of Performance Current End DatestringNullable
    • Period of Performance Start Datestring
    • Place of Performance City Codenumber
    • Place of Performance Country CodestringNullable
    • Place of Performance State CodenumberNullable
    • Place of Performance Zip5number
    • COVID-19 Outlaysnumber
    • COVID-19 Obligationsnumber
    • Infrastructure Outlaysnumber
    • Infrastructure Obligationsnumber
    • def_codesarray of string
    • Prime Award IDstringNullable

      Sub-Awards only, returns the ID (piid/fain/uri) of the prime award.

    • Prime Recipient NamestringNullable

      Sub-Awards only, returns the name of the prime award's recipient.

    • prime_award_recipient_idstringNullable

      Sub-Awards only, return the recipient id of the prime award's recipient.

    • prime_award_internal_idstringNullable

      Sub-Awards only, return the award id of the prime award.

    • prime_award_generated_internal_idstring

      Sub-Awards only, return the generated unique award id of the prime award.

    • Recipient DUNS NumberstringNullable
    • Recipient NamestringNullable
    • recipient_idstringNullable

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

    • SAI NumberstringNullable

      Assistance awards only

    • Start Datestring
    • Sub-Award Amountstring

      Sub-Awards only

    • Sub-Award Datestring

      Sub-Awards only

    • Sub-Award IDstring

      Sub-Awards only

    • Sub-Award Typestring

      Sub-Awards only

    • Sub-Awardee Namestring

      Sub-Awards only

    • Subsidy Costnumber

      Assistance awards only

    • agency_slugstringNullable

      Returns with "Awarding Agency", is null when the agency does not have an agency profile page

  • page_metadataobject · PageMetadataObject4 fields
    • pagenumberRequired
    • hasNextbooleanRequired
    • last_record_unique_idnumber
    • last_record_sort_valuestring
  • messagesarray of string

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

Example response
{
  "spending_level": "awards",
  "limit": 0,
  "results": [
    {
      "internal_id": 0,
      "def_codes": []
    }
  ],
  "page_metadata": {
    "page": 0,
    "hasNext": false
  },
  "messages": []
}

Recent changes

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

Loading…