Registry / http-networking / sam-gov-api

sam-gov-api

libraryN/Apyrest✓ verified 26d ago

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.

http-networking data devops

pip install requests

homepage ↗

INSTALL

IMPORT

SIG · SAM-GOV-API

sam-gov-api

http-networkingpythonvN/A

Install

2.4s avg

Import

353ms

Disk

105MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v? · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.368s · 70MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.4s · import 0.338s · 141MB

105MB installed

● package 105MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Session

✓ from requests import Session

✗ from sam_gov_api import SAMClient

Request

✓ from requests import Request

Response

✓ from requests import Response

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

Debug

Known issues

breakingA 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.

affects: all

gotchaSAM.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.

affects: all

gotchaThe 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'.

affects: all

gotchaSAM.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.

affects: all

gotchaPagination is 1-indexed, not 0-indexed. Passing page=0 may return unexpected results or errors.

fix

Start pagination from page=1.

affects: all

gotchaThe 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).

affects: all

gotchaRunning 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.

affects: all

Upgrade

Version history

N/Alatest on PyPI

Audit

Dependencies

requestsrequiredCore HTTP library used for all API calls to SAM.gov endpoints.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

homepagehttps://sam.gov ↗