A python library that provides an object-relational mapping layer to the USAspending.gov API.
USASpending.gov is the official federal database for tracking U.S. government spending, and provides extensive data on federal contracts, grants, and other awards since 2007-10-01, enabling citizens to track how federal money is spent.
The platform has a comprehensive API for querying the data, but the API is complex and can be cumbersome to work with. This library provides an abstraction layer and other quality-of-life improvements to enable rapid development of applications that consume USASpending data.
🔗 ORM-Style Chained Interface - Access related data through object associations (e.g., award.recipient.location.city) inspired by ActiveRecord and SQLAlchemy. Navigate related data without manual API calls.
🔎 Comprehensive Award Queries - Build complex searches with chainable filters for agencies, award types, fiscal years, and more.
⚡️ Smart Caching & Rate Limiting - Optional file-based caching to dramatically improve performance for repeated queries. Automatic rate limiting and retry logic handles API throttle limits during bulk operations.
🛡️ Data Normalization and Type Casting - Consistent field naming across resources, with lazy-loading for nested data and automatic type conversion.
🥩 Raw API Output Preserved - Access the original API JSON response via the .raw property on any resource object when you need the underlying data structure.
pip install usaspending-ormRequires Python 3.9 or higher. No API key required.
The library provides a USASpendingClient class that manages the connection to the USASpending API and provides access to various resources such as awards, recipients, agencies, etc. This can be used as a context manager to ensure proper session management
or can be instantiated directly.
from usaspending import USASpendingClientwith USASpendingClient() as client:
award = client.awards.find_by_award_id("80GSFC18C0008")with USASpendingClient() as client:
award = client.awards.find_by_award_id("80GSFC18C0008")
award.recipient.location.full_address # -> 105 Jessup Hall, Iowa City, IA, 52242, United States
award.subawards.count() # -> 100
award.subawards[2].recipient.place_of_performance.district # -> AL-03You can query awards data using the search() method on the client.awards object:
with USASpendingClient() as client:
awards_query = client.awards.search()Search parameters are outlined in the spending_by_award endpoint of the USASpending API. Every search parameter is applied via a matching "snake_case" method name. These methods can be chained together to build complex queries.
awards_query = client.awards.search() \
.agencies({"name":"National Aeronautics and Space Administration", "type":"awarding", "tier":"toptier"}) \
.grants() \
.keywords("Perseverance","Mars")This returns a query object that can be further refined or executed to return results.
The methods .all(), .first(), .count() will trigger a query to the API, as will iterating over the query object.
with USASpendingClient() as client:
# Create query object with chained filters
awards_query = client.awards.search() \
.agency("National Aeronautics and Space Administration") \
.recipient_search_text("Space Exploration Technologies") \
.contracts() \
.fiscal_year(2023) \
.order_by("Award Amount", "desc")
# -> <AwardQuery ...> object, no API call made yet
# Return results count without fetching all records
count = awards_query.count() # -> 8
# Fetch first result (query executes here)
top_spacex_award = awards_query.first()
# Returned value is an Award object with all properties mapped
# and properly typed.
top_spacex_award.total_obligation # -> Decimal('3029850123.69')
top_spacex_award.category # -> "contract"
top_spacex_award.description # -> "The Commercial Crew Program (CCP) contract ...."
# Helper methods provide easy access to common fields without having to account for
# inconsistent naming or nested structures in the raw API response
top_spacex_award.award_identifier # -> "80GSFC18C0008"
top_spacex_award.start_date # -> datetime.date(2016, 12, 30)
top_spacex_award.end_date # -> datetime.date(2023,12,31)
# The resulting object provides a normalized interface to the full Award record,
# and provides access to related data via chained associations
# Recipient information
top_spacex_award.recipient.name # -> "Space Exploration Technologies Corp."
top_spacex_award.recipient.location.city # -> "Hawthorne"
# Award Transactions
last_transaction = top_spacex_award.transactions.order_by("action_date", "desc").first()
last_transaction.action_date # -> datetime.date(2025, 10, 08)
last_transaction.action_type_description # -> "SUPPLEMENTAL AGREEMENT FOR WORK WITHIN SCOPE"The client.downloads resource queues server-side download jobs and returns a DownloadJob
you can poll. Single awards are downloaded by their generated award ID:
job = client.downloads.contract("CONT_AWD_...") # also .assistance(...) and .idv(...)
status = job.wait_for_completion()To download many awards at once, build an awards search and pass it to client.downloads.search().
The same fluent filters used for searching drive the download, which can combine award,
transaction, and subaward data into a single zip archive:
query = (
client.awards.search()
.contracts()
.agency("National Aeronautics and Space Administration")
.fiscal_year(2024)
)
# spending_level defaults to awards, transactions, and subawards when omitted.
job = client.downloads.search(query, spending_level=["awards"], file_format="csv")
status = job.wait_for_completion()The library uses lazy-loading to avoid unnecessary API calls. Missing award and Recipient properties will trigger an API call to fetch the missing data. This means models require an active client session to load missing data on demand.
Use the client as a context manager (recommended) or explicitly call close():
with USASpendingClient() as client:
awards = client.awards.search().agency("National Aeronautics and Space Administration").all()
for award in awards:
# Access lazy-loaded properties inside the context
print(f"{award.recipient.name}: ${award.total_obligation:,.2f}")
print(f"Subawards: {award.subaward_count}")
# Session automatically closed here
# Or explicitly manage session
client = USASpendingClient()
awards = client.awards.search().agency("National Aeronautics and Space Administration").all()
client.close()Accessing related properties after the client session closes raises a DetachedInstanceError:
# This will raise DetachedInstanceError
with USASpendingClient() as client:
awards = client.awards.search().all()
# Client is closed here
# This will raise DetachedInstanceError
print(awards[0].transactions.count())You can also reattach objects to a new session if needed:
# Create objects in one session
with USASpendingClient() as client:
award = client.awards.find_by_award_id("80GSFC18C0008")
# Reattach to a new session to access related properties
with USASpendingClient() as new_client:
award.reattach(new_client)
print(f"Subawards: {award.subawards.count()}") # Works!
# Recursive reattach for nested objects
award.reattach(new_client, recursive=True)
print(f"Recipient: {award.recipient.name}") # Recipient also reattachedThe library uses lazy loading for related data (e.g., award.transactions, award.recipient). When iterating over awards and accessing lazy-loaded properties, each access triggers a separate API call. This is known as the N+1 query problem:
# This triggers N+1 API calls (1 for search + N for details)
for award in client.awards.search().contracts().limit(100):
print(award.recipient.name) # Each access = 1 API callThis is a fundamental limitation of the USASpending API, which does not provide batch endpoints for fetching multiple award details in a single request.
Recommended patterns to minimize API calls:
-
Access only search result properties - Properties returned by the search endpoint don't trigger additional API calls:
for award in client.awards.search().contracts().limit(100): # These properties are included in search results - no extra API calls print(award.award_identifier, award.total_obligation, award.description)
-
Enable caching - Cache responses to avoid repeated fetches for the same data:
from usaspending import config as usaspending_config usaspending_config.configure(cache_enabled=True)
-
Use explicit limits - Set a reasonable
limit()to control the number of results:# Fetch only what you need top_awards = client.awards.search().contracts().limit(10).all()
By default, queries without an explicit limit() will fetch up to 10,000 results to prevent unbounded API calls. You can customize this behavior:
from usaspending import config as usaspending_config
# Change the default limit
usaspending_config.configure(default_result_limit=5000)
# Disable the default limit (not recommended for production)
usaspending_config.configure(default_result_limit=None)By default, caching is disabled. However, enabling caching can dramatically improve performance and reduce API load for repeated queries, especially during development or when working with large datasets.
To enable caching, load the configuration module and set cache_enabled=True before creating a client instance:
from usaspending import config as usaspending_config, USASpendingClient
# Enable with defaults (1 week TTL, file-based storage)
usaspending_config.configure(cache_enabled=True)
with USASpendingClient() as client:
# All queries will now be cached
awards = client.awards.search().agency("National Aeronautics and Space Administration").all()Caching happens at the HTTP request layer. A cached response is reused only when the
HTTP method, endpoint, query parameters, JSON payload, and cache_namespace are identical.
This means:
- Re-running the same query or lazy-loaded detail request can reuse a cached response, even across different
USASpendingClientinstances when they share the same cache namespace. .count(),.all(),.first(), different filter chains, and different pagination pages are separate API calls and are cached separately.- Lazy-loaded associations such as
award.recipientoraward.transactionsstill make their first detail request. Caching only helps when that exact request is repeated later. - Download job creation and status checks intentionally bypass caching because those endpoints are time-sensitive.
The library defaults to file-based caching with a 1-week TTL, but you can customize these settings as needed:
usaspending_config.configure(
cache_enabled=True, # Enable caching
cache_ttl=86400, # Cache for 1 day (default: 1 week)
cache_backend="memory", # "file" or "memory" (default: "file")
)File-based caching (default):
- Persists between Python sessions
- Stored in
~/.cache/usaspendingdirectory - Uses pickle for serialization
- Best for production and development workflows
Cache entries are namespaced using cache_namespace to avoid collisions with other
applications. The default namespace is usaspending-orm. Override this if you need
separate cache pools for different environments or applications.
Memory-based caching:
- Faster access, no disk I/O
- Cleared when Python process ends
- Best for single-session data exploration
- Enable with
cache_backend="memory"
Changing cache settings with config.configure(...) updates subsequent requests. For the
most predictable behavior, configure caching before issuing API calls from a client.
The library applies some sensible defaults that work for most use cases:
- Rate limiting: 1000 calls per 5 minutes (respecting USASpending API limits)
- Caching: disabled by default (see Performance & Caching section above to enable)
Customize these settings before creating a client instance if needed:
from usaspending import config as usaspending_config
# Configure settings before creating the client
usaspending_config.configure(
# Cache settings (caching is disabled by default)
cache_enabled=True, # Enable caching
# Set file-cache directory (default: ~/.cache/usaspending)
cache_dir="/tmp/usaspending_cache",
# Cache key namespace (default: "usaspending-orm")
cache_namespace="usaspending-orm",
# Set cache expiration time (default 1 week)
cache_ttl=86400,
# Set cache backend to be in-memory "memory" or "file" for file-based caching via pickle (default: "file")
cache_backend="memory",
# Set rate limiting parameters
# Set number of calls allowed within the rate limit period (default: 1000)
rate_limit_calls=500,
# Rate limit period (in seconds, default: 300)
rate_limit_period=60,
# Set HTTP request parameters (default: max_retries=3, timeout=30)
# Set number of retries for failed requests (default: 3)
max_retries=5,
# Set delay between retries in seconds (default: 1.0)
retry_delay=10.0,
# Set exponential backoff factor for retries (default: 2.0)
retry_backoff=2.0,
# Set request timeout in seconds (default: 30)
timeout=60 # Longer timeout for slow connections (default: 30)
)The library provides detailed logging, which you can configure in your application:
import logging
from usaspending import USASpendingClient
# Configure root logger (affects all loggers)
logging.basicConfig(
level=logging.DEBUG,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)Security Note: When DEBUG logging is enabled, the library logs full API request payloads including query parameters and filter criteria. In a business context, this could expose search patterns or analysis focus areas. Use DEBUG logging only in development environments and ensure log files have appropriate access controls.
When using file-based caching (the default), be aware of these security considerations:
- Pickle Serialization: File-based caching uses Python's
picklemodule for serialization. If an attacker gains write access to your cache directory, they could potentially inject malicious serialized objects. - Cache Directory Permissions: The cache directory (
~/.cache/usaspending/by default) should have appropriate permissions (e.g., 0700 on Unix systems). - Shared Systems: For shared or multi-tenant systems, consider using memory-based caching (
cache_backend="memory") or disabling caching entirely.
USASpending Python Wrapper is under active development. The API is stabilizing but may change as we refine the abstractions based on real-world usage. We welcome feedback on the interface design and feature priorities.
The library includes both unit tests and integration tests.
Unit tests run against mocked API responses and do not require network access:
# Run all unit tests (default, excludes integration tests)
pytest
# Run with verbose output
pytest -vIntegration tests hit the real USASpending.gov API to verify end-to-end functionality. These are excluded by default to avoid network dependencies during normal development.
# Run only integration tests
pytest -m integration
# Run integration tests with verbose output
pytest -m integration -v
# Run all tests including integration
pytest -m ""Integration tests verify connectivity and response structure for all major resources including awards, recipients, agencies, spending, and award-related data (transactions, funding, subawards).
We welcome contributions to improve and expand the implementation and functionality.
This library was initially developed to serve the needs of The Planetary Society's Space Policy and Advocacy team in tracking and analyzing National Aeronautics and Space Administration contract data, and is in-use in our internal and external data tools.
We have open-sourced the project to enable others to better use USASpending data.
The Planetary Society is an independent nonprofit organization that empowers the world's citizens to advance space science and exploration. The organization is supported by individuals across the world, and does not accept government grants nor does it have major aerospace donations.
Please consider supporting our work by becoming a member.
MIT License