consultation-des-donnees-publiques
Interface synchrone (OpenAPI) — version 0.3.0. Producteur : donnees-publiques.
CE QUE LE SERVICE COMMUN SERT : les jeux de données publiques répliqués localement —
le répertoire Sirene de l’Insee et la Base Adresse Nationale —, tels que publiés par
leurs producteurs, sans altération de sens. AUCUNE DONNÉE DE TENANT NE FRANCHIT CE CONTRAT, dans aucun sens : une instance unique
sert tous les tenants, et aucun identifiant de tenant n’est accepté dans les URL, les
en-têtes ou les corps de requête. CHAQUE RÉPONSE PORTE SA PROVENANCE — jeu d’origine, producteur, adresse du concédant,
licence et date de fraîcheur (celle du dernier chargement réussi) : ce sont les
contreparties de la Licence Ouverte 2.0, converties en exigences par la carte
d’identité du service. Ces
données AIDENT AU CONTRÔLE ; elles ne remplacent jamais le domaine propriétaire, et
aucune règle métier — éligibilité, rapprochement, priorité entre sources — n’est
évaluée ici. LES ADRESSES SONT STRUCTURÉES SELON ISO 20022, dans la simplification que le CFONB
recommande pour le périmètre français : huit des quatorze éléments de « Postal
Address », chaque exclusion motivée à la conception du service. Les longueurs
maximales de la norme ne sont pas imposées ici — tronquer une voie publiée pour la
faire entrer serait altérer le jeu ; les respecter appartient au consommateur qui
compose un message ISO. Consommateurs pressentis, non encore écrits : entreprise, epargnant, relation-tiers. Le composant est un OAuth 2.0 Resource Server et valide l’Access Token ; les
permissions indiquées par x-authorization-permission sont évaluées par le PEP
.
La spécification
Section intitulée « La spécification »openapi: 3.1.0info: title: donnees-publiques — la consultation des référentiels publics version: 0.3.0 x-ruptures: [] x-producteurs: [donnees-publiques] x-consommateurs: [] description: | CE QUE LE SERVICE COMMUN SERT : les jeux de données publiques répliqués localement — le répertoire Sirene de l'Insee et la Base Adresse Nationale —, tels que publiés par leurs producteurs, sans altération de sens.
AUCUNE DONNÉE DE TENANT NE FRANCHIT CE CONTRAT, dans aucun sens : une instance unique sert tous les tenants, et aucun identifiant de tenant n'est accepté dans les URL, les en-têtes ou les corps de requête.
CHAQUE RÉPONSE PORTE SA PROVENANCE — jeu d'origine, producteur, adresse du concédant, licence et date de fraîcheur (celle du dernier chargement réussi) : ce sont les contreparties de la Licence Ouverte 2.0, converties en exigences par la carte d'identité du service. Ces données AIDENT AU CONTRÔLE ; elles ne remplacent jamais le domaine propriétaire, et aucune règle métier — éligibilité, rapprochement, priorité entre sources — n'est évaluée ici.
LES ADRESSES SONT STRUCTURÉES SELON ISO 20022, dans la simplification que le CFONB recommande pour le périmètre français : huit des quatorze éléments de « Postal Address », chaque exclusion motivée à la conception du service. Les longueurs maximales de la norme ne sont pas imposées ici — tronquer une voie publiée pour la faire entrer serait altérer le jeu ; les respecter appartient au consommateur qui compose un message ISO.
Consommateurs pressentis, non encore écrits : entreprise, epargnant, relation-tiers. Le composant est un OAuth 2.0 Resource Server et valide l'Access Token ; les permissions indiquées par `x-authorization-permission` sont évaluées par le PEP.servers: - url: https://donnees-publiques.api.example.internal description: Instance unique, partagée par tous les tenants.
tags: - name: Sirene description: Identité des unités légales et des établissements, répertoire Sirene (Insee). - name: Adresses description: Normalisation d'adresses et géocodage, Base Adresse Nationale. - name: Jeux description: Les jeux servis, leur producteur, leur licence et leur fraîcheur.
security: - bearerAuth: []
paths:
/v1/sirene/unites-legales: get: tags: [Sirene] operationId: rechercherUnitesLegales summary: Rechercher une unité légale par sa dénomination. description: >- UNE AIDE AU RAPPROCHEMENT : le service rend des candidats du répertoire, ordonnés par proximité de dénomination. La décision de retenir un candidat, et ce qu'on en retient, appartient au consommateur — aucune règle de rapprochement n'est évaluée ici. x-authorization-permission: donnees-publiques:consulter parameters: - name: q in: query required: true description: Dénomination recherchée, complète ou partielle. schema: { type: string, minLength: 3, maxLength: 200 } - name: etatAdministratif in: query schema: { type: string, enum: [ACTIVE, CESSEE] } - $ref: '#/components/parameters/Curseur' - $ref: '#/components/parameters/Limite' responses: '200': description: La page de candidats, avec sa provenance. content: application/json: schema: type: object required: [provenance, elements, pagination] properties: provenance: { $ref: '#/components/schemas/Provenance' } elements: type: array items: { $ref: '#/components/schemas/UniteLegale' } pagination: { $ref: '#/components/schemas/Pagination' } '401': { $ref: '#/components/responses/NonAuthentifie' } '403': { $ref: '#/components/responses/NonAutorise' } default: { $ref: '#/components/responses/Erreur' }
/v1/sirene/unites-legales/{siren}: get: tags: [Sirene] operationId: consulterUniteLegale summary: Consulter une unité légale par son SIREN. description: >- La fiche telle que publiée par l'Insee, projection du jeu répliqué — jamais un enrichissement ni une correction. x-authorization-permission: donnees-publiques:consulter parameters: - $ref: '#/components/parameters/Siren' responses: '200': description: L'unité légale. content: application/json: schema: type: object required: [provenance, uniteLegale] properties: provenance: { $ref: '#/components/schemas/Provenance' } uniteLegale: { $ref: '#/components/schemas/UniteLegale' } '401': { $ref: '#/components/responses/NonAuthentifie' } '403': { $ref: '#/components/responses/NonAutorise' } '404': { $ref: '#/components/responses/Introuvable' } default: { $ref: '#/components/responses/Erreur' }
/v1/sirene/etablissements/{siret}: get: tags: [Sirene] operationId: consulterEtablissement summary: Consulter un établissement par son SIRET. description: >- La fiche telle que publiée par l'Insee, adresse comprise. Le SIREN porté est celui du jeu ; l'unité légale correspondante se consulte séparément. x-authorization-permission: donnees-publiques:consulter parameters: - $ref: '#/components/parameters/Siret' responses: '200': description: L'établissement. content: application/json: schema: type: object required: [provenance, etablissement] properties: provenance: { $ref: '#/components/schemas/Provenance' } etablissement: { $ref: '#/components/schemas/Etablissement' } '401': { $ref: '#/components/responses/NonAuthentifie' } '403': { $ref: '#/components/responses/NonAutorise' } '404': { $ref: '#/components/responses/Introuvable' } default: { $ref: '#/components/responses/Erreur' }
/v1/adresses: get: tags: [Adresses] operationId: rechercherAdresses summary: Normaliser une adresse en texte libre. description: >- DES CANDIDATS ORDONNÉS PAR SCORE, jamais une décision : le score dit la qualité de l'appariement, il ne choisit pas. Retenir un candidat, et ce qu'on en retient, appartient au consommateur. x-authorization-permission: donnees-publiques:consulter parameters: - name: q in: query required: true description: L'adresse recherchée, en texte libre. schema: { type: string, minLength: 3, maxLength: 300 } - name: codePostal in: query description: Restreint la recherche à un code postal. schema: { type: string, pattern: '^[0-9]{5}$' } - name: codeCommune in: query description: Restreint la recherche à un code commune Insee. schema: { type: string, pattern: '^[0-9AB]{5}$' } - $ref: '#/components/parameters/Limite' responses: '200': description: Les candidats, du meilleur score au moins bon, avec leur provenance. content: application/json: schema: type: object required: [provenance, candidats] properties: provenance: { $ref: '#/components/schemas/Provenance' } candidats: type: array items: { $ref: '#/components/schemas/AdresseCandidate' } '401': { $ref: '#/components/responses/NonAuthentifie' } '403': { $ref: '#/components/responses/NonAutorise' } default: { $ref: '#/components/responses/Erreur' }
/v1/jeux: get: tags: [Jeux] operationId: listerJeux summary: Lister les jeux servis et leur fraîcheur. description: >- LE JEU QU'ON NE RAFRAÎCHIT PLUS SE VOIT ICI, avant de se voir dans les données : la date de fraîcheur est celle du dernier chargement réussi, et elle vieillit dès qu'un chargement échoue. x-authorization-permission: donnees-publiques:consulter responses: '200': description: Les jeux, leur producteur, leur licence, leur dernier chargement. content: application/json: schema: type: object required: [jeux] properties: jeux: type: array items: { $ref: '#/components/schemas/Jeu' } '401': { $ref: '#/components/responses/NonAuthentifie' } '403': { $ref: '#/components/responses/NonAutorise' } default: { $ref: '#/components/responses/Erreur' }
components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Access Token validé par le Resource Server ; la permission est évaluée par le PEP.
parameters: Siren: name: siren in: path required: true description: Identifiant Sirene d'une unité légale, neuf chiffres. schema: { type: string, pattern: '^[0-9]{9}$' } Siret: name: siret in: path required: true description: Identifiant Sirene d'un établissement, quatorze chiffres. schema: { type: string, pattern: '^[0-9]{14}$' } Curseur: name: curseur in: query description: Curseur opaque de la page suivante, servi par la page précédente. schema: { type: string, maxLength: 500 } Limite: name: limite in: query schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
responses: NonAuthentifie: description: Jeton absent, invalide ou expiré. content: application/problem+json: schema: { $ref: '#/components/schemas/Probleme' } NonAutorise: description: Jeton valide, permission refusée par le PEP. content: application/problem+json: schema: { $ref: '#/components/schemas/Probleme' } Introuvable: description: L'identifiant demandé est inconnu du jeu servi, à sa date de fraîcheur. content: application/problem+json: schema: { $ref: '#/components/schemas/Probleme' } Erreur: description: Toute autre erreur, au format problème. content: application/problem+json: schema: { $ref: '#/components/schemas/Probleme' }
schemas: Provenance: type: object description: >- Les contreparties de la Licence Ouverte 2.0, portées par chaque réponse : la source est nommée, l'adresse du concédant est donnée, la date de dernière mise à jour est dite, et la réutilisation n'est ni officielle ni cautionnée par le producteur. required: [jeu, producteur, urlDuConcedant, licence, dateDeFraicheur] properties: jeu: type: string enum: [SIRENE, BAN] producteur: type: string description: >- Le producteur du jeu, tel qu'il se nomme — « Insee » pour Sirene ; pour la BAN, le partenariat qui la produit (Ministère de la Transition écologique, IGN, ANCT). Une mention de source inexacte est un manquement à la licence. urlDuConcedant: type: string format: uri description: >- L'adresse du concédant, que l'attribution due par la Licence Ouverte réclame au même titre que la source et la date de dernière mise à jour. licence: type: string const: "Licence Ouverte 2.0" dateDeFraicheur: type: string format: date-time description: La date du dernier chargement réussi du jeu servi.
UniteLegale: type: object description: >- L'unité légale telle que publiée par l'Insee — les champs servis sont une projection du jeu, jamais un enrichissement. required: [siren, denomination, etatAdministratif] properties: siren: { type: string, pattern: '^[0-9]{9}$' } denomination: type: string description: Dénomination de l'unité légale, ou nom d'usage pour une personne physique. etatAdministratif: { type: string, enum: [ACTIVE, CESSEE] } categorieJuridique: type: string description: Code de la nomenclature Insee des catégories juridiques. dateCreation: { type: string, format: date } siretDuSiege: { type: string, pattern: '^[0-9]{14}$' }
Etablissement: type: object description: L'établissement tel que publié par l'Insee. required: [siret, siren, etatAdministratif, estSiege] properties: siret: { type: string, pattern: '^[0-9]{14}$' } siren: { type: string, pattern: '^[0-9]{9}$' } etatAdministratif: { type: string, enum: [ACTIF, FERME] } estSiege: { type: boolean } denominationUsuelle: { type: string } dateCreation: { type: string, format: date } adresse: { $ref: '#/components/schemas/AdresseStructuree' }
AdresseStructuree: type: object description: >- L'adresse d'un établissement telle que publiée dans Sirene, décomposée selon ISO 20022 (simplification CFONB). Le code commune Insee n'appartient pas à la norme : il est servi à côté, parce qu'il IDENTIFIE la commune là où TownName la nomme seulement. properties: numeroDeVoie: type: string description: 'ISO 20022 BuildingNumber (BldgNb, Max16Text).' nomDeVoie: type: string description: >- ISO 20022 StreetName (StrtNm, Max70Text) — type et libellé de voie réunis, la norme ne les distinguant pas. complement: type: string description: >- ISO 20022 Floor (Flr, Max70Text) — le complément géographique français : entrée, tour, immeuble, résidence. Le CFONB y range le nom d'immeuble, BuildingName étant trop court, et écarte BuildingName. boitePostale: type: string description: 'ISO 20022 PostBox (PstBx, Max16Text) — mentions spéciales de distribution.' codePostal: type: string description: >- ISO 20022 PostCode (PstCd, Max16Text), DANS LE PAYS de l'établissement — le répertoire contient des adresses étrangères, dont le code porte parfois lettres, espaces et tirets. Porte le code CEDEX quand l'établissement en a un. nomDeVille: type: string description: >- ISO 20022 TownName (TwnNm, Max35Text) — la commune de destination, ou le bureau distributeur pour un CEDEX. localite: type: string description: >- ISO 20022 TownLocationName (TwnLctnNm, Max35Text) — la commune d'implantation quand elle diffère du bureau distributeur CEDEX. pays: type: string pattern: '^[A-Z]{2}$' description: >- ISO 20022 Country (Ctry, Code2Text) — code ISO 3166-1 alpha-2. ABSENT pour une adresse étrangère : l'Insee publie un code du COG, dont la correspondance ISO n'est pas acquise, et le service ne l'invente pas. codeCommune: type: string pattern: '^[0-9AB]{5}$' description: 'Code commune Insee — hors ISO 20022, servi pour identifier la commune.' codePaysEtranger: type: string description: >- Le code pays du COG tel que l'Insee le publie, quand l'adresse est étrangère — servi tel quel, en attendant sa correspondance ISO. nomPaysEtranger: type: string
AdresseCandidate: type: object description: Un candidat de la Base Adresse Nationale, avec son score d'appariement. required: [libelle, score, nomDeVille, pays, codeCommune] properties: libelle: type: string description: L'adresse complète normalisée, en une ligne. score: type: number minimum: 0 maximum: 1 description: Qualité de l'appariement — un score, pas une décision. numeroDeVoie: type: string description: 'ISO 20022 BuildingNumber (BldgNb) — numéro et indice de répétition réunis.' nomDeVoie: type: string description: >- ISO 20022 StreetName (StrtNm) — nom de la voie, ou du lieu-dit. ABSENT pour les adresses que le producteur publie sans voie. codePostal: type: string pattern: '^[0-9]{5}$' description: >- ISO 20022 PostCode (PstCd). ABSENT pour les adresses que le producteur publie sans code postal. nomDeVille: type: string description: 'ISO 20022 TownName (TwnNm) — la commune.' pays: type: string pattern: '^[A-Z]{2}$' description: 'ISO 20022 Country (Ctry) — toujours FR : la BAN ne couvre que la France.' codeCommune: type: string pattern: '^[0-9AB]{5}$' description: 'Code commune Insee — hors ISO 20022, servi pour identifier la commune.' position: type: object description: Position géographique, WGS 84. required: [longitude, latitude] properties: longitude: { type: number } latitude: { type: number }
Jeu: type: object description: Un jeu servi par le service, avec sa provenance et sa fraîcheur. required: [jeu, producteur, urlDuConcedant, licence, dateDeFraicheur] properties: jeu: { type: string, enum: [SIRENE, BAN] } producteur: { type: string } urlDuConcedant: { type: string, format: uri } licence: { type: string, const: "Licence Ouverte 2.0" } dateDeFraicheur: type: string format: date-time description: La date du dernier chargement réussi.
Pagination: type: object description: Pagination par curseur opaque ; l'absence de curseurSuivant clôt la liste. properties: curseurSuivant: { type: string, maxLength: 500 }
Probleme: type: object description: Erreur au format « problème » (RFC 9457). required: [title, status] properties: type: { type: string, format: uri-reference } title: { type: string } status: { type: integer } detail: { type: string }