# EU Procurement Notice Finder by CPV & Country (`vexaloom-labs/eu-procurement-notice-finder-by-cpv-and-country`) Actor

Search EU TED procurement notices by CPV category, buyer country, publication date, and keyword, or fetch specific notices by publication number, with buyer, deadline, and contract value per notice.

- **URL**: https://apify.com/vexaloom-labs/eu-procurement-notice-finder-by-cpv-and-country.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (community)
- **Categories:** Automation, Lead generation, Other
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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

## EU Procurement Notice Finder by CPV & Country

TED (Tenders Electronic Daily) is the EU's official journal for public procurement. It publishes contract notices, award results, prior information notices and modifications from thousands of public buyers across Europe. This actor queries TED's open Search API directly and returns clean notice records — no account, API key, cookie, or proxy is needed.

### What this actor does

- Searches notices by CPV category (one of 45 divisions) and optional exact/partial CPV codes, buyer country, publication-date range, tender-deadline range, contract-value range, notice type, procedure type, contract nature, buyer name and full-text keyword.
- Fetches specific notices by publication number — one, several, or a pasted TED URL.
- Scopes a search to notices still open for submission (`ACTIVE`), the latest version of each notice (`LATEST`), or the complete archive (`ALL`).
- Sorts results newest first, oldest first, by soonest submission deadline, or by highest contract value.
- Pages through results with a stable server cursor, up to 10,000 notices per run, with no duplicates.
- Returns buyer identity and contact details, CPV codes, dates, deadlines, contract and award values, winning suppliers with their identifiers, and links to the HTML, XML and PDF versions of every notice.
- Leaves a field out of a record when TED does not publish it for that notice, instead of sending an empty value.

### Output per notice

| Field | Description |
|---|---|
| `publicationNumber` | TED publication number, e.g. `463590-2022` |
| `title` | Notice title |
| `buyerName`, `buyerIdentifier`, `buyerLegalType` | Contracting authority name, registration identifier and legal form code |
| `buyerCountry`, `buyerCountryName`, `buyerCity` | Buyer country and city |
| `buyerEmail`, `buyerContactPoint`, `buyerWebsite` | Buyer contact details when published |
| `placeOfPerformance` | NUTS and country codes where the contract is performed |
| `cpvCodes`, `cpvMain` | All CPV classification codes on the notice, and the primary one |
| `noticeType`, `noticeSubtype`, `noticeVersion`, `formType` | Notice classification and version |
| `procedureType`, `contractNature` | Procedure and nature (works, supplies, services) |
| `publicationDate`, `ojsNumber` | Publication date and Official Journal issue |
| `deadline` | Earliest tender submission deadline, when published |
| `value`, `valueCurrency` | Total contract value and its currency, when published |
| `estimatedValue`, `estimatedValueCurrency`, `estimatedValueLots` | Estimated value for the procedure and per lot |
| `awardValue`, `awardValueCurrency` | Awarded value on award notices |
| `winnerName`, `winnerNames`, `winnerIdentifiers`, `winnerCountries`, `winnerEmails` | Winning supplier(s), with identifiers, countries and contact emails |
| `winnerSizes`, `winnerSelectionStatuses` | Winner size class and selection status codes |
| `contractConclusionDate`, `winnerDecisionDate` | Contract signature and award decision dates |
| `contractTitle` | Contract or lot title when published |
| `durationValue`, `durationUnit` | Contract duration and unit |
| `frameworkAgreement`, `subcontracting` | Framework-agreement and subcontracting codes |
| `htmlUrl`, `xmlUrl`, `pdfUrl`, `sourceUrl` | Official notice formats and canonical page |
| `recordType` | Always `notice` |
| `scrapedAt` | UTC timestamp of the scrape |

### Output when a request fails

If TED rejects a query, a request fails after retries, or `getNotice` is called without a valid publication number, the actor pushes an error record instead of silently returning nothing:

| Field | Description |
|---|---|
| `recordType` | Always `error` |
| `error` | Short code, e.g. `query_error`, `request_failed`, `missing_input` |
| `message` | Human-readable explanation |
| `input` | The query or input value that triggered the error, when applicable |
| `sourceUrl` | The TED endpoint that was called |
| `scrapedAt` | UTC timestamp of the scrape |

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `search` | `search` (filter-based) or `getNotice` (by publication number). |
| `cpvCategory` | string | – (any) | CPV top-level division, e.g. `45` for construction, `72` for IT services. Matches the division and all its sub-codes. |
| `cpvCode` | string | – | One or more CPV codes, separated by commas or spaces, e.g. `45233140, 48000000`. Each matches the code and its sub-codes. |
| `noticeType` | string | – (any) | Contract notice, contract award notice, prior information notice, modification, and the other TED notice types. |
| `procedureType` | string | – (any) | Open, restricted, competitive dialogue, negotiated, innovation partnership, and other procedure types. |
| `contractNature` | string | – (any) | `works`, `supplies`, or `services`. |
| `country` | string | – (all) | Buyer country as an ISO-3166 alpha-3 code (alpha-2 is also accepted). |
| `keyword` | string | – | Full-text keyword matched anywhere in the notice. |
| `buyerName` | string | – | Text that must appear in the contracting authority name. |
| `publicationDateFrom`, `publicationDateTo` | string | – | Publication-date range, `YYYY-MM-DD`. |
| `deadlineFrom`, `deadlineTo` | string | – | Tender submission deadline range, `YYYY-MM-DD`. |
| `minValue`, `maxValue` | integer | – | Total contract-value range, in the notice's own currency. |
| `scope` | string | `ACTIVE` | `ACTIVE` (open for submission), `LATEST` (latest version of each notice), or `ALL` (full archive). |
| `sortBy` | string | `newest` | `newest`, `oldest`, `deadlineSoonest`, or `valueHighest`. |
| `publicationNumber` | string | – | One or more TED publication numbers or notice URLs, used in `getNotice` mode. |
| `maxItems` | integer | `50` | Maximum notice records to return, 1–10,000. |

#### Example: open German construction tenders above EUR 1 million

```json
{
  "mode": "search",
  "cpvCategory": "45",
  "country": "DEU",
  "noticeType": "cn-standard",
  "procedureType": "open",
  "contractNature": "works",
  "minValue": 1000000,
  "scope": "ACTIVE",
  "sortBy": "deadlineSoonest",
  "maxItems": 50
}
```

#### Example: recent IT awards, highest value first

```json
{
  "mode": "search",
  "cpvCategory": "72",
  "noticeType": "can-standard",
  "publicationDateFrom": "2026-01-01",
  "sortBy": "valueHighest",
  "maxItems": 100
}
```

#### Example: notices for one buyer in a date window

```json
{
  "mode": "search",
  "buyerName": "comune di milano",
  "publicationDateFrom": "2026-01-01",
  "publicationDateTo": "2026-03-31",
  "maxItems": 200
}
```

#### Example: fetch specific notices

```json
{
  "mode": "getNotice",
  "publicationNumber": "463590-2022, 4-2026"
}
```

### Use cases

- **Bid discovery** — find open tenders in your sector and country before the submission deadline.
- **Market intelligence** — track which buyers are procuring what, where, and at what value.
- **Competitor monitoring** — watch award notices, winners and contract values by CPV category.
- **Procurement research** — build datasets of public spending across Europe by category and time period.
- **Lead generation** — surface contracting authorities active in a specific sector, with contact details.

### FAQ

**Do I need an account, API key, or proxy?**
No. TED's published-notice Search API is anonymous and cookieless, and the actor calls it directly.

**What is a CPV code?**
CPV (Common Procurement Vocabulary) is the EU's classification for public contracts. `cpvCategory` matches one top-level division and all of its sub-codes; `cpvCode` adds specific codes and matches them hierarchically (a code also returns its sub-codes). When both are set, a notice matching either is returned.

**Which countries are covered?**
EU member states, EEA/EFTA countries (Iceland, Liechtenstein, Norway, Switzerland), the United Kingdom, and other European countries that publish on TED.

**What do the three scopes mean?**
`ACTIVE` returns notices still open for submission. `LATEST` returns the newest version of each matching notice. `ALL` returns every notice and every version in the archive, including amendments.

**What is the difference between `value`, `estimatedValue` and `awardValue`?**
`value` is the notice's total contract value. `estimatedValue` is the buyer's estimate for the procedure or lots. `awardValue` is the value actually awarded on an award notice. Not every notice publishes all three.

**Why are some fields missing from a notice?**
TED only publishes them for certain notice types. For example, winner and award fields exist on award notices, while deadlines exist on notices that invite tenders. Missing values are omitted, never sent as `null`.

**Why is `buyerEmail` or `buyerContactPoint` missing?**
Contact details are optional in eForms and many buyers omit them. The actor returns them whenever TED publishes them, but never invents them. Phone numbers are not exposed by the Search API at all.

**How many notices can one run return?**
Up to `maxItems`, capped at 10,000. The actor uses TED's stable iteration cursor, so it does not duplicate rows or hit the 15,000-row page-number window.

**How fresh is the data?**
Each run queries TED live, so results reflect what is published when the run starts.

**What happens if my query is invalid or a request fails?**
The actor retries transient failures with backoff and pushes a single descriptive error record (`recordType: "error"`) rather than failing silently.

**Is this affiliated with TED or the EU?**
No. This actor reads TED's public data and is not affiliated with, endorsed by, or connected to the Publications Office of the European Union.

### Limitations

- Winner and award fields are only present on award notices; tender notices have no winners yet.
- Contract values are reported in the notice's own currency, not converted to EUR.
- Buyer phone numbers are not part of TED's Search API response.
- Sorting is available for publication date, submission deadline and total value; TED does not expose a relevance score through this API.
- A single run is capped at 10,000 notices. For larger exports, partition by publication date, country or CPV division.
- Contract descriptions are not included to keep records compact; every notice links to its official HTML, XML and PDF versions.

# Actor input Schema

## `mode` (type: `string`):

What to scrape: `search` builds a query from filters; `getNotice` fetches a notice by its publication number.

## `cpvCategory` (type: `string`):

Common Procurement Vocabulary top-level division. Matches the whole division and all its sub-codes. Used in `search` mode.

## `cpvCode` (type: `string`):

Optional exact or partial CPV code(s) (e.g. `45233140`, `48000000`). Separate several codes with commas or spaces; each matches the code and its sub-codes. Combined with CPV Category. Used in `search` mode.

## `noticeType` (type: `string`):

Restrict to one TED notice type, e.g. contract notices or contract award notices. Used in `search` mode.

## `procedureType` (type: `string`):

Restrict to a procurement procedure, e.g. open or restricted. Used in `search` mode.

## `contractNature` (type: `string`):

Restrict to works, supplies, or services. Used in `search` mode.

## `country` (type: `string`):

Filter by the buyer's country (ISO-3166 alpha-3, TED style). Used in `search` mode.

## `keyword` (type: `string`):

Full-text keyword to match anywhere in the notice (title, description, buyer, ...). Used in `search` mode.

## `buyerName` (type: `string`):

Match notices whose contracting authority name contains this text, e.g. `comune di milano`. Used in `search` mode.

## `publicationDateFrom` (type: `string`):

Only notices published on or after this date (YYYY-MM-DD). Used in `search` mode.

## `publicationDateTo` (type: `string`):

Only notices published on or before this date (YYYY-MM-DD). Used in `search` mode.

## `deadlineFrom` (type: `string`):

Only notices with a submission deadline on or after this date (YYYY-MM-DD). Used in `search` mode.

## `deadlineTo` (type: `string`):

Only notices with a submission deadline on or before this date (YYYY-MM-DD). Used in `search` mode.

## `minValue` (type: `integer`):

Only notices whose total contract value is at least this amount, in the notice's own currency. Used in `search` mode.

## `maxValue` (type: `integer`):

Only notices whose total contract value is at most this amount, in the notice's own currency. Used in `search` mode.

## `scope` (type: `string`):

Which notices to include: Active (still open for submission), Latest version of each notice, or All notices and versions. Used in `search` mode.

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

Order of the returned notices. Used in `search` mode.

## `publicationNumber` (type: `string`):

TED publication number(s) to fetch (e.g. `463590-2022`). Accepts several separated by comma/space. Used in `getNotice` mode.

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

Maximum number of notice records to return (1-10,000).

## Actor input object example

```json
{
  "mode": "search",
  "cpvCategory": "45",
  "noticeType": "",
  "procedureType": "",
  "contractNature": "",
  "country": "",
  "scope": "ACTIVE",
  "sortBy": "newest",
  "maxItems": 3
}
```

# Actor output Schema

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

Dataset containing all scraped TED tender notices.

# 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 = {
    "mode": "search",
    "cpvCategory": "45",
    "scope": "ACTIVE",
    "sortBy": "newest",
    "maxItems": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("vexaloom-labs/eu-procurement-notice-finder-by-cpv-and-country").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 = {
    "mode": "search",
    "cpvCategory": "45",
    "scope": "ACTIVE",
    "sortBy": "newest",
    "maxItems": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("vexaloom-labs/eu-procurement-notice-finder-by-cpv-and-country").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 '{
  "mode": "search",
  "cpvCategory": "45",
  "scope": "ACTIVE",
  "sortBy": "newest",
  "maxItems": 3
}' |
apify call vexaloom-labs/eu-procurement-notice-finder-by-cpv-and-country --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/eu-procurement-notice-finder-by-cpv-and-country"
        }
    }
}
```

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/Nec206EHIvMnhKQtx/builds/Pxrx2xoD3ISc1sldg/openapi.json
