Download Count

Request

curl -X POST 'https://api.usaspending.gov/api/v2/download/count/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "keywords": [
      "cheese"
    ],
    "time_period": [
      {
        "start_date": "2019-10-01",
        "end_date": "2020-09-30"
      },
      {
        "start_date": "2010-10-01",
        "end_date": "2011-09-30"
      }
    ],
    "recipient_type_names": [
      "higher_education"
    ],
    "place_of_performance_locations": [
      {
        "country": "USA",
        "state": "WI"
      }
    ],
    "psc_codes": {
      "require": [
        [
          "Product",
          "10",
          "1035"
        ]
      ]
    }
  },
  "spending_level": "awards"
}'

Request body

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

• filtersobject · AdvancedFilterObjectRequired21 fields

  • keywordsarray of string

    Example ["transport"]

  • time_periodarray of TimePeriodObject

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

  • recipient_idstring

    A hash of recipient UEI, DUNS, name, and level. A unique identifier for recipients, used for profile page urls. 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

      Example 090

    • 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

      Example 1000

    • substringNullable

      Sub-Account Code - three digits

• spending_levelenum (string)
  Allowed values

  • subawards
  • transactions
  • awards

  Default transactions

Response · 200

• calculated_transaction_countnumberRequired

  The calculated count of all transactions which would be included in the download files.

• maximum_transaction_limitnumberRequired

  The current allowed maximum number of transactions in a row-limited download. Visit https://www.usaspending.gov/download_center/custom_award_data to download larger volumes of data.

• transaction_rows_gt_limitbooleanRequired

  A boolean returning whether the transaction count is over the maximum row limit.

• calculated_countnumberRequired

  The calculated count of Awards, Transactions, or Subawards included in the download files.

• spending_levelstringRequired

  The spending_level provided by the user or the default value of transactions.

• maximum_limitnumberRequired

  The current allowed maximum number of Awards, Transactions, or Subawards in a row-limited download. Visit https://www.usaspending.gov/download_center/custom_award_data to download larger volumes of data.

• rows_gt_limitbooleanRequired

  A boolean returning whether the Awards, Transactions, or Subawards count is over the maximum row limit.

• messagesarray of string

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

{
  "calculated_transaction_count": 87343,
  "maximum_transaction_limit": 500000,
  "transaction_rows_gt_limit": false,
  "calculated_count": 87343,
  "spending_level": "awards",
  "maximum_limit": 500000,
  "rows_gt_limit": false,
  "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
• October 8, 2024Mentioned in the October 8, 2024 release notes
• October 2, 2024Updated api contract
• August 7, 2020Mentioned in the August 07, 2020 release notes
• November 1, 2017Mentioned in the November 1, 2017 release notes

Generated from contracts/v2/download/count.md in the USAspending API repo.