SAM.gov API Python Client

N/A verified Tue May 12 auth: no python install: stale quickstart: verified

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.

pip install requests

Common errors

error ModuleNotFoundError: No module named 'sam_gov_api' ↓

cause The `sam-gov-api` library has not been installed or is not accessible in the current Python environment.

fix

pip install sam-gov-api

error SyntaxError: invalid syntax ↓

cause Python module names cannot contain hyphens. Attempting to import using the package name `sam-gov-api` instead of the module name `sam_gov_api` results in a syntax error.

fix

import sam_gov_api

error requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: ... ↓

cause The provided SAM.gov API key is either missing, invalid, or does not have the necessary permissions for the requested endpoint.

fix

Ensure you are using a valid SAM.gov API key and that it's correctly passed during client initialization: client = SamGovApi(api_key="YOUR_VALID_API_KEY")

error requests.exceptions.HTTPError: 429 Client Error: Too Many Requests for url: ... ↓

cause You have exceeded the rate limits imposed by the SAM.gov API, causing the server to reject further requests temporarily.

fix

Implement a delay between API calls or integrate a robust rate-limiting strategy (e.g., exponential backoff) into your application logic.

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.

gotcha The test environment produced pip warnings or notices regarding root user permissions, virtual environment recommendations, or outdated pip versions. These messages indicate environmental setup considerations rather than issues with the sam-gov-api library's functionality. ↓

fix It is recommended to use virtual environments (e.g., venv or poetry) for Python projects to manage dependencies cleanly and avoid permission conflicts. Ensure pip is up-to-date and avoid running pip as the 'root' user unless explicitly necessary for system-wide installations (which is generally discouraged for application dependencies).

gotcha Running pip as the 'root' user can result in broken permissions and conflicting behavior with the system package manager. ↓

fix It is recommended to use a virtual environment instead (https://pip.pypa.io/warnings/venv) or to run pip as a non-root user. Use the --root-user-action option if you understand the risks and want to suppress this warning.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - - -

3.10 slim (glibc) - - - -

3.11 alpine (musl) - - - -

3.11 slim (glibc) - - - -

3.12 alpine (musl) - - - -

3.12 slim (glibc) - - - -

3.13 alpine (musl) - - - -

3.13 slim (glibc) - - - -

3.9 alpine (musl) - - - -

3.9 slim (glibc) - - - -

Imports

SAMClient

wrong

from sam_gov_api import Client

correct

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 verified last tested: 2026-05-12

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)}")