# TenderAPI

> Unified REST API for French (BOAMP) and EU (TED) public procurement data. Search over a decade of tender notices (since 2015), track award outcomes, and identify winning companies by sector, region, budget, or CPV code.

TenderAPI normalizes BOAMP (Bulletin Officiel des Annonces des Marchés Publics, DILA) and TED (Tenders Electronic Daily, EU Publications Office) into a single stable JSON schema with typed filters and pagination. Source data is public: Licence Ouverte Etalab 2.0 (BOAMP) and EU open reuse terms (TED). Commercial use is permitted under those licenses.

## Docs

- [API guide](https://tenderapi.fr/guide): Human-readable guide: copy-pastable curl examples per use case (daily monitoring cron, keyword search, awards by SIREN/SIRET, winner intelligence, alerts, common errors).
- [OpenAPI specification](https://tenderapi.fr/openapi.json): Machine-readable spec: use this to auto-generate clients or tools.
- [Swagger UI](https://tenderapi.fr/docs): Interactive browser documentation.
- [API BOAMP (dedicated page)](https://tenderapi.fr/boamp-api): BOAMP-specific usage, filters, examples.
- [Homepage](https://tenderapi.fr/): Overview, features, pricing.

## Endpoints

- `GET /tenders`: Search tenders. Filters: `keyword` (full-text, alias `q`), `cpv`, `cpv_family`, `descripteur`, `region`, `department`, `country`, `source` (boamp|ted), `status`, `contract_type`, `procedure_type`, `buyer_siret`, `buyer_keyword`, `budget_min`, `budget_max`, `include_null_budget`, `deadline_after`, `deadline_before`, `include_null_deadline`, `published_after`, `published_before`, `include_planning`, `sort` (date|relevance), `page`, `page_size`. Available on all tiers. Prior-information notices (PINs) are excluded by default; pass `include_planning=true` to include them. A `deadline_after`/`deadline_before` filter drops notices with no submission deadline unless `include_null_deadline=true`.
- `GET /awards`: Search award notices (who won contracts). Filters: `cpv`, `region`, `winner_name`, `winner_siret` (14-digit establishment), `winner_siren` (9-digit company — matches all establishments), `awarded_after`, `amount_min`, `source`, `sort` (date|relevance), pagination. Starter tier and above.
- `GET /awards/winner-intel`: Aggregated winner statistics by CPV/region/year, e.g. "who wins IT contracts in Occitanie in 2025". Accepts `winner_siret` or `winner_siren` to focus on one establishment or a whole company. Pro tier only.
- `POST /profiles`: Register an alert profile (daily email digest, Teams card, or webhook) for new tenders matching your criteria. Starter tier and above.
- `GET /me`: Returns the authenticated key's tier, quota remaining, and available features.
- `POST /keys`: Self-serve free API key creation (100 req/day).

## Keyword search syntax (FTS5)

`keyword` / `q` parameters use SQLite FTS5 with accent-insensitive, multi-token AND matching and prefix support.

- Single token: `keyword=hydrographie` matches notices containing that word (any stem).
- AND of tokens (default): `keyword=bathymetrie sonar coastal`: all three must appear.
- OR: explicit FTS5 OR operator. Example: `keyword=BIM OR "maquette numerique" OR IFC OR "jumeau numerique"`.
- Quoted phrase: `keyword="maquette numerique"` matches the exact phrase.
- NOT supported as OR separators: comma `,`, pipe `|`, semicolon `;`. They are treated as literal characters and will silently narrow results.
- Template literals must be interpolated client-side. Strings like `keyword=join(BIM, IFC; " OR ")` or `keyword={{ var }}` are passed verbatim and won't match anything useful; a non-blocking `warning` field is returned in the response when this pattern is detected.
- Country codes use ISO 3166-1 alpha-2 (2 letters): `country=FR`, `country=BE`, `country=DE`. 3-letter codes like `FRA` return 422.
- Regions accept canonical slugs (`ile-de-france`, `paca`, `bretagne`…), pre-2016 region names (`rhone-alpes`, `aquitaine`…) and INSEE region codes (`11` = Île-de-France, `76` = Occitanie, `84` = Auvergne-Rhône-Alpes…).

## Relevance ranking (sort=relevance)

Default result order is chronological (`published_at` DESC on /tenders, `awarded_at` DESC on /awards). Pass `sort=relevance` (requires `keyword=`) to rank by BM25 best-match instead:

- /tenders: title matches outweigh description matches 5:1.
- /awards: winner-name matches rank highest, then buyer name, then descripteur — ideal when searching by company name.
- Each result then carries a `relevance_score` (higher = better match; scores are only comparable within a single query, `null` when sort=relevance is not active).
- `sort=relevance` without `keyword=` returns 422. `sort=date` is accepted as the explicit form of the default.
- Prefer `sort=relevance` when the goal is "most pertinent notices for a topic"; keep the default when the goal is "latest notices".

## Authentication

All endpoints require the `X-API-Key` header. Rate limits per tier:

- Free: 100 req/day, page_size max 20, tenders only
- Starter (5€/mo HT): 500 req/day, page_size max 50, up to 3 alert profiles (email digest, Teams or webhook), adds awards
- Pro (15€/mo HT): 1 500 req/day, page_size max 50, up to 10 alert profiles (email digest, Teams or webhook), adds winner intelligence

Get a free key at <https://tenderapi.fr/>.

## Data freshness

- BOAMP: refreshed 2×/day from the official DILA open-data feed.
- TED: refreshed daily from the EU Publications Office.
- Historical coverage since 2015: BOAMP from March 2015; TED for FR/DE/IT/ES/UK since 2015 (legacy XML format until end 2023, then eForms), refreshed to current. ~2.9M tender notices + ~1.95M awards total.

## Optional

- [Dashboard](https://tenderapi.fr/dashboard): User-facing quota and billing management.
- [Terms of service](https://tenderapi.fr/cgv)
- [Privacy policy](https://tenderapi.fr/privacy)
- [Legal notices](https://tenderapi.fr/mentions-legales)

## Contact

contact@tenderapi.fr