Award Download

POST/api/v2/download/awards/

Powers Custom award and account data on usaspending.gov How the Download Center works

This endpoint is used by the Advanced Search download page.

This route sends a request to the backend to begin generating a zipfile of award data in CSV form for download.

Request

curl -X POST 'https://api.usaspending.gov/api/v2/download/awards/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "agencies": [
      {
        "type": "awarding",
        "tier": "toptier",
        "name": "Department of Agriculture"
      }
    ],
    "keywords": [
      "Defense"
    ]
  },
  "columns": [
    "assistance_award_unique_key",
    "award_id_fain",
    "award_id_uri",
    "sai_number",
    "total_funding_amount"
  ]
}'

Request body

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

columnsarray of string
filtersobject · FiltersRequired26 fields
- agenciesarray of Agency4 fields
  - namestringRequired
  - tierenum (string)Required
    Allowed values
    toptier
    subtier
  - typeenum (string)Required
    Allowed values
    funding
    awarding
  - toptier_namestring
    Provided when the name belongs to a subtier agency
- award_amountsarray of AwardAmount2 fields
  - lower_boundnumber
  - upper_boundnumber
- 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.
- award_type_codesarray of string
- contract_pricing_type_codesarray of string
- def_codesarray of DEFC
  List of Disaster Emergency Fund (DEF) Codes (DEFC) defined by legislation at the time of writing. A list of current DEFC can be found here.
- extent_competed_type_codesarray of string
- federal_account_idsarray of string
- keywordsarray of string
- legal_entitiesarray of string
- naics_codesobject · NAICSCodeObject2 fields
  - requirearray of string
    Example ["33"]
  - excludearray of string
    Example ["3333"]
- object_class_idsarray of string
- place_of_performance_locationsarray of Location7 fields
  - countrystringRequired
  - statestring
  - countystring
  - citystring
  - district_originalstring
    A 2 character code indicating the congressional district
    
    When provided, a state must always be provided as well.
    
    When provided, a county must never be provided.
    
    When provided, country must always be "USA".
    
    When provided, district_current must never be provided.
  - district_currentstring
    A 2 character code indicating the current congressional district
    
    When provided, a state must always be provided as well.
    
    When provided, a county must never be provided.
    
    When provided, country must always be "USA".
    
    When provided, district_original must never be provided.
  - zipstring
- place_of_performance_scopestring
- program_activity_idsarray of string
- program_numbersarray of string
- psc_codesenum (PSCCodeObject)
  Supports new PSCCodeObject or legacy array of codes.
- recipient_locationsarray of Location7 fields
  - countrystringRequired
  - statestring
  - countystring
  - citystring
  - district_originalstring
    A 2 character code indicating the congressional district
    
    When provided, a state must always be provided as well.
    
    When provided, a county must never be provided.
    
    When provided, country must always be "USA".
    
    When provided, district_current must never be provided.
  - district_currentstring
    A 2 character code indicating the current congressional district
    
    When provided, a state must always be provided as well.
    
    When provided, a county must never be provided.
    
    When provided, country must always be "USA".
    
    When provided, district_original must never be provided.
  - zipstring
- recipient_scopestring
- recipient_search_textstring
- set_aside_type_codesarray of string
- recipient_type_namesarray of string
- tas_codesarray of TASCodeObject2 fields
  - requirearray of string
    Example ["[`091`]"]
  - excludearray of string
    Example ["[[`091`","`091-0800`]]"]
- time_periodarray of TimePeriod3 fields
  - start_datestringRequired
  - end_datestringRequired
  - date_typeenum (string)
- transaction_keyword_searchstring
  Filter awards by keywords in the award's transactions.
- 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
file_formatenum (string)
The format of the file(s) in the zip file containing the data.
Allowed values
- csv
- tsv
- pstxt
Default csv
limitnumber

Try it

Runs against the live API. Responses are real data.

POST/api/v2/download/awards/

Request body

Response · 200

status_urlstringRequired
The endpoint used to get the status of a download.
file_namestringRequired
Is the name of the zipfile containing CSVs that will be generated (file_name is timestamp followed by _transactions or _awards).
file_urlstringRequired
The URL for the file.
download_requestobjectRequired
The JSON object used when processing the download.

Example response

{
  "status_url": "http://localhost:8000/api/v2/download/status?file_name=PrimeAwardSummariesAndSubawards_2020-01-13_H21M05S48397603.zip",
  "file_name": "PrimeAwardSummariesAndSubawards_2020-01-13_H21M05S48397603.zip",
  "file_url": "/csv_downloads/PrimeAwardSummariesAndSubawards_2020-01-13_H21M05S48397603.zip",
  "download_request": {
    "columns": [
      "assistance_award_unique_key",
      "award_id_fain",
      "award_id_uri",
      "sai_number",
      "total_funding_amount"
    ],
    "download_types": [
      "awards",
      "sub_awards"
    ],
    "file_format": "csv",
    "filters": {
      "agencies": [
        {
          "type": "awarding",
          "tier": "toptier",
          "name": "Department of Agriculture"
        }
      ],
      "award_type_codes": [
        "02",
        "03",
        "04",
        "05",
        "06",
        "07",
        "08",
        "09",
        "10",
        "11",
        "A",
        "B",
        "C",
        "D",
        "IDV_A",
        "IDV_B",
        "IDV_B_A",
        "IDV_B_B",
        "IDV_B_C",
        "IDV_C",
        "IDV_D",
        "IDV_E",
        "-1"
      ],
      "keywords": [
        "Defense"
      ],
      "time_period": [
        {
          "date_type": "action_date",
          "end_date": "2020-01-13",
          "start_date": "1000-01-01"
        }
      ]
    },
    "limit": 500000,
    "request_type": "award"
  }
}

Recent changes

October 31, 2024DEV-10988: Add DEFC object to Data Structures/Filter Objects
October 30, 2024DEV-10988: Add def_codes to filter of award download api contract
July 19, 2023Mentioned in the July 19, 2023 release notes
October 21, 2019Mentioned in the October 21, 2019 release notes
November 1, 2017Mentioned in the November 1, 2017 release notes

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