3617 verif ?

Détails
Catégorie : Les API du web
View Comments

Nous allons voir, au cours de ce (long) article, comment récupérer très facilement des données INSEE sur vos entreprises favorites.
ATTENTION : il existe deux sites internet avec des API sur les données INSEE.
Nous parlons bien ici du site api.insee.fr.
Il existe (ou existait) un autre site avec des API aussi quelque peu différentes (d'après ce que j'ai vu) http://api.insee.fr qui ne fonctionne plus à l'heure où j'écris cet article.

Acquérons une clef API

Je ne reviens plus sur le "à quoi cela sert", elle sert à vous authentifier et gérer les restrictions lorsque l'API en possède. Je ne vais pas m'étendre sur le sujet étant donnée qu'une documentation en français sur l'acquisition des clefs API de l'INSEE est mise en ligne et est assez détaillée. (je ne vous cacherai pas que pour comprendre comment acquérir une clef, ... j'ai lu la doc !) Ensuite, lançons-nous dans le grand bain !

Premièrement vérifions la date de la dernière mise à jour de la base INSEE

Si je vous laisse le jetons qui m'a permi de faire mes tests, c'est qu'il ne fonctionne plus. Remplacez le jeton (en bleu) par le vôtre.

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer 1f6c905a-435c-302e-babd-6e2152bfd86f' 'https://api.insee.fr/entreprises/sirene/V3/informations'

Accès au service avec recherche de la totalité des périodes historiques par SIREN

Rappelons poor celles et ceux qui l'ignorent, ce que signififie SIREN : Système Informatique du Répertoire des Entreprises.
L'accès au SIREN s'appelle via l'API de cette forme :
https://api.insee.fr/entreprises/sirene/V3/siren/{siren}

Il est possible de définit un paramètre date
https://api.insee.fr/entreprises/sirene/V3/siren/{siren}?date={date}

Voici les parmètres pouvant être concaténés à l'URL :

  • {siren} est un numéro à 9 chiffres : paramètre obligatoire.
  • {date} est de la forme AAAA-MM-JJ : paramètre facultatif

Accès au service avec le paramètre date qui renvoie uniquement la période comprenant cette date :

On accède à cette données via la requête HTTP https://api.insee.fr/entreprises/sirene/V3/siren/{siren}?date={date}.
Bien évidemment, il faut remplacer les valeurs en bleu par les données réelles.
Les données à paser en paramètre correspondent à :

  • {siren} est un numéro à 9 chiffres : paramètre obligatoire.
  • {date} est de la forme AAAA-MM-JJ : paramètre facultatif
    • Ex. 1 : https://api.insee.fr/entreprises/sirene/V3/siren/005520135
    • Ex. 2 : https://api.insee.fr/entreprises/sirene/V3/siren/005520135?date=2019-01-01

ATTENTION : si aucune activité n'est antérieure à la date donnée, une réponse 404 est retournée car aucun élément n'est trouvé pour le Siren 005520135 passé en paramètre à la date 1950-01-01, par défaut.

URL d’accès au service avec recherche de la totalité des périodes historiques par SIRET

Il est ainsi possible de récupérer un historique des éléments connus pour un SIRET donné, via un appel de cette sorte :
https://api.insee.fr/entreprises/sirene/V3/siret/{siret}

Voici les parmètres pouvant être concaténés à l'URL :

  • {siren} est un numéro à 9 chiffres : paramètre obligatoire.
  • {date} est de la forme AAAA-MM-JJ : paramètre facultatif

Interrogation "unitaire" par Siret

En effet, et c'est le plus interessant à mon avis, quoi de plus syma de connaitre des informations sur UN siret donné ?
Recherchons sur la durée de vie du SIRET donné les informations le concernant : https://api.insee.fr/entreprises/sirene/V3/siret/{siret}
Mais remarquez qu'il est aussi possible de borner la période de recherche, en pasasnt un paramètre date https://api.insee.fr/entreprises/sirene/V3/siret/{siret}?date={date} Voici les parmètres pouvant être concaténés à l'URL :

  • {siret} est un numéro à 14 chiffres : paramètre obligatoire.
  • {date} est de la forme AAAA-MM-JJ : paramètre facultatif


Le retour est structuré en 2 parties :

  • le header (à ne pas confondre avec l'en-tête http ni l'en-tête de réponse) qui contient le code retour et le message d'erreur ;
  • l'établissement, qui comprend :
    • Toutes les variables courantes hors celles de l'adresse
    • La structure unité légale qui comprend toutes les valeurs courantes de l'unité légale,
    • La structure adresse qui comprend toutes les variables de l'adresse,
    • La liste de toutes les périodes et, pour chaque période,
    • La liste des variables historisées.

L'ensemble des éléments retournés est dans la documentation.

Pour aller + loin...

Je ne m'étendrai pas sur ce sujet car cet article n'ap pour but que d'initier les néophyte aux API de l'INSSE, mais sachez que vous pouvez combiner des critères de recherches, afin d'affiner vos rcherches.
L'url de votre recherce multicritere se construit de la sorte (cas de recherche d'un SIREN) : https://api.insee.fr/entreprises/sirene/V3/siren?q={requête multicritère}
L'url de votre recherce multicritere se construit de la sorte (cas de recherche d'un SIRET) : https://api.insee.fr/entreprises/sirene/V3/siret?q={requête multicritère}
S'il y a d'autres paramètres à adjoindre, en plus de la requete multicritères, on peut le faire de la sorte : https://api.insee.fr/entreprises/sirene/V3/siren?q={requête multicritère}&date=
La syntaxe des critères multiples est basé sur le couple nomVariable:valeur. nomVariable doit correspondre exactement (casse comprise) à la variable de sortie de l’interrogation unitaire.
Toutes les variables peuvent être utilisées, y compris les indicatrices, avec quelques subtilités pour les variables au format date et les variables historisées.

EXEMPLES

Aller j'ai testé l'ecriture de mon article avec ces requetes http suivantes :

Recherches monocritères :

  • Récupération des données pour UN siren : https://api.insee.fr/entreprises/sirene/V3/siren/005520135
  • Récupération d'informations pour UN SIREN donné à partir d'une date : https://api.insee.fr/entreprises/sirene/V3/siren/005520135?date=2000-01-01
  • Récupération d'informations pour UN SIREN avec date précédant la première période connue de l'établissement: RETOURNE UN STATUT 404
  • Récupération par SIRET : https://api.insee.fr/entreprises/sirene/V3/siret/39860733300059
  • Récupération par SIRET à partir d'une date : https://api.insee.fr/entreprises/sirene/V3/siret/39860733300059?date=2015-08-01
  • Récupération par SIRET avec date précédant la première période connue de l'établissement: RETOURNE UN STATUT 404

Recherches multicritères

J'ai aussi testé des recherches multicritères :

  • Recherche de tous les établissements du Siren 775672272 : /siret?q=siren:775672272
  • Recherche de toutes les unités purgées : /siren?q=unitePurgeeUniteLegale:true
  • Recherche de tous les établissements des unités purgées : /siret?q=unitePurgeeUniteLegale:true
  • Recherche de tous les établissements de la commune de Malakoff (code commune=92046) : /siret?q=codeCommuneEtablissement:92046

Recherche sur des valeurs historisées

Il est aussi possible d'interroger la "base" sur l'historisation de certaines données :

  • Recherche de toutes les UL dont la dénomination contient ou a contenu le mot GAZ : /siren?q=periode(denominationUniteLegale:GAZ)
  • Recherche de toutes les UL qui ont été cessées : /siren?q=periode(etatAdministratifUniteLegale:C)
  • Recherche de tous les établissements dont le code de l’activité principale a été 33.01 : construction de cellules d’aéronef (code NAP600) : /siret?q=periode(activitePrincipaleEtablissement:33.01)

Recherches par éliminations

  • Recherche de tous les établissements dont l'unité légale est une personne morale : /siret?q=-categorieJuridiqueUniteLegale:1000
  • Recherche de tous les établissements qui n'ont jamais été fermés : /siret?q=-periode(etatAdministratifEtablissement:F)

Recherches en combinant des booléens

  • Recherche de toutes les entreprises dont l’activité principale a été au moins dans une période 84.23Z ou 86.21Z : /siren?q=periode(activitePrincipaleUniteLegale:84.23Z OR activitePrincipaleUniteLegale:86.21Z)
  • Recherche de tous les établissements qui ont au moins une période où l'établissement est à la fois Actif et a une activité principale à 84.23Z : /siret?q=periode(activitePrincipaleEtablissement:84.23Z AND etatAdministratifEtablissement:A)
  • Recherche de tous les établissements qui ont moins une période dont l’activitePrincipaleEtablissement est 84.23Z et qui n'ont jamais été fermés : /siret?q=periode(activitePrincipaleEtablissement:84.23Z) AND -periode(etatAdministratifEtablissement:F)
  • Recherche de tous les établissements sur la commune de Malakoff dont la dernière catégorie juridique de l’unité légale est 9220 (association déclarée): /siret?q=codeCommuneEtablissement:92046 AND categorieJuridiqueUniteLegale:9220

Recherches exactes

La recherche exacte se fait en utilisant les guillemets doubles.
Recherche de toutes les unités légales dont la dénomination contient exactement le terme " LE TIMBRE " : /siren?q=periode(denominationUniteLegale:"LE TIMBRE")

Recherches en utilisant des jokers

  • « * » permet de remplacer une chaîne de caractères de taille quelconque :
    Recherche de tous les établissements des unités légales dont l'activité principale commence par 8 : /siret?q=activitePrincipaleUniteLegale:8*
    Recherche de tous les établissements des unités légales dont le sigle n'est pas rempli : /siret?q=-sigleUniteLegale:*
  • « ? » permet de remplacer exactement un caractère.
    Recherche de tous les établissements dont l'unité légale a un sigle sur 3 positions : /siret?q=sigleUniteLegale:???
    Recherche de tous les établissements dont l'unité légale a un sigle qui commence par FC et est sur 3 positions exactement : /siret?q=sigleUniteLegale:FC?
  • Recherche avec utilisation de différences de Damerau-Levenshtein
    • Recherche de tous les établissements dont l’unité légale a pour sigle PAUL à une erreur près : /siret?q=sigleUniteLegale:PAUL~1
    • Recherche de 20 établissements dont la dénomination comporte "bleu le": /siret?q=denominationUniteLegale:"bleu le"&nombre=20&chmps=denominationUniteLegale
    • Recherche de 20 établissements dont la dénomination comporte "bleu le" AVEC UNE DISTANCE DE Levenshtein de 2 : /siret?q=denominationUniteLegale:"bleu le"~2&nombre=18&champs=denominationUniteLegale
    • Recherches de plages de valeurs
      • La syntaxe est la suivante :
      • nomVariable:[valeur1 TO valeur2] : bornes valeur1 et valeur2 sont incluses
      • nomVariable:{valeur1 TO valeur2} : bornes valeur1 et valeur2 sont excluses

Les symboles { et } doivent être échappés :%7B et%7D

      • Recherche sur des dates
        • Il est possible de faire des recherches sur les variables de type date, y compris les dates de début et de fin de période.
        • Pour les SIREN
          • Recherche de toutes les entreprises dont l’activité principale a été au moins dans une période 84.23Z ou 86.21Z : /siren?q=periode(activitePrincipaleUniteLegale:84.23Z OR activitePrincipaleUniteLegale:86.21Z)
          • Recherche de tous les établissements qui ont au moins une période où l'établissement est à la fois Actif et a une activité principale à 84.23Z : /siret?q=periode(activitePrincipaleEtablissement:84.23Z AND etatAdministratifEtablissement:A)
          • Recherche de tous les établissements qui ont moins une période dont l’activitePrincipaleEtablissement est 84.23Z et qui n'ont jamais été fermés : /siret?q=periode(activitePrincipaleEtablissement:84.23Z) AND -periode(etatAdministratifEtablissement:F)
          • Recherche de tous les établissements sur la commune de Malakoff dont la dernière catégorie juridique de l’unité légale est 9220 (association déclarée) : /siret?q=codeCommuneEtablissement:92046 AND categorieJuridiqueUniteLegale:9220
          • Recherche de toutes les unités légales dont la dénomination contient exactement le terme "LE TIMBRE" : /siren?q=periode(denominationUniteLegale:"LE TIMBRE")

Et toujours l'utilisation de jokers

Avec le joker * :

  • nomVariable:va* => nomVariable doit commencer par "va"
  • nomVariable:*eur => nomVariable doit terminer par eur
  • nomVariable:*ale* => nomVariable doit contenir la chaîne ale
  • nomVariable:* => nomVariable doit contenir au moins une lettre

Exemples :

  • Recherche de tous les établissements des unités légales dont l'activité principale commence par 8 : /siret?q=activitePrincipaleUniteLegale:8*
  • Recherche de tous les établissements des unités légales dont le sigle n'est pas rempli : /siret?q=-sigleUniteLegale:*
  • Avec le joker ? :
    • Recherche de tous les établissements dont l'unité légale a un sigle sur 3 positions : /siret?q=sigleUniteLegale:???
    • Recherche de tous les établissements dont l'unité légale a un sigle qui commence par FC et est sur 3 positions exactement : /siret?q=sigleUniteLegale:FC?

Recherche sur des approximations

  • Recherche de tous les établissements dont l'unité légale a comme prenom1UniteLegale MICKAEL à deux caractères près, mais pas MICKAEL exactement : /siret?q=prenom1UniteLegale:MICKAEL~ AND -prenom1UniteLegale:MICKAEL
  • Recherche de tous les établissements dont l’unité légale a pour sigle PAUL à une erreur près : /siret?q=sigleUniteLegale:PAUL~1
  • Recherche de toutes les UL dont le nom d’usage va de DUPONT à DURAND,
    • y compris DUPONT et DURAND : /siret?q=nomUsageUniteLegale:[DUPONT TO DURAND]
    • Non compris DUPONT et DURAND : /siret?q=nomUsageUniteLegale:%7BDUPONT TO DURAND%7D
    • Y compris DUPONT et non compris DURAND : /siret?q=nomUsageUniteLegale:[DUPONT TO DURAND%7D

Recherche sur des variables de type date

      Pour les SIRET :
      • dateCreationEtablissement
      • dateDernierTraitementEtablissement
      • dateDebut
      • dateFin
      • dateCreationUniteLegale
      • dateDernierTraitementUniteLegale
      • dateDebut
      • dateFin
      La syntaxe pour requêter sur les variables dates est la suivante :
      • variabledate:AAAA-MM-JJ
      • variabledate:AAAA-MM recherche sur le mois correspondant
      • variabledate:AAAA recherche sur l'année correspondante
      La syntaxe pour requêter sur les périodes:
      • variabledate:[2001 TO 2004-05] cherchera du 01/01/2001 inclus au 31/05/2004 inclus
      • variabledate:[2017 TO *] cherchera à partir du 01/01/2017
      EXEMPLES :
      • Recherche de toutes les UL dont la date de création est au 01/01/2014 : /siren?q=dateCreationUniteLegale:2014-01-01
      • Recherche de toute les UL dont l’année de création est entre 1980 et 2003 : /siren?q=dateCreationUniteLegale:[1980 TO 2003]
      • Recherche de tous les établissements mis à jour au mois de février 2018 et non mis à jour depuis : /siret?q=dateDernierTraitementEtablissement:2018-02
      • Recherche de toutes les UL qui ont eu un changement de dénomination l'année 2017 : /siren?q=periode(changementDenominationUniteLegale:true AND dateDebut:2017)

 

    La syntaxe pour requêter avec des dates en paramètres :
          La syntaxe est la suivante :

?q={requete}&date=AAA-MM-JJ

EXEMPLES :

  • Recherche de toutes les UL actives au 18/09/2009 : /siren?q=periode(etatAdministratifUniteLegale:A)&date=2009-09-18
  • Recherche de tous les établissements de Malakoff dont l’activitePrincipaleEtablissement est 56.10A : (restauration traditionnelle) et actifs au 01/01/2018 : /siret?q=periode(etatAdministratifEtablissement:A AND activitePrincipaleEtablissement:56.10A) AND codeCommuneEtablissement:92046 &date=2018-01-01

PAGINATION DES RESULTATS :

      • {nombre} : unités légales ou établissements à afficher par page (entre 0 et 1 000). La valeur par défaut est 20 réponses par page.
      • {debut} : correspond au rang de classement du premier établissement à afficher sur la page. La valeur par défaut est 0 (attention 0 correspond au premier établissement). Le paramètre a été limité à 100 000 pour des raisons de performance.
        Attention : lorsque vous souhaitez utiliser le paramètre {debut}, il est fortement recommandé d'utiliser le paramètre {tri}.
        • {tri} indique si les résultats doivent ou non être triés. Par défaut le paramètre vaut false afin de favoriser la performance de l'appel. Dans ce cas, les résultats sont triés par un score de pertinence. Si plusieurs éléments obtiennent le même score ils peuvent arriver dans n'importe quel ordre et cet ordre peut varier d'une interrogation à l'autre. En fixant le paramètre à true, les éléments obtenant le même score seront classés par siren ou siret selon la collection interrogée. Ce paramétrage à true est fortement recommandé lorsque le paramètre {debut} est utilisé.
      • CURSEURS : Si vous désirez parcourir un grand nombre de résultats, notamment pour obtenir des résultats au-delà de la limite indiquée ci-dessus, pour des raisons de performance il est fortement recommandé d’utiliser des curseurs. A votre première requête ajouter le paramètre curseur=*.
        • Première requête : /siret?q=*&curseur=*&nombre=100

 

        Retour :
        • Nombre : 100,
        • Curseur : "*" ,
        • CurseurSuivant : "AoEuMTIwMDI3MDE2MDAzNjU="
        • Requête suivante:/siret?q=*&curseur=AoEuMTIwMDI3MDE2MDAzNjU=&nombre=100
        • Retour :
        • Nombre : 100,
        • Curseur": "AoEuMTIwMDI3MDE2MDAzNjU=",
        • CurseurSuivant : "AoEuMTIwMDI3MDE2MDA1MjI="

RECHERCHES MULTICRITERES :

Je n'ai pas regardé les facettes qui ne permettent que des comptages

      Selection des champs (projections en langage de manipulations de données) :
      • Afficher le champs dateCreationEtablissement pour l'établissement ayant le siret 39860733300059 : /siret/39860733300059?champs=dateCreationEtablissement
      • Afficher plusieurs champs sur ce même établissement : /siret/39860733300059?champs=nomUniteLegale,dateCreationEtablissement ou /siret/39860733300059?champs=nomUniteLegale,dateCreationEtablissement,enseigne1Etablissement
      • Masquer les valeurs nulles : /siren/356000000?masquerValeursNulles=true&date=2019-01-01

RECHERCHES PHONETIQUES :

      En effet, il est possible de faire des recherches sur la phonétique des mots.

 

      La syntaxe est la suivante, au choix :
      • /siren?q=periode(nomVariable.phonetisation:{recherche}) pour les variables historisées
      • /siren?q=nomVariable.phonetisation:{recherche} pour les variables non historisées
      • /siret?q=periode(nomVariable.phonetisation:{recherche}) pour les variables historisées
      • /siret?q= nomVariable.phonetisation:{recherche} pour les variables non historisées
        • Recherche des entreprises (personnes physiques) dont le nom correspond phonétiquement à mairau : siren?q=periode(nomUniteLegale.phonetisation:mairau)&champs=nomUniteLegale&nombre=20
        • Recherche des établissements dont la dénomination courante de l’entreprise contient un mot correspondant phonétiquement à oto : siret?q=denominationUniteLegale.phonetisation:oto&champs=denominationUniteLegale&nombre=10

SCORE

        Pour chacun des résultats obtenus, selon la valeur jugée plus ou moins fiable, un score est affecté, permettant ainsi un tri à l'affichage. Cependant, ce sore doit être demandé dans la requête. Icin nous obtenons une recherche sur les 8 premiers résultats dont la dénominationUnitéLégale=auto :
        • /siret?q=denominationUniteLegale:auto&champs=score,denominationUniteLegale&nombre=8
          • Dans le cadre de score, il est possible de pondérer les valeurs de retour.

 

      • Recherche sur le sigle et la dénomination en privilégiant la dénomination : /siret?q=ponderation(denominationUniteLegale*2sigleUniteLegale*1:unimer)&champs=score,denominationUniteLegale,sigleUniteLegale
      • Recherche de plusieurs mots dans la denominationUniteLegale en privilégiant un mot :/siren?q=ponderation(denominationUniteLegale*4:hotel) OR ponderation(denominationUniteLegale*2:mer) &champs=score,denominationUniteLegale&nombre=5

Connaitre l'état du service interrogé

Il faut avoir à l'esprit que ce système n'est pas mis à jour en temps réel, mais suite au lancement de batch à intervalle (réguliers ?). Aussi, est il important de connaitre ces dernières dates de mises à jour. C'est grace à cette commande

https://api.insee.fr/entreprises/sirene/V3/informations

    Trois dates sont importantes :
    • dateDerniereMiseADisposition : Les données sont mises à jour quotidiennement et intègrent les modifications enregistrées au répertoire Sirene la veille. Une fois par jour, les données consultées basculent de J-2 à J-1. En pratique quelques milliers d'unités voient leur situation évoluer, la grande majorité des unités restent inchangées.
    • dateDernierTraitementMaximum : Toutes les données enregistrées dans le répertoire Sirene jusqu'à cette date sont accessibles par le service API Sirene. Cette date intéresse un utilisateur cherchant à mettre à jour une copie des données.
    • dateDernierTraitementDeMasse : Entre 1 et 3 fois dans l'année, des traitements de gestion peuvent impacter un très grand nombre d'unités (par exemple la mise à jour annuelle des effectifs peut concerner plus de 3 millions d'unités légales en une seule fois)