USAspending API ReferenceIndependent
Try the API

How the Download Center works

Request a file, poll until it is ready, then fetch it. The same pattern covers award, account, and archive files.

Open the page on usaspending.gov 8 calls

The Download Center turns filters into files. Every download, whether from Custom Award Data, Custom Account Data, or an Advanced Search results table, follows the same three steps: ask for a file, wait for it, fetch it.

Why it works this way

Files can hold millions of rows, so they're built by a background job instead of inside the request. The request returns right away with a status_url to poll and the file_url the finished zip will live at. The Paging and downloads page shows the loop in code.

Before you ask

The site checks size before it queues a search download: download/count says how many rows a filter would produce and whether that's over the limit. It also fills its agency and budget function pickers from the list endpoints below, which you can use to build valid requests.

The calls, in order

  1. To fill the agency picker

    POSTList Agencies/api/v2/bulk_download/list_agencies/

  2. For account data: the budget function picker

    GETList Budget Functions/api/v2/budget_functions/list_budget_functions/

  3. Before a search download

    POSTDownload Count/api/v2/download/count/

    Checks the row count against the download limit.

  4. Custom Award Data: submit the request

    POSTBulk Award Download/api/v2/bulk_download/awards/

    Returns a file name and a status URL right away.

  5. Custom Account Data: submit the request

    POSTCustom Account Data/api/v2/download/accounts/

  6. From Advanced Search: download awards, transactions, and subawards together

    POSTSearch Download/api/v2/download/search/

  7. Every few seconds until status is finished

    GETDownload Status/api/v2/download/status

    When it finishes, file_url points to the zip.

  8. Award Data Archive: list the prepackaged files

    POSTList Monthly Files/api/v2/bulk_download/list_monthly_files/

Sources

Traced from these files in the public usaspending-website repo:

Loading…