SAM.gov API Python Client

N/A · active · verified Tue Mar 17

Python wrapper for the SAM.gov (System for Award Management) public API. Provides access to entity registration data, opportunities, exclusions, and other federal procurement data from SAM.gov. Simplifies authentication and pagination when querying the SAM.gov API endpoints.

Warnings

breaking A valid SAM.gov API key is required for all requests. Without it, every call returns a 403 Forbidden error.
Fix: Register at https://sam.gov and request a public API key. Pass it via SAMClient(api_key='your-key') or set SAM_GOV_API_KEY environment variable.
gotcha SAM.gov API has strict rate limits (typically 10 requests per second for public keys). Exceeding the limit returns HTTP 429 responses with no automatic retry.
Fix: Implement your own rate limiting or exponential backoff between calls when making bulk queries.
gotcha The package name uses hyphens (sam-gov-api) but the Python import uses underscores (sam_gov_api).
Fix: Use 'from sam_gov_api import SAMClient' not 'from sam-gov-api import SAMClient'.
gotcha SAM.gov API response structures vary between endpoints (entities, opportunities, exclusions). Fields are not guaranteed to be present in every response record.
Fix: Always use .get() with defaults when accessing nested response fields to avoid KeyError exceptions.
gotcha Pagination is 1-indexed, not 0-indexed. Passing page=0 may return unexpected results or errors.
Fix: Start pagination from page=1.

Install

pip install requests HTTP client (no official PyPI package)

Imports

SAMClient
```
from sam_gov_api import SAMClient
```
The main client class is SAMClient, not Client.
sam_gov_api
```
import sam_gov_api
```
Top-level import for accessing module attributes and constants.

Quickstart

Minimal example searching for entity registrations on SAM.gov by keyword.

import os
import requests

api_key = os.environ.get("SAM_GOV_API_KEY", "DEMO_KEY")
resp = requests.get(
    "https://api.sam.gov/entity-information/v3/entities",
    params={"api_key": api_key, "purposeOfRegistrationCode": "Z2", "entityEFTIndicator": "", "samRegistered": "Yes"},
    headers={"Accept": "application/json"}
)
resp.raise_for_status()
data = resp.json()
print(f"Total records: {data.get('totalRecords', 0)}")

view raw JSON →