USAspending API

The USAspending API provides public access to comprehensive U.S. government spending data, including federal awards (contracts, grants, geographic and agency breakdowns) and account-level data such as federal employee compensation.

Note on Versioning: The API is currently in V2. All V1 endpoints are considered Deprecated.

The USAspending API does not currently require any authorization to access its endpoints.

When making requests, you can expect the following standard HTTP status codes:

• 200: The request was successful.
• 400: The request was malformed (check your parameters or JSON body).
• 500: A server-side error occurred.

A successful 200 OK response returns a JSON object containing three main components:

1. totals: Aggregated spending data for the entire filtered set.

   • obligation (required, number)
   • outlay (required, number)
   • award_count (optional, number)
   • total_budgetary_resources (optional, number)

2. results: An array of Result objects representing the hierarchy of Federal Accounts/TAS.

   • Each Result includes id, code, description, award_count, obligation, outlay, and total_budgetary_resources.
   • children (optional): An array of nested Result objects representing sub-accounts.

3. page_metadata: Information about the current page and navigation.

   • page, next, previous, hasNext, hasPrevious, total, limit.

Award filtering is implemented using the award.py and transaction.py modules. To filter results, you must pass a filters dictionary to the API. The structure of this dictionary (the available filter keys and their expected values) is defined in the project's external documentation schema.

Currently, filtering is static, meaning the available filter keys are predefined in the source code.

# Filtering is performed by passing a dictionary of filters
filters = {
    "id": 1,
    "agency_name": "test"
}

The usaspending_api.common.etl.postgres module provides several abstraction objects to simplify database introspection and SQL generation during ETL (Extract, Transform, Load) processes. These objects reduce boilerplate when performing in-place creates, updates, and deletes on tables with many columns.

Key objects include:

• ETLTable: Represents a standard database table. It abstracts database introspection and encapsulates table properties.
• ETLTemporaryTable: Functions like ETLTable but is specifically designed to work with temporary tables.
• ETLDBLinkTable: A read-only ETLTable that resides on a remote server accessible via a dblink connection.
• ETLQuery: A read-only object that treats a SQL query as if it were a table.
• ETLQueryFile: A read-only object that treats a SQL query read from a file as if it were a table.

When constructing a search request, you can combine multiple filter objects into a single JSON object. By default, different filter keys are combined using AND logic (e.g., a keyword filter AND a time period filter). However, some specific filters (like agencies or time_period arrays) allow for internal OR logic within their own structure.

{
    "keywords": ["example search text"],
    "time_period": [
        {
            "start_date": "2001-01-01",
            "end_date": "2001-01-31"
        }
    ]
}

The API returns a 200 OK response containing a results array of AwardingAgencyOfficeMatchObject items and a messages array for warnings or instructions.

An AwardingAgencyOfficeMatchObject can represent one of three hierarchical levels:

1. Top-tier Agency: Contains toptier_agency details, an array of subtier_agencies, and an array of offices.
2. Sub-tier Agency: Contains subtier_agency details, the parent toptier_agency, and an array of offices.
3. Office: Contains office details, the parent toptier_agency, and the parent subtier_agency.

A successful 200 OK response returns a JSON object containing three main components:

1. totals (required): Aggregated financial data for the entire filtered set, including award_count, face_value_of_loan, obligation, and outlay.
2. results (required): An array of Result objects. Each object contains detailed program information such as code, description, cfda_federal_agency, cfda_objectives, and eligibility details (applicant_eligibility, beneficiary_eligibility).
3. page_metadata (required): Information about the current page, including page, next, previous, hasNext, hasPrevious, total, and limit.

This document defines the standard template (Format 1A) used for documenting USAspending API endpoints. It provides a structured way to describe endpoint paths, HTTP methods, required parameters, and the expected JSON response structures (including arrays and single objects).

# Short Endpoint Name [/api/v2/this/is/your/{param_for_endpoint}/]

## GET

+ Parameters
    + `param_for_endpoint`: `endpoint` (required, string)

+ Response 200 (application/json)
    + Attributes
        + `data_structure_array` (required, array[ForTheArray], fixed-type)
        + `single_data_structure` (optional, SampleSingleObject)
        + `name` (required, enum[string])

# Data Structures

## ForTheArray
+ `value_1` (optional, string)
+ `value_2` (optional, string)

## SampleSingleObject
+ `value_1` (required, number)
+ `value_2` (optional, string)
+ `value_3` (optional, number, nullable)