# UK Contract Awards (Contracts Finder) & Supplier Analytics (`zhucl1006/uk-contracts-finder-awards`) Actor

Search UK public sector contract awards from the official Contracts Finder API by keyword, buyer, supplier, CPV code, region, date and value. Clean award records with Companies House numbers, plus buyer/supplier spend rankings.

- **URL**: https://apify.com/zhucl1006/uk-contracts-finder-awards.md
- **Developed by:** [leo zhu](https://apify.com/zhucl1006) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.01 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## UK Contract Awards (Contracts Finder) & Supplier Analytics

Search **UK public sector contract awards** published on the official **Contracts Finder** service (Cabinet Office) and get clean, de-duplicated award records - or a ready-made **spend ranking** of buyers, suppliers, CPV categories, regions or fiscal years.

Built for bid teams, B2B sales, market researchers and journalists who want to know **who is buying what, from whom, and for how much** - without scraping web pages or wrestling with raw OCDS JSON.

**Keywords:** UK government contracts, UK public procurement data, Contracts Finder API, contract award notices, UK tenders won, public sector spend analysis, government supplier list, competitor contract wins, Companies House number, CPV codes, NHS contracts, council contracts, OCDS.

### Use cases

- **Bid / capture teams**: see which buyers awarded contracts in your CPV codes, at what values and via which frameworks, before the next tender comes out.
- **B2B sales & lead generation**: build lists of public bodies that just bought IT, cleaning, construction or consultancy services - and the suppliers that won (with Companies House numbers where published).
- **Competitor intelligence**: track every award won by a competitor (`suppliers: ["Capita"]`) and rank their biggest buyers.
- **Market sizing & research**: spend by CPV division, region or UK fiscal year in one run (3 years of awards in under a minute).
- **Journalism & transparency**: largest awards, direct awards and framework call-offs by department or council.

### What you get

**Award records** (one row per award):

| Field | Example |
|---|---|
| `awardDate`, `publishedDate` | 2026-09-04, 2026-09-07 |
| `buyerName`, `buyerLocality`, `buyerPostalCode` | NHS PROPERTY SERVICES LIMITED, Stockport, SK4 1BS |
| `supplierName`, `suppliers[]` (name, **Companies House number**, SME/VCSE flags) | RSK Environment Limited, SC115530, SME |
| `awardedAmount`, `tenderValue`, `currency` | 35000.76, 35000.76, GBP |
| `title`, `description` | Contract title and description (up to 4,000 characters) |
| `cpvCode`, `cpvDescription`, `cpvDivision`, `additionalCpvCodes` | 71530000 Construction consultancy services |
| `procurementMethodDetails`, `mainProcurementCategory` | Call-off from a framework agreement, services |
| `contractStartDate`, `contractEndDate`, `region` | 2026-07-23, 2028-07-23, South East |
| `suitableForSme`, `suitableForVcse` | true / false |
| `noticeUrl`, `ocid`, `noticeId` | Link to the official notice |
| `fiscalYear` | UK fiscal year (FY2026 = 1 Apr 2026 - 31 Mar 2027) |

**Spend summary rows** (`outputMode` = `summary` or `both`), grouped by supplier, buyer, buyer + supplier, fiscal year, CPV division or region: total awarded GBP, number of awards, distinct buyers/suppliers, average/median/max award, share of total, first/last award date and the top 5 counterparties.

### How to use

1. Pick a **publication date range** (default: last 30 days; up to about 3 years per run). Ranges of 45 days or more are served from the monthly yearly bulk files of the Open Contracting Partnership Data Registry (a 3-year scan takes under a minute) and the latest days are topped up from the live API.
2. Optionally filter by **keywords**, **buyers**, **suppliers**, **CPV code prefixes** (e.g. `72` for IT services, `45` for construction), **regions**, **award date**, **minimum/maximum value** or **SME-suitable** notices.
3. Choose **Award records**, **Spend summary** or **Both**.

Example input - top IT buyers in the first half of September 2026:

```json
{
  "publishedFrom": "2026-09-01",
  "publishedTo": "2026-09-14",
  "cpvCodes": ["72", "48"],
  "outputMode": "both",
  "summaryBy": "buyer",
  "summaryTopN": 10,
  "maxItems": 50,
  "sortBy": "amountDesc"
}
```

### Output example

Award record (abbreviated, real data):

```json
{
  "recordType": "award",
  "awardDate": "2026-08-27",
  "publishedDate": "2026-09-10",
  "buyerName": "FCA",
  "supplierName": "SOPRA STERIA LIMITED - FCA",
  "awardedAmount": 33355903.88,
  "currency": "GBP",
  "title": "DSF for Case & Regulatory Risk Management",
  "cpvCode": "72261000",
  "cpvDescription": "Software support services",
  "region": "London",
  "procurementMethodDetails": "Call-off from a framework agreement",
  "contractStartDate": "2026-09-01",
  "contractEndDate": "2029-08-31",
  "fiscalYear": 2026,
  "noticeUrl": "https://www.contractsfinder.service.gov.uk/Notice/09a98704-9d6d-48d9-bd34-69e2badea208"
}
```

Summary row (`summaryBy: "buyer"`, FY2025):

```json
{
  "recordType": "summary",
  "groupBy": "buyer",
  "groupKey": "Crown Commercial Service",
  "rank": 2,
  "totalAwarded": 61414369264.51,
  "awardCount": 195,
  "medianAward": 500000.0,
  "shareOfTotalPct": 17.97,
  "topCounterparties": [{"name": "PHOENIX SOFTWARE LIMITED", "totalAwarded": 2220320000.0, "awardCount": 2}]
}
```

More example inputs:

```json
{"publishedFrom": "2026-01-01", "suppliers": ["Serco"], "outputMode": "both", "summaryBy": "buyer"}
```

```json
{"publishedFrom": "2025-04-01", "publishedTo": "2026-03-31", "cpvCodes": ["72"], "outputMode": "summary", "summaryBy": "supplier", "summaryTopN": 100}
```

```json
{"publishedFrom": "2026-09-01", "buyers": ["Council"], "keywords": ["cleaning"], "smeSuitableOnly": true}
```

### Pricing (pay per event)

- Run start: small fixed fee per run
- **Award record**: per award row returned
- **Summary row**: per ranking row returned

Example: 50 award records + 10 summary rows = 0.005 + 50 x 0.002 + 10 x 0.01 = about **USD 0.21**. A top-100 supplier ranking over a whole year = about **USD 1.01**. You only pay for rows you receive. Set a maximum cost per run in Apify and the Actor stops cleanly when it is reached. See the Pricing tab for current prices.

### Good to know

- **Source and coverage**: Contracts Finder lists UK public sector contracts, mainly in England and mostly below the high-value thresholds; since the Procurement Act 2023 took effect (Feb 2025) many high-value notices are published on Find a Tender instead. Scotland, Wales and Northern Ireland have their own portals. This Actor covers Contracts Finder award notices only.
- **Values are as published by buyers**. Framework agreements and dynamic purchasing systems are often published with a total ceiling value that may never be spent, so a few awards can dominate totals - use `maxAmount` or look at the median if you need typical contract sizes.
- Negative award values (data-entry errors in the source) are ignored and explained in `valueNote`; placeholder supplier names such as "Not applicable" or "see attached supplier list" are not treated as suppliers.
- **Joint awards**: when one award lists several suppliers, the supplier summary splits the value equally between them (`jointAwardCount` shows how many awards were shared), so totals are not double counted.
- **Updates**: if a notice was corrected (`awardUpdate`), only the latest version is returned.
- **Speed**: the live API returns 100 notices per request and enforces a rate limit (the Actor waits when asked), so short ranges take seconds to a few minutes. Long ranges use the bulk files and take seconds to about a minute.
- The date range filters on the **notice publication date**; use `awardDateFrom`/`awardDateTo` to additionally filter on the award date.
- **Companies House numbers** are included when the buyer published them (about one third of suppliers in a 1-week sample of September 2026); delivery region was stated on about half of awards.
- No personal contact details (names, emails, phone numbers) are exported.

### FAQ

**Is this the official Contracts Finder API?** It uses the official Contracts Finder OCDS API and the Open Contracting Partnership's monthly bulk copy of the same data, and returns it as flat, filterable rows.

**Does it include open tenders / opportunities?** No - this Actor covers **awarded contracts**. Use the award history to find buyers that are likely to re-tender.

**Can I export to Excel, CSV or Google Sheets?** Yes - use the Apify dataset export (CSV, Excel, JSON) or the API, or schedule the Actor weekly and push results to Google Sheets, Slack or a webhook via Apify integrations.

**How fresh is the data?** Short ranges come live from the Contracts Finder API. Long ranges use the monthly bulk files and are topped up from the live API for the most recent days.

**Why are some totals huge?** Framework agreements are often published with a ceiling value for all suppliers. Use `maxAmount`, the median, or `summaryBy: "supplier"` with care.

### Data licence and attribution

Contains public sector information licensed under the [Open Government Licence v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/). Source: [Contracts Finder](https://www.contractsfinder.service.gov.uk/), Cabinet Office. Every record carries `source` and `licence` fields; if you republish the data, keep that attribution. This Actor is not affiliated with or endorsed by the UK Government.

# Actor input Schema

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

Earliest notice publication date (YYYY-MM-DD). Default: 30 days ago. Max range per run: about 3 years.

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

Latest notice publication date (YYYY-MM-DD, inclusive). Default: today.

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

Words or phrases to find in the notice title or description (case-insensitive). Leave empty for all awards.

## `keywordMatch` (type: `string`):

Match ANY keyword or ALL keywords.

## `buyers` (type: `array`):

Partial, case-insensitive buyer names, e.g. 'NHS', 'Ministry of Defence', 'Council'.

## `suppliers` (type: `array`):

Partial, case-insensitive supplier names, e.g. 'Capita', 'Serco'.

## `cpvCodes` (type: `array`):

CPV code prefixes matched against main and additional CPV codes, e.g. '72' (IT services), '45' (construction), '79341'.

## `regions` (type: `array`):

Partial region names, e.g. 'London', 'Scotland', 'North West'. Many notices do not state a region.

## `awardDateFrom` (type: `string`):

Optional extra filter on the award (contract signature) date.

## `awardDateTo` (type: `string`):

Optional extra filter on the award date.

## `minAmount` (type: `integer`):

Only awards with a stated value at or above this.

## `maxAmount` (type: `integer`):

Only awards with a stated value at or below this.

## `smeSuitableOnly` (type: `boolean`):

Keep only opportunities the buyer marked as suitable for small and medium enterprises.

## `maxItems` (type: `integer`):

Maximum number of award records to output (0 = no limit). Summary rows are not counted.

## `sortBy` (type: `string`):

Order of award records in the output.

## `outputMode` (type: `string`):

Award records, an aggregated spend ranking, or both.

## `summaryBy` (type: `string`):

Grouping for the spend summary: total awarded GBP, award count, average/median/max, share of total, first/last award date and top counterparties. Joint awards are split equally between suppliers.

## `summaryTopN` (type: `integer`):

How many summary rows to output, ranked by total awarded value (0 = all).

## `dataSource` (type: `string`):

Auto: ranges shorter than 45 days use the live Contracts Finder API; longer ranges read the monthly-refreshed yearly bulk files from the Open Contracting Partnership Data Registry (much faster) and top up the most recent days from the live API. 'Bulk only' skips the live API (data may be up to ~5 weeks old).

## Actor input object example

```json
{
  "publishedFrom": "2026-09-01",
  "keywords": [
    "software"
  ],
  "keywordMatch": "any",
  "smeSuitableOnly": false,
  "maxItems": 100,
  "sortBy": "awardDateDesc",
  "outputMode": "records",
  "summaryBy": "supplier",
  "summaryTopN": 50,
  "dataSource": "auto"
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `runSummary` (type: `string`):

No description

# 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 = {
    "publishedFrom": "2026-09-01",
    "keywords": [
        "software"
    ],
    "maxItems": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("zhucl1006/uk-contracts-finder-awards").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 = {
    "publishedFrom": "2026-09-01",
    "keywords": ["software"],
    "maxItems": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("zhucl1006/uk-contracts-finder-awards").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 '{
  "publishedFrom": "2026-09-01",
  "keywords": [
    "software"
  ],
  "maxItems": 100
}' |
apify call zhucl1006/uk-contracts-finder-awards --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,zhucl1006/uk-contracts-finder-awards"
        }
    }
}
```

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/nXDHCXwbQ8mY1eZWB/builds/TSchprYqKTnwbau5P/openapi.json