documentation

Le service de géocodage permet de fournir les coordonnées géographiques d’une adresse postale, d’un lieu ou d’une parcelle cadastrale à partir d’une requête HTTP. Les données de références utilisées par le service de géocodage sont :

• la BAN (Base Adresse Nationale) pour le géocodage des adresse ;
• la BDTOPO pour le géocodage des noms de lieux (appelés aussi « POI ») ;
• le produit Parcellaire Express (PCI) pour le géocodage des parcelles.

Le géocodage des lieux est composé de plusieurs thèmes dont le thème administratif permettant de localiser les différentes divisions administrative du territoire (commune, région…).

l’instance de test du service de géocodage est accessible à l’adresse suivante : https://geocodage.ign.fr/look4/{indice}/{méthode}?

La documentation technique du service au format OpenAPI peut être consultée ici.

Le paramètre indice permet de spécifier la donnée de référence utilisée. Les valeurs possibles sont :

• address (pour une recherche sur les adresses) ;
• poi (pour une recherche sur les lieux) ;
• parcel (pour une recherche surles parcelles cadastrales) ;
• location (pour une recherche groupée sur les adresses et les lieux).

Le paramètre méthode, quant à lui, permet d’indiquer suivant quelle méthode doit s’effectuer la recherche. Les valeurs possibles sont :

• search (pour une recherche de géocodage) ;
• reverse (pour une recherche de géocodage inverse).

Les requêtes sont de type HTTP GET : on ajoute à l’url les paramètres sous la forme clé=valeur.

Les capacités du service (ressources disponibles, paramètres et valeurs autorisées) sont accessibles via l’url : https://geocodage.ign.fr/look4/getCapabilities

En réponse à une requête de géocodage ou de géocodage inverse le service retourne un objet JSON de type “FeatureCollection”. Les feature sont composés d’attributs qui différent en fonction du type de l’objet (address, poi ou parcel). Pour chaque feature de la collection le service retourne en complément des attributs les éléments suivants :

• _score : le score de géocodage
• _type : le type de l’objet (address, poi ou parcel)

Le calcul du score, dont la valeur est comprise entre 0 et 1, s’effectue de la manière suivante : Le score est calcul à partir de plusieurs composantes. Chacune d’entre elles est définie par un poids et son score peut-être compris entre 0 et ce poids. Le score final est calculé de la manière suivante : score final = somme des scores des composantes / somme des poids des composantes

Le score du géocodage est calculé à partir de 3 composantes :

• la distance entre chaînes de charactères (poids: 1) : calculée par comparaison entre la chaîne de la requête et les labels des objets ;
• la distance géographique (poids: 1) : calculée en fonction de la distance entre le localisant de l’objet et un point de référence spécifié dans la requête. Si le point de référence n’est pas spécifié dans la requête (paramètre lonlat), cette composante n’est pas prise de en compte.
• l’importance de l’objet (poids 0,1) : chaque objet possède un champs importance dont la valeur est comprise entre 0 et 1.

Le score du géocodage inverse est calculé à partir d’une seule composante :

• la distance géographique (poids: 1)

Ci-après la composition attributaire des différents types d’objet : Type “POI” :

• postalCode (tableau) : liste codes postaux (5 chiffres)
• inseeCode (tableau) : liste codes INSEE de départementaux (2 chiffres), et communaux (5 chiffres)
• toponyme (chaîne de caractères) : toponyme principal avec majuscules et accentuation
• type (tableau) : liste des types de l’objet
• extraFields (objet JSON) : objet constitué d’attributs supplémentaires extraits des données sources
• trueGeometry (geometrie GeoJSON) : géométrie de l’objet
• geometry (geometrie GeoJSON) : géometrie ponctuelle calculée à partir de la géométrie complexe de l’objet (trueGeometry).

Type “address” :

• city (chaîne de caractères) : le nom de la commune
• street (chaîne de caractères) : libellé de la voie
• postalCode (code de 5 chiffres) : le code postal
• number (chaîne de caractères) : le numéro dans la voie
• inseeCode (tableau) : liste comprenant le code INSEE du département (2 chiffres), et celui de la commune (5 chiffres)
• houseNumberInfos (objet JSON) : objet fournissant des informations complémentaires sur l’adresse
• geometry (geometrie GeoJSON) : géometrie ponctuelle, position de principale de l’adresse

Type “parcel” :

• identifiant (chaîne de caractères) : l’identifiant unique de la parcelle cadastrale
• codeDepartement (code de 2 chiffres) : le code INSEE du département
• codeCommune (code de 3 chiffres) : le code INSEE de la commune
• nomCommune (chaîne de caractères) : le nom de la commune
• codeCommuneAbs (code de 3 chiffres) : le code INSEE de la commune absorbée
• codeArrondissement (code de 3 chiffres) : le code INSEE de l’arrondissement
• section (code de 2 lettres) : le code de la section cadastrale
• numero (entier) : le numéro de la parcelle cadastrale
• feuille (entier) : le numéro de la feuille
• trueGeometry (geometrie GeoJSON) : la géométrie de la parcelle issue des données sources.
• geometry (geometrie GeoJSON) : géometrie ponctuelle calculée à partir de la géométrie complexe de l’objet (trueGeometry).

Les paramètres pour ce type de requête sont les suivants :

• q [obligatoire] : chaîne décrivant la localisation à rechercher
• lonlat [optionnel] : coordonnées (longitude, latitude) d’un localisant pour favoriser les candidats les plus proches.
• maxResp [optionnel] : nombre maximum d’objets retournés dans la réponse. La valeur par défaut est 10. Le nombre maximum d’objet pouvant être retournés est 100.
• returnTrueGeometry [optionnel] : booléen pour indiquer si la vraie géométrie doit être retournée. La valeur par défaut est “false”.
• filters [optionnel] : objet permettant d’associer des propriétés avec des valeurs de filtrage. Les propriétés de filtrage varient suivant le type de donnée de référence. Plusieurs propriétés de filtrage peuvent être définies. En revanche, il n’est pas possible d’associer plusieurs valeurs de filtrage à une même propriété. Exemple :
  • filtrage autorisé : filters[propriété1]=valeur1&filters[propriété2]=valeur2
  • filtrage non autorisé : filters[propriété1]=valeur1&filters[propriété1]=valeur2

La recherche par lieux regroupe plusieurs thèmes. Ces thèmes sont les suivants :

• cimetière
• aérodrome
• réservoir
• administratif
• construction linéaire
• construction ponctuelle
• construction surfacique
• cours d’eau
• détail hydrographique
• détail orographique
• équipement de transport
• plan d’eau
• poste de transformation
• terrain de sport
• transport par câble
• zone d’activite ou d’interet
• zone d’habitation

Les propriétés de filtrage (paramètre filters) pour les lieux sont :

• postalCode : le code postal constitué de 5 chiffres
• inseeCode : le code INSEE du département (2 chiffres) ou de la commune (5 chiffres)
• type : la valeur du type peut être prise parmi les noms des thèmes mentionnés ci-avant ou bien parmi les valeurs de type détaillé qui existent pour chaque thème et dont la liste complète est fournie dans la documentation de l’API

Exemple de recherche de géocodage sur les lieux :https://geocodage.ign.fr/look4/poi/search?q=roissy%20charles%20de%20gaulle&filters[type]=a%C3%A9rodrome&returnTrueGeometry=true

Dans cette requête nous recherchons des objets de type POI dont le libellé est proche de la chaîne de caractère “roissy charles de gaulle” et dont le type comprend la valeur “aérodrome”. Nous précisons également que nous souhaitons récupérer dans la réponse la géométrie complexe des objets (dans le cas présent, des polygones).

Réponse:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "postalCode": ["95380",...],
        "inseeCode": ["93073","93",...],
        "toponyme": "Aéroport de Paris-Charles de Gaulle",
        "type": ["aérodrome"],
        "extraFields": {
          "cleabs": "AERODROM0000000003752586",
          "nature_detaillee": "",
          "names": ["aérodrome louvres","aérodrome épiais-lès-louvres","aéroport de paris-charles de gaulle",...]
        },
        "trueGeometry": {
          "type": "MultiPolygon",
          "coordinates": [[[[2.4823760016619,48.8589843844804,69.7],
            [2.48366443142965,48.8590798844387,66.7],[2.48368714658264,48.85912584868... ],
            ...80304411,72.8],[2.4823760016619,48.8589843844804,69.7]]]]
        },
        "_score": 0.5,
        "_type": "poi"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [2.48288196455206,48.8600271058162]
      }
   }
  ]
}

Les propriétés de filtrage (paramètre filters) pour les adresses sont :

• postalCode : le code postal constitué de 5 chiffres
• inseeCode : le code INSEE du département (2 chiffres) ou de la commune (5 chiffres)
• city : le nom de la commune

Les codes postaux, codes insee ou nom de commune peuvent être directement ajoutés en complément de la chaîne de recherche (paramètre q). Exemple : Le paramètrage q=15 rue nationale&filters[inseeCode]=75 peut être remplacé par q=15 rue nationale 75 Il n’est pas interdit d’ajouter le paramètre ‘returnTrueGeometry’ dans la requête mais ce dernier n’aura pas d’effet puisque seul une géométrie ponctuelle peut être retournée (position principale de l’adresse peut être retournée)

Exemple de recherche de géocodage sur les adresses : https://geocodage.ign.fr/look4/address/search?q=10 rue nationale 75&lonlat=2.369,48.822

Dans cette requête nous recherchons des objets de type address dont le libellé est proche de la chaîne de caractère “10 rue nationale 75”. Le score sera influencé par la distance des objets au point de référence dont les coordonnées sont spécifiées par le paramètre “lonlat”. Les objets les plus proche de ce point verront leur score amélioré.

Réponse :

{
   "type": "FeatureCollection",
   "features": [
     {
       "type": "Feature",
       "properties": {
         "city": "Paris 13e Arrondissement",
         "street": "Rue Nationale",
         "postalCode": "75013",
         "number": "10",
         "inseeCode": ["75113","75"],
         "houseNumberInfos": {
           "date":"2018-10-21",
           "source":"ign",
           "kind":"entrance"
         },
         "_score":0.9761899647698602,
         "_type":"address"
       },
       "geometry": {
         "type": "Point",
         "coordinates": [2.369025,48.822466]}
       }
     },
     {
       "type": "Feature",
       …
     }
   ]
 }

Les propriétés de filtrage (paramètre filters) pour les parcelles sont :

• codeDepartement : le code du département (2 chiffres)
• codeCommune : le code de la commune (3 chiffres)
• nomCommune : le nom de la commune
• codeCommuneAbs : le code de la commune absorbée (3 chiffres)
• codeArrondissement : le code de l’arrondissement (3 chiffres)
• section : le numéro de la section cadastral (2 lettres)
• numero : le numéro de la parcelle cadastrale
• feuille : numéro de la feuille

Pour faire une recherche de parcelle cadastrale, il faut connaître la référence cadastrale de la parcelle.

Exemple : https://geocodage.ign.fr/look4/parcel/search?q=920120000G0027&returnTrueGeometry=true Dans cette requête nous recherchons l’objet de type parcel dont le libellé vaut “920120000G0027”. Nous précisons également que nous souhaitons récupérer dans la réponse la géométrie complexe des objets (dans le cas présent, des polygones).

Réponse :

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "identifiant": "920120000G0027",
        "codeDepartement": "92",
        "codeCommune": "012",
        "nomCommune": "Boulogne-Billancourt",
        "codeCommuneAbs": "000",
        "codeArrondissement": "000",
        "section": "0G",
        "numero": "0027",
        "feuille": 1,
        "trueGeometry": {
          "type": "MultiPolygon",
          "coordinates": [
            [[[2.23124554382499,48.8452290709846],
            ...54382499,48.8452290709846]]]
          ]
        },
        "_score": 1,
        "_type": "parcel"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [2.23133407213081,48.8450469160941]
      }
    }
  ]
}

Si l’utilisateur ne connaît pas la référence et souhaite utiliser les filtres de recherche, il faut tout de même spécifier le paramètre “q” (paramètre obligatoire) en lui affectant une chaîne vide.

Exemple : https://geocodage.ign.fr/look4/parcel/search?q=’‘&filters[codeDepartement]=95&filters[codeCommune]=200&filters[numero]=2

Pour la recherche multi-index avec l’indice “location”, les propriétés de filtrage des 2 index (address et POI) peuvent être utilisées. Chaque filtrage sera appliqué sur l’index concerné et n’aura pas d’effet sur l’autre.

Par exemple dans la requête qui suit, un filtrage est réalisé sur la propriété “type” qui existe pour le type POI mais qui n’existe pas pour le type address : https://geocodage.ign.fr/look4/location/search?q=vincennes&filters[type]=commune Ce filtrage ne sera donc pas pris en compte pour le type address et des objets address pourront donc être retourné dans la réponse du service. En revanche, le filtrage sera effectif sur le type POI. Seul des objets POI ayant un champ ‘type’ valant ‘commune’ seront donc retournés.

Les paramètres pour ce type de requête sont les suivants :

• searchGeom [obligatoire] : Geométrie utilisée pour la recherche géographique par intersection avec la géométrie des objets POI. Les types géométriques autorisés sont : Point, LineString, Polygon. En plus des types GeoJSON autorisés, il est possible d’utiliser un type de géometrie supplémentaire qui ne fait pas parti du standard GeoJSON : le type “Circle”. Ce dernier s’écrit de la manière suivante :

{
    type: 'Circle',
    coordinates: [2.0, 48.5],
    radius: 100
}

Le paramètre “radius’ est exprimé en mètres. Il est à noter qu’il existe des restrictions sur le paramètre searchGeom:

• Pour l’index “address’, seuls les types géométriques “Polygon” et “Cycle” sont autorisés,

• Le plus grand côté du rectangle d’emprise de la géométrie ne doit pas excéder 1000 mètres.

• lonlat [optionnel] : coordonnées (longitude, latitude) du point de référence à partir duquel est calculée la distance, puis le score permettant l’ordonnancement des résultats. Si ce paramètre n’est pas renseigné le point de réference sera calculé automatique à partir de la géométrie du paramètre searchGeom.
• maxResp [optionnel] : nombre maximum d’objets retournés dans la réponse. La valeur par défaut est 10. Le nombre maximum d’objet pouvant être retournés est 100.
• returnTrueGeometrie [optionnel] : booléen pour indiquer si la vraie géométrie doit être retournée. La valeur par défaut est “false”.
• filters [optionnel] : objet permettant d’associer des propriétés avec des valeurs de filtrage. Les propriétés de filtrage varient suivant le type de donnée de référence. Plusieurs propriétés de filtrage peuvent être définies. En revanche, il n’est pas possible d’associer plusieurs valeurs de filtrage à une même propriété. Exemple :
• filtrage autorisé : filters[propriété1]=valeur1&filters[propriété2]=valeur2
• filtrage non autorisé : filters[propriété1]=valeur1&filters[propriété1]=valeur2

La recherche par lieux regroupe plusieurs thèmes. Ces thèmes sont les suivants :

• cimetière
• aérodrome
• réservoir
• administratif
• construction linéaire
• construction ponctuelle
• construction surfacique
• cours d’eau
• détail hydrographique
• détail orographique
• équipement de transport
• plan d’eau
• poste de transformation
• terrain de sport
• transport par câble
• zone d’activite ou d’interet
• zone d’habitation

Les propriétés de filtrage (paramètre filters) pour les lieux sont :

• postalCode :le code postal constitué de 5 chiffres
• inseeCode : le code INSEE du département (2 chiffres) ou de la commune (5 chiffres)
• type : la valeur du type peut être pris parmis les noms des thèmes mentionnés ci-avant ou bien parmis les valeurs de type détaillé qui existent pour chaque thème et dont la liste complète est fournie sur la documentation de l’API

Exemple de recherche de géocodage inverse sur les lieux : https://geocodage.ign.fr/look4/poi/reverse?searchGeom={“type”:”Point”,”coordinates”:[2.363348,48.827650]}&filters[type]=département

Par cette réquête nous souhaitons récupérer les objets de type POI dont la géométrie complexe intersecte le point localisé aux coordonnées longitude=2.363348 et latitude=48.827650 et dont la propriété “type” comprant la valeur “département”.

Réponse :

{
   "type": "FeatureCollection",
   "features": [
     {
       "type": "Feature",
       "properties": {
         "postalCode":[],
         "inseeCode": ["75"],
         "toponyme": "Paris",
         "extraFields": {
           "cleabs": "DEPARTEM0000002150000468",
           "names": ["paris"]
       },
       "type" : ["administratif","département"],
       "trueGeometry": "",
       "_score": 1,
       "_type": "poi"
     },
     "geometry":
       {
         "type": "Point",
         "coordinates": [2.31987826073,48.8586469225]
       }
    }
  ]
}

Les propriétés de filtrage (paramètre filters) pour les adresses sont :

• postalCode :le code postal constitué de 5 chiffres
• inseeCode : le code INSEE du département (2 chiffres) ou de la commune (5 chiffres)
• city : le nom de la commune

Les codes postaux, codes INSEE ou nom de commune peuvent être directement ajoutés en complément de la chaîne de recherche (paramètre q). Exemple : Le paramètrage ‘q=15 rue nationale&filters[inseeCode]=75’ peut être remplacé par ‘q=15 rue nationale 75’ Il n’est pas interdit d’ajouter le paramètre ‘returnTrueGeometry’ dans la requête mais ce dernier n’aura pas d’effet puisque seul une géométrie ponctuelle peut être retournée (position principale de l’adresse peut être retournée)

Exemple de recherche de géocodage inverse sur les adresses : https://geocodage.ign.fr/look4/address/reverse?searchGeom={“type”:”Polygon”,”coordinates”:[[[2.354,48.838],[2.354,48.839],[2.357,48.839],[2.357,48.838],[2.354,48.838]]]}&filters[inseeCode]=75

Par cette réquête nous souhaitons récupérer les objets de type address dont la géométrie (ponctuelle) intersecte le polygone dont les coordonnées sont spécifiées dans le paramètre “searchGeom” et dont la propriété “inseeCode” comprant la valeur “75”.

Réponse :

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "city": "Paris 5e Arrondissement",
        "street": "Rue des Fossés Saint-marcel",
        "postalCode": "75005",
        "number": "14",
        "inseeCode": ["75105","75"],
        "houseNumberInfos": {
          "date": "2018-10-21",
          "source": "ign",
          "kind": "entrance",
          "otherPositions": [
            {
              "date": "2018-10-21",
              "source": "dgfip",
              "kind": "parcel",
              "geometry": {
                "type": "Point",
                "coordinates": ["2.355673","48.838603"]
              }
            }
          ]
        },
        "_score": 0.9769854718881752,
        "_type": "address"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [2.355869,48.838509]
      }
    },
    {
      "type": ...
    }
  ]
}

Les propriétés de filtrage (paramètre filters) pour les parcelles sont :

• codeDepartement : le code du département (2 chiffres)
• codeCommune : le code de la commune (3 chiffres)
• nomCommune : le nom de la commune
• codeCommuneAbs : le code de la commune absorbée (3 chiffres)
• codeArrondissement : le code de l’arrondissement (3 chiffres)
• section : le numéro de la section cadastral (2 lettres)
• numero : le numéro de la parcelle cadastrale
• feuille : numéro de la feuille

Pour faire une recherche de parcelle cadastrale, il faut connaître la référence cadastrale de la parcelle.

Exemple de recherche de géocodage inverse sur les parcelles cadastrales : https://geocodage.ign.fr/look4/parcel/reverse?searchGeom={“type”:”Point”,”coordinates”:[2.2313,48.845]}

Par cette réquête nous souhaitons récupérer les objets de type parcel dont la géométrie complexe intersecte le point de coordonnées : longitude=2.2313 et latitude=48.845.

Réponse :

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "identifiant": "920120000G0027",
        "codeDepartement": "92",
        "codeCommune": "012",
        "nomCommune": "Boulogne-Billancourt",
        "codeCommuneAbs": "000",
        "codeArrondissement": "000",
        "section": "0G",
        "numero": "0027",
        "feuille": 1,
        "trueGeometry": {
          "type": "MultiPolygon",
          "coordinates": [
            [[[2.23124554382499,48.8452290709846],
            ...54382499,48.8452290709846]]]
          ]
        },
        "_score": 1,
        "_type": "parcel"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [2.23133407213081,48.8450469160941]
      }
    }
  ]
}

Pour la recherche multi-index avec l’indice “location”, les propriétés de filtrage des 2 index (address et POI) peuvent être utilisées. Chaque filtrage sera appliqué sur l’index concerné et n’aura pas d’effet sur l’autre.

Par exemple dans la requête qui suit, un filtrage est réalisé sur la propriété “type” qui existe pour le type POI mais qui n’existe pas pour le type address : https://geocodage.ign.fr/look4/location/reverse?searchGeom={“type”:”Polygon”,”coordinates”:[[[2.3776307702064514,48.85442547791262],[2.3776307702064514,48.85469373059058],[2.378220856189728,48.85469373059058],[2.378220856189728,48.85442547791262],[2.3776307702064514,48.85442547791262]]]}&filters[type]=commune

Ce filtrage ne sera donc pas pris en compte pour le type address et des objets address pourront donc être retourné dans la réponse du service. En revanche, le filtrage sera effectif sur le type POI. Seul des objets POI ayant un champ ‘type’ valant ‘commune’ seront donc retournés.