TrustyData Docs
Site Tarifs Contact

Communes

Un champ « ville » saisi librement contient des fautes de frappe, des noms d'arrondissement incomplets ou une hésitation de l'utilisateur. À l'inverse, un usage marketing ou logistique a parfois besoin de constituer une cohorte géographique — « toutes les communes de plus de 180 000 habitants en Île-de-France » — sans connaître un seul nom de commune à l'avance. Les deux endpoints ci-dessous interrogent le même référentiel : le Code Officiel Géographique (COG) de l'INSEE.

Endpoint Quand l'utiliser Plan minimum
GET /locality/autocomplete Champ de saisie « ville » — suggestions au fil de la frappe Discovery
GET /locality/search Cohorte géographique par filtres combinables (département, région, population), avec ou sans nom de commune Discovery

GET /locality/autocomplete — suggestions pendant la frappe

Branchez cet endpoint sur un champ de saisie « ville » : à chaque caractère tapé, il retourne les communes correspondantes par nom, code postal ou code INSEE, classées par pertinence. 

curl -H "Authorization: Bearer VOTRE_CLE_API" \
  "https://api.trustydata.app/services/v1/locality/autocomplete?q=wimereux"
{
  "status": "OK",
  "message": "Search completed successfully",
  "suggestions": [
    {
      "score": 1,
      "id": 27238,
      "destination": "62930 WIMEREUX",
      "nom_commune": "WIMEREUX",
      "code_postal": "62930",
      "ligne_5": "",
      "ligne_6": "WIMEREUX",
      "position": { "lat": 50.780282, "lon": 1.614473 },
      "surface": { "hectare": 826, "km2": 8 },
      "elevation": { "min": 0, "max": 71, "average": 24 },
      "density": { "code": 4, "label": "Ceintures urbaines" },
      "population": [
        { "periode": 2022, "totale": 6438, "municipale": 6307, "comptee_a_part": 131 },
        { "…": "…" }
      ],
      "departement": { "id": "62", "libelle": "Pas-de-Calais", "nom_riche": "Pas-de-Calais", "…": "…" },
      "region": { "id": "32", "libelle": "Hauts-de-France", "nom_riche": "Hauts-de-France", "…": "…" },
      "cog": { "insee": "62893", "type": "COM", "libelle": "Wimereux", "…": "…" }
    }
  ]
}

Le champ score (0 à 1) indique la pertinence de la suggestion. destination, ligne_5 et ligne_6 recomposent la commune sur une adresse multi-lignes ; cog.insee est le code commune INSEE stable — à ne pas confondre avec code_postal (voir plus bas). position ne renvoie ici que lat/lon (pas de coordonnées Lambert 93, contrairement aux adresses). details vaut true par défaut : c'est lui qui ajoute surface, elevation, density, departement et region — voir plus bas.

GET /locality/search — filtrer sans connaître les noms

Contrairement à l'autocomplétion, /locality/search accepte une recherche sans aucun texte : combinez department_code, region_name, population_min et population_max pour extraire une cohorte de communes qui partagent des caractéristiques géographiques et démographiques, sans connaître un seul nom de commune à l'avance. C'est le principal intérêt de cet endpoint face à l'autocomplétion. 

curl -G "https://api.trustydata.app/services/v1/locality/search" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  --data-urlencode "region_name=ILE DE FRANCE" \
  --data-urlencode "population_min=180000" \
  --data-urlencode "details=false"
{
  "status": "OK",
  "message": "Search completed successfully",
  "results": [
    {
      "score": 1,
      "id": 32622,
      "destination": "75015 PARIS",
      "nom_commune": "PARIS 15",
      "code_postal": "75015",
      "ligne_5": "",
      "ligne_6": "PARIS",
      "population": [
        { "periode": 2022, "totale": 230390, "municipale": 228754, "comptee_a_part": 1636 },
        { "…": "…" }
      ]
    },
    { "nom_commune": "PARIS 18", "code_postal": "75018", "…": "…" },
    { "nom_commune": "PARIS 20", "code_postal": "75020", "…": "…" }
  ]
}

Aucun paramètre q n'a été passé : la réponse liste la cohorte sous la clé results, avec les seuls champs de base (details=false ici — voir plus bas). Trois arrondissements parisiens franchissent le seuil de 180 000 habitants ; ni leur nom, ni leur code postal n'ont été fournis en entrée. Notez que region_name attend la valeur normalisée du COG, en majuscules et sans accent (ILE DE FRANCE, pas « Île-de-France ») — la liste complète des valeurs acceptées est dans la référence.

Un nom, un code postal ou un code INSEE peut être combiné aux mêmes filtres via q — la réponse bascule alors sur la clé suggestions, comme pour l'autocomplétion : 

curl -G "https://api.trustydata.app/services/v1/locality/search" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  --data-urlencode "q=95690" \
  --data-urlencode "details=true"
{
  "status": "OK",
  "message": "Search completed successfully",
  "suggestions": [
    { "nom_commune": "FROUVILLE",       "code_postal": "95690", "cog": { "insee": "95258", "…": "…" }, "…": "…" },
    { "nom_commune": "HEDOUVILLE",      "code_postal": "95690", "cog": { "insee": "95304", "…": "…" }, "…": "…" },
    { "nom_commune": "LABBEVILLE",      "code_postal": "95690", "cog": { "insee": "95328", "…": "…" }, "…": "…" },
    { "nom_commune": "NESLES LA VALLEE","code_postal": "95690", "cog": { "insee": "95446", "…": "…" }, "…": "…" }
  ]
}

Le code postal 95690 à lui seul renvoie quatre communes distinctes, chacune avec son propre code INSEE — la preuve concrète du point suivant.

Code commune INSEE ≠ code postal

Un code postal peut couvrir plusieurs communes (l'exemple ci-dessus : 95690 pour Frouville, Hédouville, Labbeville et Nesles-la-Vallée), et une grande ville peut avoir plusieurs codes postaux pour un seul code INSEE (Paris, Marseille, Lyon — un code INSEE par arrondissement). Stockez cog.insee, l'identifiant stable du référentiel COG, plutôt que code_postal, qui n'identifie pas une commune de façon unique.

Le paramètre details : réponse compacte ou enrichie

Ici, la richesse de la réponse ne dépend pas du plan — les deux endpoints sont accessibles dès Discovery — mais du seul booléen details (true par défaut) :

  • details=false — champs de base : score, id, destination, nom_commune, code_postal, ligne_5, ligne_6, population (recensement). Exemple : la cohorte Île-de-France ci-dessus.
  • details=true — ajoute position (lat/lon), surface (hectare/km2), elevation (min/max/moyenne), density (code + libellé), departement, region et cog (dont le code INSEE). Exemple : Wimereux et le code postal 95690 ci-dessus.

Prochains pas