Federal Contracts & Spending Scraper — USAspending.gov + SAM.gov

Pull US federal contract and grant award data straight from USAspending.gov, the government's own public spending database, and — optionally, if you supply your own free API key — live open contracting opportunities from SAM.gov. Both sources come back in one normalized schema, so you can build a pipeline once and cover both historical awards and active solicitations.

Why this actor

USAspending.gov's award search API is genuinely public: no API key, no login, no rate-limit registration. It covers every prime federal contract and grant since fiscal year 2008 — tens of millions of records, growing every day as new awards post. This actor talks to that API directly (plain JSON over HTTPS, no browser) and normalizes the response into a schema built for how govcon buyers actually work: recipient name, agency, NAICS, PSC, dollar amounts, place of performance, dates.

No actor on the Store currently combines historical USAspending award data with live SAM.gov opportunity data in one normalized output — this one does both, in the same run, same schema.

Data sources

Source	Auth	What it returns
USAspending.gov POST /api/v2/search/spending_by_award/	None — fully public	Historical + active prime contracts and/or grant awards
SAM.gov GET /opportunities/v2/search	Your own free API key (optional)	Live, open contracting opportunities/solicitations

USAspending.gov (primary, always on)

This is the same API that powers usaspending.gov's own search page. No key required, verified live against the real endpoint before shipping. It supports filtering by keyword (recipient name), NAICS code, PSC code, awarding agency, date range, and place of performance, and returns both contract awards (award_type_codes: A/B/C/D) and grant/assistance awards (award_type_codes: 02/03/04/05).

Pagination note: USAspending caps simple page-number pagination at 50,000 total results per query (page * limit). This actor stays well under that by capping maxResults and using it directly as the page size, so a single run never approaches the cap.

SAM.gov (secondary, opt-in, requires your own key)

SAM.gov's Opportunities API requires a free API key tied to your own sam.gov account (Account Details → API Key). This actor never obtains, stores, or ships a key of its own — leave includeSamOpportunities off (the default) to skip SAM.gov entirely, or turn it on and paste your own key into samApiKey.

Honesty note: the SAM.gov integration is written directly from SAM.gov's published API documentation (https://open.gsa.gov/api/get-opportunities-public-api/), but it has not been exercised against a real key — SAM.gov keys aren't something this actor can obtain on its own. If you run it and hit an issue, please report it in the Issues tab so it can be fixed against real response data.

Input

Field	Type	Description
keyword	string	Matches recipient/vendor name on USAspending, opportunity title on SAM.gov.
naicsCodes	array of strings	Filter by NAICS industry code(s), e.g. "541511".
pscCodes	array of strings	Filter by Product/Service Code(s), e.g. "D301". USAspending only.
awardingAgency	string	Exact top-tier agency name, e.g. "Department of Defense".
awardCategory	string	"contracts" (default), "grants", or "both".
placeOfPerformanceState	string	Two-letter state code, e.g. "VA".
dateFrom / dateTo	string (YYYY-MM-DD)	Date range. Defaults to the last 30 days.
maxResults	integer	Max normalized records returned, combined across sources. Default 100.
includeSamOpportunities	boolean	Turn on SAM.gov opportunities. Default false.
samApiKey	string (secret)	Your own free SAM.gov API key. Only used when includeSamOpportunities is true.

Example — broad default run (USAspending only, fast)

{
  "awardCategory": "contracts",
  "maxResults": 100
}

Example — targeted search by industry and agency

{
  "keyword": "Booz Allen",
  "naicsCodes": ["541511"],
  "awardingAgency": "Department of Defense",
  "awardCategory": "contracts",
  "dateFrom": "2026-01-01",
  "dateTo": "2026-07-30",
  "maxResults": 200
}

Example — contracts + grants + SAM.gov opportunities (bring your own key)

{
  "naicsCodes": ["541512"],
  "awardCategory": "both",
  "maxResults": 300,
  "includeSamOpportunities": true,
  "samApiKey": "YOUR-SAM-GOV-API-KEY"
}

Output — normalized schema

Every item, regardless of source, has this shape:

Field	Type	Notes
source	string	"usaspending" or "sam.gov"
id	string	Award ID (USAspending) or notice ID (SAM.gov)
recordType	string	"award" or "opportunity"
title / description	string | null	Award description or opportunity title/description
recipientName	string | null	Vendor/recipient name (USAspending only)
recipientUei	string | null	Recipient's Unique Entity Identifier, when disclosed
awardingAgency / awardingSubAgency	string | null	Top-tier agency and sub-agency/component
obligatedAmount	number | null	Dollar amount obligated
potentialAmount	number | null	Total outlays disbursed to date, where reported
awardType	string | null	Contract type, "grant", or opportunity type
naicsCode / naicsDescription	string | null	Industry classification
pscCode / pscDescription	string | null	Product/Service Code
placeOfPerformanceState / placeOfPerformanceCountry	string | null	Where the work is performed
startDate / endDate	string | null	Period of performance / response deadline
postedDate	string | null	Last-modified date (award) or posted date (opportunity)
solicitationNumber	string | null	Solicitation/RFP number. Always null for USAspending awards — this is only populated by the optional SAM.gov opportunities source, which needs your own API key
url	string	Link to the public record on usaspending.gov or sam.gov
scrapedAt	string	ISO timestamp of when this actor fetched the record

Fields the source genuinely doesn't disclose come back as JSON null — never false or 0 — so you can tell "not reported" apart from an actual zero-dollar or negative-flag value.

Sample output items (real run, 2026-07-31)

{
  "source": "usaspending",
  "id": "DEAC0494AL85000",
  "recordType": "award",
  "title": null,
  "description": null,
  "recipientName": "LOCKHEED MARTIN CORP",
  "recipientUei": "FYHNA5WC8XD7",
  "awardingAgency": "Department of Energy",
  "awardingSubAgency": "Department of Energy",
  "obligatedAmount": 48063737196.35,
  "potentialAmount": -4166130.71,
  "awardType": "DEFINITIVE CONTRACT",
  "naicsCode": "561210",
  "naicsDescription": "FACILITIES SUPPORT SERVICES",
  "pscCode": "M181",
  "pscDescription": "OPER OF GOVT R&D GOCO FACILITIES",
  "placeOfPerformanceState": "NM",
  "placeOfPerformanceCountry": "UNITED STATES",
  "startDate": "1993-10-15",
  "endDate": "2017-04-30",
  "postedDate": "2026-07-07 17:57:06",
  "solicitationNumber": null,
  "url": "https://www.usaspending.gov/award/CONT_AWD_DEAC0494AL85000_8900_-NONE-_-NONE-",
  "scrapedAt": "2026-07-31T02:37:13.953Z"
}

{
  "source": "usaspending",
  "id": "DENA0003525",
  "recordType": "award",
  "title": "IGF::CL,CT::IGF CONTRACT AWARD DE-NA0003525 TO THE NATIONAL TECHNOLOGY&ENGINEERING SOLUTIONS OF SANDIA, LLC (NTESS) FOR THE MANAGEMENT AND OPERATION OF THE DEPARTMENT OF ENERGY, NATIONAL NUCLEAR SECURITY ADMINISTRATION'S SANDIA NATIONAL LABORATORIES (SNL)",
  "description": "IGF::CL,CT::IGF CONTRACT AWARD DE-NA0003525 TO THE NATIONAL TECHNOLOGY&ENGINEERING SOLUTIONS OF SANDIA, LLC (NTESS) FOR THE MANAGEMENT AND OPERATION OF THE DEPARTMENT OF ENERGY, NATIONAL NUCLEAR SECURITY ADMINISTRATION'S SANDIA NATIONAL LABORATORIES (SNL)",
  "recipientName": "NATIONAL TECHNOLOGY & ENGINEERING SOLUTIONS OF SANDIA, LLC",
  "recipientUei": "LUJEPCRRT377",
  "awardingAgency": "Department of Energy",
  "awardingSubAgency": "Department of Energy",
  "obligatedAmount": 42571358867.68,
  "potentialAmount": 25931071186.21,
  "awardType": "DEFINITIVE CONTRACT",
  "naicsCode": "561210",
  "naicsDescription": "FACILITIES SUPPORT SERVICES",
  "pscCode": "M1JZ",
  "pscDescription": "OPERATION OF MISCELLANEOUS BUILDINGS",
  "placeOfPerformanceState": "NM",
  "placeOfPerformanceCountry": "UNITED STATES",
  "startDate": "2017-01-18",
  "endDate": "2027-04-30",
  "postedDate": "2026-07-28 19:06:01",
  "solicitationNumber": null,
  "url": "https://www.usaspending.gov/award/CONT_AWD_DENA0003525_8900_-NONE-_-NONE-",
  "scrapedAt": "2026-07-31T02:37:13.953Z"
}

Run summary

At the end of a run, a per-source status is written to the default key-value store under SOURCE_SUMMARY — whether each source was attempted, how many records it returned after dedupe, and a clear message for anything skipped or failed (e.g. "Skipped: includeSamOpportunities is true but no samApiKey was provided"). Records are deduped by source:id across both sources. The run only fails (non-zero exit) if every attempted source failed — a SAM.gov hiccup, for example, won't sink a run that still got USAspending data.

Use cases

• Govcon competitive intelligence — see which vendors are winning contracts in a given NAICS/PSC space, at what dollar amounts, from which agencies.
• Pipeline building — filter by agency, industry, and date range to build a target list of active or recently-awarded contracts and incumbents.
• Market sizing — pull obligated-dollar totals across a NAICS code or agency to estimate addressable market size for a given service line.
• Subcontractor discovery — cross-reference recipient names and NAICS codes to find potential teaming partners already performing similar work.

Pricing

Billed pay-per-result: one dataset item = one award or opportunity record.

Limitations (please read)

• SAM.gov requires your own API key and is untested. The integration is written correctly per SAM.gov's public documentation, but has not been run against a live key. USAspending.gov, the primary and default source, is fully verified live.
• USAspending's simple pagination caps at 50,000 results per query (page * limit). This actor's maxResults cap keeps any single run well under that, but a very broad, very high-maxResults query could theoretically approach it — narrow with naicsCodes, awardingAgency, or a tighter date range if you need more than that.
• pscCodes and placeOfPerformanceState apply to USAspending only — SAM.gov's public API doesn't expose the exact same filter shape for PSC, so that field is passed through to SAM.gov as its own ccode parameter, not guaranteed to filter identically.
• title/description on USAspending awards is often the contract's own free-text description, not a short human title — some agencies write these in all caps with internal shorthand (e.g. "IGF::CL,CT::..."). That's the government's own data, not a normalization choice.
• Data reflects a single point-in-time snapshot of each source's public feed at the moment the actor ran.