FAQ · données, schéma, qualité, fraîcheur

1. Périmètre et sources

TenderAPI agrège deux sources officielles de marchés publics :

• BOAMP : Bulletin Officiel des Annonces des Marchés Publics, géré par la DILA. Couverture France.
• TED : Tenders Electronic Daily, supplément électronique au Journal officiel de l'Union européenne. Couverture UE.

Couverture temporelle

• BOAMP : depuis mars 2015, continu.
• TED legacy (format XML) : de janvier 2015 à fin 2023, pays FR, DE, IT, ES, UK.
• TED eForms : depuis fin 2023 (format généralisé début 2024), mêmes pays FR, DE, IT, ES, UK, rafraîchi quotidiennement.

Volumétrie actuelle

2,9 M+ tenders (avis publiés) et 1,95 M+ awards (résultats d'attribution) à date.

Avis de préinformation (PIN)

Les avis de préinformation TED annoncent un marché à venir : on ne peut pas encore y soumissionner et ils n'ont pas de date limite. Ils sont donc exclus de /tenders par défaut. Pour les inclure (veille amont des marchés à venir), ajoutez include_planning=true.

2. Modèle de données

L'API expose deux ressources principales :

• tenders : les avis publiés (appels d'offres ouverts ou clôturés).
• awards : les résultats d'attribution (qui a gagné, pour combien, quand).

Conventions

• Codes pays : country suit la norme ISO 3166-1 alpha-2 (FR, DE, IT, ES, UK…).
• Dates : format ISO 8601 en UTC (ex. 2026-05-21T08:00:00Z).
• CPV : cpv_codes et cpv_family sont des tableaux JSON de codes CPV (Common Procurement Vocabulary).
• Recherche textuelle : descripteur_libelles_folded est une version normalisée (minuscules, sans accents) pour la recherche FTS (Full-Text Search).
• Paramètres de recherche : keyword= est le paramètre canonique (FTS5 multi-tokens AND, accent-insensible). Les alias q= et search= sont acceptés pour convention REST. Pour une recherche OR explicite : keyword=BIM OR "maquette numerique". Listes virgule/pipe non parsées comme OR : utilisez le mot-clé OR.
• Pays supportés : EU 27 + UK/GB + EEA (IS/NO/LI) + CH. Tout autre code retourne 422. GB est aliasé vers UK (convention TED legacy).

Recherche par mot-clé multilingue

Le filtre keyword (alias q) recherche dans le titre et la description, dans la langue de publication de l'avis (TED est multilingue). Un terme en français ne remonte pas les avis allemands, espagnols ou italiens : cherchez le concept dans chaque langue cible et combinez avec OR, par exemple keyword=bathymétrie OR Bathymetrie OR batimetría.

Champ awarded_at_source

Pour chaque award, ce champ indique d'où vient la date d'attribution. C'est utile pour interpréter la précision de awarded_at :

• eForms : date exacte de décision (notices TED au format eForms, depuis fin 2023).
• ted_legacy_decision : date de conclusion du contrat extraite du XML legacy.
• ted_legacy_publication : utilisé en repli quand la date de décision est absente ou aberrante côté source : on prend alors la date de publication de la notice.
• boamp_pub_legacy et variantes : dates issues de la chaîne BOAMP.

3. Qualité et complétude des champs

Les taux ci-dessous indiquent la proportion de lignes où le champ est renseigné, mesurée sur la totalité du corpus actuel. Ils dépendent essentiellement du format imposé par la source à l'autorité contractante au moment de la publication.

Pourquoi ces écarts ?

• budget_max = 0% sur BOAMP : le format BOAMP n'expose pas de champ budget structuré. Le montant n'est connu qu'à l'attribution (champ amount dans /awards).
• buyer_siret et winner_siret faibles en TED legacy (~14-16%) : le format XML legacy (jusqu'à fin 2023) publié par TED n'exige pas l'identifiant SIRET français. Ce champ devient quasi systématique avec le format eForms (~95%).
• cpv_codes = 62% sur BOAMP : une partie des avis BOAMP anciens publient des descripteurs textuels sans code CPV machine-lisible. Pour ces lignes, descripteur_libelles reste exploitable via la recherche FTS.
• budget_max faible sur eForms (6%) : le format eForms rend le champ optionnel et la majorité des autorités contractantes ne le renseignent pas. Le montant final reste disponible côté /awards.
• department sur TED : la déduction du département français s'appuie d'abord sur le code NUTS3 fourni par la notice, complétée par un mapping buyer_siret → INSEE commune → département (via SIRENE). Le résidu (~5-9%) correspond aux avis sans NUTS3 ni SIRET acheteur exploitable.

Ces taux reflètent ce que les sources officielles publient effectivement, et constituent une limite intrinsèque à ces sources, pas de notre traitement. Pour les lignes où un champ est null, c'est qu'il était absent ou non parsable dans la donnée source.

4. Mises à jour et fraîcheur

L'ingestion des nouvelles publications est entièrement automatisée :

• BOAMP : deux passages par jour, le matin et en fin de journée.
• TED : un passage par jour, en début de matinée.

La latence typique entre la publication officielle d'un avis et sa disponibilité dans l'API est inférieure à 24 heures.

Bascule automatique des avis clôturés

Chaque jour, les tenders dont la date limite de remise des offres est dépassée basculent automatiquement de status="open" à status="closed". Certains avis n'ont pas de date limite renseignée (accords-cadres permanents, procédures négociées, anciens MAPA) et restent en open par défaut. Pour les exclure, ajoutez deadline_after=now. À l'inverse, un filtre deadline_after/deadline_before écarte par défaut les avis sans date limite : ajoutez include_null_deadline=true pour les conserver dans vos résultats.