documentation

Le service de géocodage permet de fournir les coordonnées géographiques d’une adresse postale, d’un lieu ou d’un numéro de section ou de parcelles cadastrales à partir d’une requête HTTP.

Les données adresse de référence utilisées au sein du service de géocodage proviennent de la base de données IGN BD ADRESSE® pour le géocodage à l’adresse, du thème Toponymes de la base de données IGN BD TOPO® pour le géocodage par noms de lieux et de la BD PARCELLAIRE® pour le géocodage de parcelles cadastrales ou de section.

La géocodage de noms de lieux inclut également les départements et les régions.

Le service de géocodage du Géoportail implémente le protocole OpenLS "Location Utility Service" qui est un standard défini par l’OGC (Open Geospatial Consortium). On peut consulter le document de référence sur le site de l’OGC.

Le service de géocodage est accessible à l’adresse suivante :

https://wxs.ign.fr/CLEF/geoportail/ols?

Le paramètre CLEF doit être remplacé par l'une des clés partagées de type "essentiels" ou "calcul".

Chaque type de géocodage est associé à une ressource à laquelle la clé d’accès doit être associée. La liste des ressources est disponible ici.

Les requêtes OpenLS peuvent être soit des requêtes HTTP POST XML, soit des requêtes HTTP GET en KVP comme expliqué ci-après pour chaque type de géocodage.

Quand l’attribut countryCode de la balise <Address> d’une requête est égal à "PositionOfInterest", il spécifie une recherche par lieux.

La balise <freeFormAddress> contient la localisation à rechercher :

( Préciser dans le Headers  Name : Content-Type et  Value : application/xml )

<?xml version="1.0" encoding="UTF-8"?>
<XLS
  xmlns:xls="http://www.opengis.net/xls"
  xmlns:gml="http://www.opengis.net/gml"
  xmlns="http://www.opengis.net/xls"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  version="1.2"
  xsi:schemaLocation="http://www.opengis.net/xls http://schemas.opengis.net/ols/1.2/olsAll.xsd">
    <RequestHeader/>
    <Request requestID="1" version="1.2" methodName="LocationUtilityService">
       <GeocodeRequest returnFreeForm="false">
         <Address countryCode="PositionOfInterest">
                <freeFormAddress>rennes</freeFormAddress>
         </Address>
       </GeocodeRequest>
    </Request>
</XLS>

La localisation géographique est stockée dans la balise <Point>. La balise <Place> contient le nom trouvé. La balise <GeocodeMatchCode> contient un indicateur de pertinence.

Quand l’attribut countryCode de la balise <Address> d’une requête est égal à "Administratif", il spécifie une recherche par unités administratives.

La balise <freeFormAddress> contient le nom du département ou de la région à rechercher :

<?xml version="1.0" encoding="UTF-8"?>
<XLS
  xmlns:xls="http://www.opengis.net/xls"
  xmlns:gml="http://www.opengis.net/gml"
  xmlns="http://www.opengis.net/xls"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  version="1.2"
  xsi:schemaLocation="http://www.opengis.net/xls http://schemas.opengis.net/ols/1.2/olsAll.xsd">
    <RequestHeader/>
    <Request requestID="1" version="1.2" methodName="LocationUtilityService">
       <GeocodeRequest returnFreeForm="false">
         <Address countryCode="Administratif">
            <freeFormAddress>Bretagne</freeFormAddress>
         </Address>
       </GeocodeRequest>
    </Request>
</XLS>

<XLS version="1.2" xsi:schemaLocation="http://wxs.ign.fr/schemas/olsAll.xsd">
  <ResponseHeader/>
  <Response requestID="1" version="1.2">
  <GeocodeResponse>
    <GeocodeResponseList numberOfGeocodedAddresses="1">
      <GeocodedAddress>
        <gml:Point>
        <gml:pos>48.114293 -1.680724</gml:pos>
        </gml:Point>
        <Address countryCode="Administratif">
        <StreetAddress><Street/>
        </StreetAddress>
        <Place type="Municipality">Bretagne</Place>
        <Place type="Bbox">-5.141333;47.277979;-1.015766;48.900849</Place>
        <Place type="Prefecture">Rennes</Place>
        <Place type="InseeRegion">53</Place>
        <PostalCode>53</PostalCode></Address>
        <GeocodeMatchCode accuracy="1.0" matchType="City"/>
      </GeocodedAddress>
    </GeocodeResponseList>
  </GeocodeResponse>
  </Response>
</XLS>

La localisation géographique stockée dans la balise <Point> correspond à un ponctuel situé sur le chef-lieu de l’unité administrative qui est renvoyée.

La balise <Address> contient l’ensemble des informations sur le département ou la région retourné(e) par le service (nom, emprise géographique, chef-lieu, code INSEE du département et/ou de la région). Ces attributs sont présentés dans les balises <Place>.

Quand l’attribut countryCode de la balise <Address> d’une requête est égal à "StreetAddress", il spécifie une recherche par adresses.

Corps du POST :

<?xml version="1.0" encoding="UTF-8"?>
<XLS
  xmlns:gml="http://www.opengis.net/gml"
  xmlns="http://www.opengis.net/xls"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.2"
  xsi:schemaLocation="http://www.opengis.net/xls http://schemas.opengis.net/ols/1.2/olsAll.xsd">
  <RequestHeader srsName="epsg:4326"/>
  <Request maximumResponses="25" methodName="GeocodeRequest" requestID="uid42" version="1.2">
  <GeocodeRequest returnFreeForm="false">
    <Address countryCode="StreetAddress">
      <freeFormAddress>2 avenue Pasteur 94160 Saint-Mandé</freeFormAddress>
    </Address>
  </GeocodeRequest>
  </Request>
</XLS>

L’attribut srsName de la balise <RequestHeader> permet de spécifier le système de coordonnées dans lequel seront exprimées les adresses de la réponse. Cet attribut est facultatif et vaut "epsg:4326" (système WGS84 utilisé par GPS) par défaut.

L’attribut returnFreeForm de la balise <GeocodeRequest> indique si l’utilisateur désire une adresse structurée (numéro, rue, ville et attributs) ou une adresse condensée (numéro, rue et ville en une seule chaîne de caractères). Cet attribut est facultatif et vaut "false" par défaut.

L’attribut maximumResponses de la balise <Request> indique le nombre maximum d’adresses désirées. Il est facultatif et vaut "25" par défaut.

La localisation géographique est stockée dans la balise <Point>.

La balise <Address> contient l’ensemble des informations sur l’adresse trouvée retournée par le service (adresse normalisée, identifiant du point adresse, code postal, code INSEE etc…).

La balise <Street> contient l’adresse telle que normalisée et utilisée par le service.

Les balises <Place> contiennent les attributs de l’adresse, le nom de l’attribut est dans l’attribut Type.

L’attribut Municipality contient la ville, la balise <PostalCode> contient le code postal.

L’attribut ID contient l’identifiant de l’adresse ponctuelle contenue dans la table “Adresse” de la base BD ADRESSE® de l’IGN.

L’attribut ID_TR contient l’identifiant de la voie qui porte l’adresse dans la table “Route Adresse” de la base BD ADRESSE® de l’IGN.

L’attribut Qualite dépend du résultat du géocodage :

• Pour un géocodage issu de la table "Route Adresse" (quand l’adresse est interpolée sur la voie), l’attribut Qualite retourne la valeur de l’attribut PREC_PLANI du tronçon de route selon le tableau de correspondance suivant :

• Pour un géocodage issu de la table "Adresse" l’attribut Qualite retourne la valeur de l’attribut TYPE_LOC de l’adresse selon le tableau de correspondance suivant :

La balise <GeocodeMatchCode> contient un indicateur de proximité phonétique et orthographique du nom de l’adresse entre 0 (pas de correspondance) et 1 (exactement identique).

Remarque : En deçà d’une valeur de 0.7, l’appariement effectué ne permet pas d’obtenir une géolocalisation précise de l’adresse, les erreurs d’appariement pouvant entraîner des erreurs de géolocalisation importantes.

L’attribut matchType prend les valeurs suivantes :

• "street number" : géocodage à l’adresse exacte
• "street enhanced" : géocodage à l’adresse avec interpolation de l’adresse entre les bornes de début et de fin du tronçon de la rue
• "street" : géocodage à la rue sans interpolation de de l’adresse
• "city" : géocodage à la commune (pas de correspondance trouvée avec les autres éléments de l’adresse)

Corps du POST :

La balise <Street> contient les informations sur la rue ; la balise <Place> contient le nom de la localité pour la recherche.

<?xml version="1.0" encoding="UTF-8"?>
<XLS
  xmlns:xls="http://www.opengis.net/xls"
  xmlns:gml="http://www.opengis.net/gml"
  xmlns="http://www.opengis.net/xls"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  version="1.2"
  xsi:schemaLocation="http://www.opengis.net/xls http://schemas.opengis.net/ols/1.2/olsAll.xsd">
    <RequestHeader/>
    <Request requestID="1" version="1.2" methodName="LocationUtilityService">
       <GeocodeRequest returnFreeForm="false">
           <Address countryCode="StreetAddress">
               <StreetAddress>
                        <Street>1 rue Marconi</Street>
               </StreetAddress>
               <Place type="Municipality">Metz</Place>
               <PostalCode>57000</PostalCode>
           </Address>
       </GeocodeRequest>
    </Request>
</XLS>

Réponse XML :

Voir ci-dessus pour l’explication des différentes balises.

Exemple de requête avec une adresse avec filtrage géographique lat/long :

<?xml version="1.0" encoding="UTF-8"?>
<XLS
  xmlns:xls="http://www.opengis.net/xls"
  xmlns:gml="http://www.opengis.net/gml"
  xmlns="http://www.opengis.net/xls"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  version="1.2"
  xsi:schemaLocation="http://www.opengis.net/xls http://schemas.opengis.net/ols/1.2/olsAll.xsd">
    <RequestHeader/>
    <Request requestID="1" version="1.2" methodName="LocationUtilityService">
       <GeocodeRequest returnFreeForm="false">
           <Address countryCode="PositionOfInterest">
            <freeFormAddress>Saint-Mandé</freeFormAddress>
              <gml:envelope>
                    <gml:pos>48.80 2.35</gml:pos>
                    <gml:pos>48.86 2.47</gml:pos>
              </gml:envelope>
           </Address>
       </GeocodeRequest>
    </Request>
</XLS>

Exemple de requête avec une adresse avec filtrage attributaire :

<?xml version="1.0" encoding="UTF-8"?>
<XLS
  xmlns:xls="http://www.opengis.net/xls"
  xmlns:gml="http://www.opengis.net/gml"
  xmlns="http://www.opengis.net/xls"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  version="1.2"
  xsi:schemaLocation="http://www.opengis.net/xls http://schemas.opengis.net/ols/1.2/olsAll.xsd">
    <RequestHeader/>
    <Request requestID="1" version="1.2" methodName="LocationUtilityService">
       <GeocodeRequest returnFreeForm="false">
           <Address countryCode="PositionOfInterest">
               <freeFormAddress>Saint-Mandé</freeFormAddress>
               <Place type="Departement">41</Place>
           </Address>
       </GeocodeRequest>
    </Request>
</XLS>

Exemple de requête avec une adresse avec filtrage multi-attributaires:

<?xml version="1.0" encoding="UTF-8"?>
<XLS
  xmlns:xls="http://www.opengis.net/xls"
  xmlns:gml="http://www.opengis.net/gml"
  xmlns="http://www.opengis.net/xls"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  version="1.2"
  xsi:schemaLocation="http://www.opengis.net/xls http://schemas.opengis.net/ols/1.2/olsAll.xsd">
    <RequestHeader/>
    <Request requestID="1" version="1.2" methodName="LocationUtilityService">
       <GeocodeRequest returnFreeForm="false">
           <Address countryCode="PositionOfInterest">
               <freeFormAddress>Saint-Mandé</freeFormAddress>
               <Place type="nature">Lieu-dit habité</Place>
               <Place type="nature">Ruines</Place>
           </Address>
       </GeocodeRequest>
    </Request>
</XLS>

Quand l’attribut countryCode de la balise <Address> d’une requête est égal à "CadastralParcel", il spécifie une recherche par parcelles cadastrales.

La balise <freeFormAddress> contient le numéro de la parcelle à rechercher.

Pour info, la parcelle cadastrale se compose de 14 chiffres ou lettres, indiquant, de gauche à droite :

• le code du département (2 caractères) le code INSEE de la commune (5 chiffres),
• le code commune (3 caractères). (code département + code commune = code INSEE)
• le code commune absorbée INSEE, ou ‘000’ (3 caractères),
• la section (2 caractères),
• le numéro de parcelle (4 caractères).

Exemple d’identifiant de parcelle : ‘940670000D0041’.

Si l’identifiant est incomplet (par exemple ‘940670000D’), le service renverra uniquement les 25 premiers résultats pouvant correspondre.

Pour les villes de Paris et Lyon, le code commune absorbée est remplacé par le code arrondissement : de 101 à 120 pour les 20 arrondissements de Paris, et de 381 à 389 pour les 9 arrondissements de Lyon. On a donc : département (2), code commune (3), code arrondissement (3), section (2), numéro (4).

Exemple de numéro de parcelle dans Paris : ‘75056112CH0020’.

Pour la ville de Marseille, le code commune est remplacé par le code arrondissement (de 201 à 216), et le code commune absorbée est bien présent. On a donc : département (2), arrondissement (3), commune absorbée (3), section (2), numéro (4).

Exemple de numéro de parcelle dans Marseille : ‘132159050K0003’.

Enfin, pour la ville de Toulouse, les codes commune absorbée correspondent aux quartiers de la ville : de 801 à 846.

Exemple de numéro de parcelle dans Toulouse : ‘31555819AB0001’.

<?xml version="1.0" encoding="UTF-8"?>
<XLS
  xmlns:xls="http://www.opengis.net/xls"
  xmlns:gml="http://www.opengis.net/gml"
  xmlns="http://www.opengis.net/xls"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  version="1.2"
  xsi:schemaLocation="http://www.opengis.net/xls http://schemas.opengis.net/ols/1.2/olsAll.xsd">
    <RequestHeader/>
    <Request requestID="1" version="1.2" methodName="LocationUtilityService">
       <GeocodeRequest returnFreeForm="false">
         <Address countryCode="CadastralParcel">
            <freeFormAddress>940670000D0041</freeFormAddress>
         </Address>
       </GeocodeRequest>
    </Request>
</XLS>

La localisation géographique du localisant parcellaire de la parcelle est stockée dans la balise <Point>.

La balise <Address> contient l’ensemble des informations sur la parcelle retournée par le service (code INSEE et nom de la commune, département, commune absorbée, section, numéro, feuille…), contenues dans les balises <Place>.

La balise <Place> associée à l’attribut "Type" fournit l’origine de l’objet parcellaire renvoyé. Le type "Parcelle" indique une réponse issue de la classe "Parcelle" de la BD Parcellaire vecteur (la parcelle a été totalement vectorisée) et le type "Localisant" indique une réponse issue de la classe "Localisant" de la BD Parcellaire vecteur (seul l’emplacement du numéro de la parcelle inscrit sur le plan cadastral papier a été numérisé).

La balise <Street> contient le numéro de la parcelle demandée.

La balise <GeocodeMatchCode> contient un indicateur de pertinence.

Toutes les requêtes précédentes peuvent aussi être passée avec la méthode HTTP GET en mode KVP (Key Value Pair) dans l’URL.

Il suffit d’insérer le corps de la requête XML "URL encodé" à la suite de l’URL du service de géocodage, assigné au paramètre xls, de la manière suivante :

http://wxs.ign.fr/calcul/geoportail/ols?xls=VotreRequeteEncodee

Le corps de la requête XML à encoder est le même que dans le cas d’une requête POST. Vous pouvez vous référer aux parties ci-dessus pour les syntaxes des requêtes des différents types de recherches (par lieux, parcelles cadastrales, recherche inverse...).

Pour encoder votre requête XML, vous pouvez utiliser par exemple la fonction JavaScript encodeURI(), ou encore utiliser un encodeur en ligne (Par exemple celui-ci).

Exemple d’URL GET complète :

http://wxs.ign.fr/calcul/geoportail/ols?xls=%3C%3Fxml%20version%3D%221.0%22%20encoding%3D%22UTF-8%22%3F%3E%3CXLS%20xmlns%3Axls%3D%22http%3A%2F%2Fwww.opengis.net%2Fxls%22%20xmlns%3Agml%3D%22http%3A%2F%2Fwww.opengis.net%2Fgml%22%20xmlns%3D%22http%3A%2F%2Fwww.opengis.net%2Fxls%22%20xmlns%3Axsi%3D%22http%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema-instance%22%20version%3D%221.2%22%20xsi%3AschemaLocation%3D%22http%3A%2F%2Fwww.opengis.net%2Fxls%20http%3A%2F%2Fschemas.opengis.net%2Fols%2F1.2%2FolsAll.xsd%22%3E%3CRequestHeader%2F%3E%3CRequest%20requestID%3D%221%22%20version%3D%221.2%22%20methodName%3D%22LocationUtilityService%22%3E%3CGeocodeRequest%20returnFreeForm%3D%22false%22%3E%3CAddress%20countryCode%3D%22PositionOfInterest%22%3E%3CfreeFormAddress%3Erennes%3C%2FfreeFormAddress%3E%3C%2FAddress%3E%3C%2FGeocodeRequest%3E%3C%2FRequest%3E%3C%2FXLS%3E

De plus, l’ajout du paramètre output avec la valeur ‘json’ à la suite de l’URL indique au service de retourner une réponse XML imbriquée dans une syntaxe JSON :

https://wxs.ign.fr/calcul/geoportail/ols?xls=<?xml(...)>&output=json

La réponse est alors du type :

{
  "https":{
    "status":200,
    "error":null
  },
  "xml" : "<?xml (... ici la réponse du service ...)>"
}

Protocole JSONP:

http://wxs.ign.fr/calcul/geoportail/ols?xls=<?xml(...)>&output=json&callback=fonctionDeTraitementDuResultatJSONP

Exemple de réponse JSONP :

fonctionDeTraitementDuResultatJSONP(
  {
    "http":{
      "status":200,"error":null
    },
    "xml":
      "<?xml version=\"1.0\" encoding=\"UTF-8\"?><XLS version=\"1.2\" xmlns=\"http://www.opengis.net/xls\" xmlns:gml=\"http://www.opengis.net/gml\" xmlns:xls=\"http://www.opengis.net/xls\" xmlns:xlsext=\"http://www.opengis.net/xlsext\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:schemaLocation=\"http://wxs.ign.fr/schemas/olsAll.xsd\"><ResponseHeader/><Response requestID=\"1\" version=\"1.2\"><GeocodeResponse><GeocodeResponseList numberOfGeocodedAddresses=\"1\"><GeocodedAddress><gml:Point><gml:pos>48.113493 -1.675702</gml:pos></gml:Point><Address countryCode=\"PositionOfInterest\"><StreetAddress><Street/></StreetAddress><Place type=\"Municipality\">rennes</Place><Place type=\"Departement\">35</Place><Place type=\"Bbox\">-1.675702;48.113493;-1.675702;48.113493</Place><Place type=\"Commune\">Rennes</Place><Place type=\"Importance\">1</Place><Place type=\"INSEE\">35238</Place><Place type=\"Territoire\">FXX</Place><Place type=\"Nature\">Préfecture de région</Place><PostalCode>35000</PostalCode></Address><GeocodeMatchCode accuracy=\"1.0\" matchType=\"City\"/></GeocodedAddress></GeocodeResponseList></GeocodeResponse></Response></XLS>"
  }
)