Documentation technique

v002/referentiel/communes/

Point d’entrée

  • méthode : GET (pour utilisation JSONP) / POST – application/x-www-form-urlencoded
  • url : /v002/referentiel/communes/
  • paramètres :
  1. query : la représentation au format JSON de la requête (voir Format de la requête, ci-dessous)
  2. callback : nom de la fonction de callback (uniquement en GET pour utilisation JSONP)

Format de la requête

La requête est un objet à sérialiser en JSON.

Le schéma JSON de la requête est disponible sur cette page (fichier apiReferentielCommunesRequete.schema).

On y trouve les champs suivants :

apiKey

  • description : clé d’API
  • type : chaîne de caractères
  • où trouver l’information : clé d’API
  • exemple :
"apiKey" : "s34WSq8"

projetId

  • description : identifiant du projet
  • type : entier
  • où trouver l’information : sur la fiche Apidae du projet
  • attention : il faut que la clé d’API et l’identifiant de site web correspondent
  • exemple :
"projetId" : 123

communeIds

  • description : les identifiants des communes à retourner. Si plusieurs communes sont spécifiées, on applique un opérateur OU entre elles. Ignoré si la liste est nulle ou vide.
  • type : liste d’entiers.
  • où trouver l’information : dans les fichiers d’exports.
  • exemple :
"communeIds":[ 14762, 28713 ]

codesInsee

  • description : codes INSEE des communes à retourner. Si plusieurs communes sont spécifiées, on applique un opérateur OU entre elles. Ignoré si la liste est nulle ou vide.
  • type : liste de chaînes de caractères.
  • où trouver l’information : www.insee.fr/fr/methodes/nomenclatures/cog/
  • exemple :
"codesInsee":[ "69275", "69388" ]

Remarques :

  • Lorsque les champs communeIds et codesInsee sont tous les deux remplis, on applique un opérateur OU entre les deux listes.
  • Si aucun des deux champs n’est rempli, la requête ne renverra aucun résultat.

Exemple de requête au format JSON :

{
    "projetId" : 123,

    "apiKey" : "dfl87jq5",

    "communeIds": [ 1278, 14762, 28713],

    "codesInsee" : ["38534", "69388", "74140"]
}

Format de sortie

La réponse est un tableau de communes sérialisé en JSON.

Le schéma JSON de la réponse est disponible sur cette page (fichier apiReferentielCommunesResultat.schema).

Attention, le nombre de communes retournées par ce service est limité à 500. Cette limitation a été délibérément mise en place pour éviter les abus. Si vous utilisez les exports et que vous avez besoin de récupérer un plus grand nombre de communes, peut-être devriez-vous exploiter le fichier communes.json se trouvant dans les archives d’export.

Exemple de résultat (2 communes) :

[ {
  "id" : 1278,
  "code" : "03043",
  "nom" : "Broût-Vernet",
  "pays" : {
    "elementReferenceType" : "Pays",
    "id" : 532,
    "libelleFr" : "France",
    "libelleEn" : "France",
    "libelleEs" : "Francia",
    "libelleIt" : "Francia",
    "libelleDe" : "FRANKREICH",
    "libelleNl" : "FRANKRIJK",
    "ordre" : 78
  },
  "codePostal" : "03110"
}, {
  "id" : 30717,
  "code" : "74140",
  "nom" : "Habère-Poche",
  "pays" : {
    "elementReferenceType" : "Pays",
    "id" : 532,
    "libelleFr" : "France",
    "libelleEn" : "France",
    "libelleEs" : "Francia",
    "libelleIt" : "Francia",
    "libelleDe" : "FRANKREICH",
    "libelleNl" : "FRANKRIJK",
    "ordre" : 78
  },
  "codePostal" : "74420"
} ]

Cas d’erreur

  • Erreur 40x : erreur dans la requête ; le corps de la réponse HTTP contient le message d’erreur au format texte.
  • Erreur 50x : erreur de traitement ; le corps de la réponse HTTP contient le message d’erreur au format texte.