# SAM.gov & UK Contracts Finder Tenders Scraper (`tinyrex/us-uk-tenders-scraper`) Actor

Search US federal contract opportunities on SAM.gov and UK public tenders on Contracts Finder via official APIs. Keywords, dates, only-new mode. ~$2.50/1k notices; failed free.

- **URL**: https://apify.com/tinyrex/us-uk-tenders-scraper.md
- **Developed by:** [TinyRex](https://apify.com/tinyrex) (community)
- **Categories:** Lead generation, Developer tools, AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 notices

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## SAM.gov & UK Contracts Finder Tenders Scraper – US Federal & UK Public Procurement

Search **US federal contract opportunities on SAM.gov** and **UK public tenders on Contracts Finder** through their **official public APIs**, and get clean, structured notices: title, buyer, country, dates, deadlines, value, CPV/NAICS, procedure type and a direct notice URL. Filter by keywords and publication window, or turn on **Only new notices** for a daily tender alert feed.

**Why this one:** no fragile HTML scraping — SAM.gov Get Opportunities Public API and the UK Contracts Finder OCDS Search API only. Pay per notice saved (~**$2.50 / 1,000**). Empty or failed runs are **free** apart from the tiny start fee; notices skipped as already seen are **free**.

### Why this scraper

- **Official sources.** US: [SAM.gov Get Opportunities Public API](https://open.gsa.gov/api/get-opportunities-public-api/). UK: [Contracts Finder OCDS Search](https://www.contractsfinder.service.gov.uk/apidocumentation/Notices/1/GET-Published-Notice-OCDS-Search) under the [Open Government Licence v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).
- **One Actor, two markets.** Pull US and UK public procurement in the same schema, or run either source alone.
- **Fields that matter.** `source`, `noticeId`, title, description, publication and deadline dates, `isOpen`, buyer, value, currency, CPV/NAICS, procedure and notice type, notice URL.
- **Tender alerts.** Enable *Only new notices* and schedule the Actor — each run returns only notices you have not seen under that state key.
- **Companion to TED.** Pair with [TED EU Tenders Scraper](https://apify.com/tinyrex/ted-tenders-scraper) and [EU Grants Scraper](https://apify.com/tinyrex/eu-grants-scraper) for EU + US + UK coverage.

### What you get

| Field | Example |
|---|---|
| source, noticeId | contracts-finder, ocds-b5fd17-… |
| title, description | Northampton College – Media planning & Buying Services |
| publicationDate, deadlineDate, isOpen | 2026-10-09, 2026-11-04, true |
| buyerName, buyerCountry | Northampton College, United Kingdom |
| estimatedValue, currency | 250000, GBP |
| cpvOrNaics / naicsCode | 79340000 or 541511 |
| procedureType, noticeType | Open procedure, tender |
| noticeUrl, documentsUrl | https://www.contractsfinder.service.gov.uk/Notice/… |

### Use cases

- **Bid and BD teams.** Daily feed of new US federal and UK public opportunities in your keywords or NAICS/CPV area.
- **Lead generation.** Contracting authorities that are actively buying, with notice links.
- **Market intelligence.** Track awards and open solicitations across both markets in one pipeline.
- **Tender portals and consultants.** Feed your CRM or alerting product from official APIs.

### How to use

1. Pick **Sources**: UK Contracts Finder (no key), SAM.gov (needs a free public API key), or both.
2. Optional: keywords, last N days (default 7), max notices (default 50).
3. For SAM.gov: create a free account at [sam.gov](https://sam.gov), open **Account Details**, generate a **public API key**, paste it into **SAM.gov public API key**.
4. Run, or schedule daily with **Only new notices** on.

#### Example input (UK only – works without a SAM key)

```json
{
  "sources": ["contracts-finder"],
  "keywords": ["software"],
  "publishedWithinDays": 14,
  "maxResults": 50,
  "cfStages": ["tender"]
}
```

#### Example input (both sources)

```json
{
  "sources": ["sam.gov", "contracts-finder"],
  "keywords": ["cybersecurity"],
  "publishedWithinDays": 7,
  "maxResults": 100,
  "samApiKey": "YOUR_SAM_PUBLIC_API_KEY",
  "onlyNew": true,
  "stateKey": "cyber-us-uk"
}
```

#### Example output (shortened)

```json
{
  "source": "contracts-finder",
  "noticeId": "ocds-b5fd17-eba856aa-b8d6-4d73-b794-8420ea10a3d9",
  "title": "CA18543 - Northampton College - Media planning & Buying Services",
  "publicationDate": "2026-10-09",
  "deadlineDate": "2026-11-04",
  "isOpen": true,
  "buyerName": "Northampton College",
  "buyerCountry": "United Kingdom",
  "estimatedValue": 250000,
  "currency": "GBP",
  "cpvOrNaics": "79340000",
  "procedureType": "Open procedure",
  "noticeType": "tender",
  "noticeUrl": "https://www.contractsfinder.service.gov.uk/Notice/d2301388-4ca6-48fc-805d-eb2e5793377e",
  "scrapedAt": "2026-10-10T07:00:00.000Z"
}
```

Run totals and per-source stats are saved to the `SUMMARY` record in the run key-value store.

### Pricing

Pay per event:

- **Notice** (`notice`): charged once per notice saved to your dataset (~$0.0025 each, see Pricing tab).
- **Free:** notices skipped as already seen (*Only new*), duplicates in a run, and runs that save nothing (apart from the tiny actor-start fee).

### Limitations

- **SAM.gov requires your own free public API key.** Without it, the Actor skips SAM.gov and still returns UK Contracts Finder results when that source is selected.
- SAM.gov date ranges must be at most one year (API rule). This Actor defaults to the last 7 days.
- Contracts Finder keyword matching is applied client-side on title/description after the official date/stage search.
- Values and descriptions are only as complete as the publishing authority’s notice.
- Respect API rate limits; Contracts Finder may return HTTP 403 if you request too aggressively (the Actor backs off and retries).

### Licence / legal

- **UK Contracts Finder:** public sector information under the [Open Government Licence v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/). Attribution: *Contains public sector information licensed under the Open Government Licence v3.0.*
- **SAM.gov:** this Actor uses only the [Get Opportunities Public API](https://open.gsa.gov/api/get-opportunities-public-api/). It does not scrape the SAM.gov website (scraping is prohibited in the [SAM.gov Terms of Use](https://sam.gov/about/terms-of-use)). Share only data from the public API. U.S. federal government works are generally not protected by copyright in the U.S.; cite SAM.gov / GSA.
- Full licence notes: see `PRICING.md` in the Actor source.

### Related actors

- [TED EU Tenders Scraper](https://apify.com/tinyrex/ted-tenders-scraper) — EU public tenders and awards from TED.
- [EU Grants Scraper](https://apify.com/tinyrex/eu-grants-scraper) — Horizon Europe and other EU funding calls.
- [Contact Details Extractor](https://apify.com/tinyrex/contact-details-extractor) — emails, phones and socials from buyer websites.
- [Tech Stack Detector](https://apify.com/tinyrex/tech-stack-detector) — technologies behind buyer or winner sites.

### FAQ

**Do I need API keys?** Only for SAM.gov (free public key from sam.gov Account Details). Contracts Finder needs none.

**Is this legal?** Yes for the intended use: official public APIs, OGL (UK) and public-domain / government-work norms for SAM public opportunity data. Do not scrape the SAM.gov HTML site.

**How fresh is the data?** Both portals publish continuously; a daily schedule with *Only new notices* catches new opportunities.

# Actor input Schema

## `sources` (type: `array`):

Which official portals to query. Default: both. SAM.gov requires a free public API key (samApiKey).

## `keywords` (type: `array`):

Match notices whose title (and UK description) contains any of these words. Case-insensitive. Leave empty for all notices in the date window.

## `publishedWithinDays` (type: `integer`):

Notices published in the last N days. Ignored when Published from/to are set. 0 with no date range still defaults to 7 days for API safety.

## `publishedFrom` (type: `string`):

Start of publication date range (YYYY-MM-DD). SAM.gov ranges must be ≤ 1 year.

## `publishedTo` (type: `string`):

End of publication date range (YYYY-MM-DD), inclusive.

## `maxResults` (type: `integer`):

Maximum notices to save in this run (across selected sources). Default 50 finishes quickly for Store tests.

## `onlyOpen` (type: `boolean`):

Keep notices whose response/tender deadline is today or later when a deadline is present.

## `includeDescription` (type: `boolean`):

Include truncated description text when the API returns it (UK). SAM.gov often returns a description URL instead of text.

## `onlyNew` (type: `boolean`):

Skip notices already returned in a previous run with the same State key. First run is a baseline.

## `stateKey` (type: `string`):

Named memory for Only new notices. Use different keys for different saved searches.

## `samApiKey` (type: `string`):

Required for SAM.gov. Free key from your SAM.gov Account Details page (https://sam.gov). Never shared; used only for official public API calls. Leave empty to skip SAM.gov.

## `samNaicsCode` (type: `string`):

Optional 2–6 digit NAICS filter for SAM.gov, e.g. 541511.

## `samState` (type: `string`):

Optional US state code for SAM.gov place of performance, e.g. CA, TX, NY.

## `samPtype` (type: `string`):

Optional SAM.gov procurement type code.

## `cfStages` (type: `array`):

UK OCDS procurement stages to include. Default: tender.

## Actor input object example

```json
{
  "sources": [
    "contracts-finder"
  ],
  "keywords": [
    "software"
  ],
  "publishedWithinDays": 7,
  "maxResults": 50,
  "onlyOpen": false,
  "includeDescription": true,
  "onlyNew": false,
  "stateKey": "default",
  "samPtype": "",
  "cfStages": [
    "tender"
  ]
}
```

# Actor output Schema

## `notices` (type: `string`):

Public procurement notices from SAM.gov and/or Contracts Finder.

## `summary` (type: `string`):

Totals, warnings and source stats for the run.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "sources": [
        "contracts-finder"
    ],
    "keywords": [
        "software"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("tinyrex/us-uk-tenders-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "sources": ["contracts-finder"],
    "keywords": ["software"],
}

# Run the Actor and wait for it to finish
run = client.actor("tinyrex/us-uk-tenders-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "sources": [
    "contracts-finder"
  ],
  "keywords": [
    "software"
  ]
}' |
apify call tinyrex/us-uk-tenders-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,tinyrex/us-uk-tenders-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Kjf7gW3ddvdVsPdcR/builds/851Zt1UAIPZX2MoxB/openapi.json