USAspending API ReferenceIndependent
Try the API

Spending Explorer

POST/api/v2/spending/
Powers Spending Explorer on usaspending.gov

These endpoints are used to power USAspending.gov's Spending Explorer. This data can be used to drill down into specific subsets of data by level of detail.

The Spending Explorer requires the top-level (or entry point) filter to be one of three types:

  • Budget Function (budget_function)

  • Agency (agency)

  • Object Class (object_class)

General Spending Explorer Data

The general Spending Explorer response will contain only one filter (required), a fiscal year and quarter to limit the data to. The data will include all quarters up to and including the specified quarter in the given fiscal year.

This data represents all government spending in the specified time period, grouped by the data type of your choice.

Note that data is not available prior to FY 2017 Q2.

Note that data for the latest complete quarter is not available until 45 days after the quarter's close.

Specific Spending Explorer

Using the response from the general Spending Explorer, you can drill down to more detailed grouping fields. However, you must limit the scope of your request to one of the top-level groups and, optionally, additional lower-level groups. Each of your groups will combine to become the scope of your request. For example, if you filter by "Department of Justice" and "Salaries and Expenses," you will only see spending breakdowns for "Salaries and Expenses" within "Department of Justice."

Request

curl -X POST 'https://api.usaspending.gov/api/v2/spending/' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "recipient",
  "filters": {
    "fy": "2020",
    "quarter": "1",
    "budget_function": "500",
    "budget_subfunction": "501",
    "federal_account": "5901"
  }
}'

Request body

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

  • typeenum (string)Required
    Allowed values
    • federal_account
    • object_class
    • recipient
    • award
    • budget_function
    • budget_subfunction
    • agency
    • program_activity
  • filtersobject · DetailedFilterRequired10 fields
    • fystringRequired

      Example 2019

    • quarterenum (string)
      Allowed values
      • 1
      • 2
      • 3
      • 4
    • periodenum (string)
      Allowed values
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
      • 8
      • 9
      • 10
      • 11
      • 12
    • agencynumber

      This value is the id returned in the general Spending Explorer response.

    • federal_accountnumber

      This value is the id returned in the previous specific Spending Explorer response.

    • object_classnumber
    • budget_functionnumber
    • budget_subfunctionnumber
    • recipientnumber
    • program_activitynumber

Try it

Runs against the live API. Responses are real data.

POST/api/v2/spending/

Response · 200

  • totalnumberRequiredNullable

    Total should only be null when there are no results.

  • end_datestringRequired

    This is the "as-of" date for the data being returned.

  • resultsarray of SpendingExplorerDetailedResponseRequired8 fields
    • codestringRequired
    • idstringRequired
    • generated_unique_award_idstring

      Durable identifier for an award. This value only returned for award type requests.

    • typestringRequired

      The type will always be equal to the type parameter you provided in the request.

    • namestringRequired
    • amountnumberRequired
    • account_numberstring

      The response includes account_number when the requested type was federal_account.

    • linkstring

      The response includes link when the requested type was agency

Example response
{
  "total": 10758018561.52,
  "end_date": "2019-12-31",
  "results": [
    {
      "amount": 1338785075,
      "id": "EDUCATION, CALIFORNIA DEPARTMENT OF",
      "type": "recipient",
      "name": "EDUCATION, CALIFORNIA DEPARTMENT OF",
      "code": "EDUCATION, CALIFORNIA DEPARTMENT OF",
      "total": 1338785075
    },
    {
      "amount": 1049216400,
      "id": "TEXAS EDUCATION AGENCY",
      "type": "recipient",
      "name": "TEXAS EDUCATION AGENCY",
      "code": "TEXAS EDUCATION AGENCY",
      "total": 1049216400
    },
    {
      "amount": 849061298,
      "id": "EDUCATION DEPARTMENT, NEW YORK STATE",
      "type": "recipient",
      "name": "EDUCATION DEPARTMENT, NEW YORK STATE",
      "code": "EDUCATION DEPARTMENT, NEW YORK STATE",
      "total": 849061298
    },
    {
      "amount": 638939299,
      "id": "EDUCATION, FLORIDA DEPARTMENT OF",
      "type": "recipient",
      "name": "EDUCATION, FLORIDA DEPARTMENT OF",
      "code": "EDUCATION, FLORIDA DEPARTMENT OF",
      "total": 638939299
    },
    {
      "amount": 449552712,
      "id": "EDUCATION, ILLINOIS STATE BOARD OF",
      "type": "recipient",
      "name": "EDUCATION, ILLINOIS STATE BOARD OF",
      "code": "EDUCATION, ILLINOIS STATE BOARD OF",
      "total": 449552712
    },
    {
      "amount": 421294862,
      "id": "EDUCATION, PENNSYLVANIA DEPT OF",
      "type": "recipient",
      "name": "EDUCATION, PENNSYLVANIA DEPT OF",
      "code": "EDUCATION, PENNSYLVANIA DEPT OF",
      "total": 421294862
    },
    {
      "amount": 392298566,
      "id": "DEPARTMENT OF EDUCATION OHIO",
      "type": "recipient",
      "name": "DEPARTMENT OF EDUCATION OHIO",
      "code": "DEPARTMENT OF EDUCATION OHIO",
      "total": 392298566
    },
    {
      "amount": 372229194,
      "id": "EDUCATION, GEORGIA DEPARTMENT OF",
      "type": "recipient",
      "name": "EDUCATION, GEORGIA DEPARTMENT OF",
      "code": "EDUCATION, GEORGIA DEPARTMENT OF",
      "total": 372229194
    }
  ]
}

Recent changes

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

Loading…