Documentation technique de l'API Géoportail

  • FR
  • UK

Accueil / Documentation / Documentation technique

Moteurs de recherche

Recherche par lieux 
Recherche par unités administratives 
Recherche par adresses 
Recherche par parcelles cadastrales 
Recherche inverse 
Requêtes GET KVP 
Le service d'autocomplétion 

Les moteurs de recherche du Géoportail reposent sur le standard OGC "Location Utility Service" (OpenLS). Les requêtes OpenLS peuvent être soit des requêtes POST XML, soit des requêtes KVP GET.

Comme l'accès aux moteurs de recherche est protégé par le contrôle des droits d'accès, l'URL de la requête doit contenir la clef associée au contrat qui autorise l'accès aux ressources du moteur de recherche.

http://wxs.ign.fr/VOTRE_CLEF/geoportail/ols? 

Recherche par lieux

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

Corps de la requête du POST XML :

La balise freeFormAddress contient la localisation à 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="PositionOfInterest">
                <freeFormAddress>rennes</freeFormAddress>
         </Address>
       </GeocodeRequest>
    </Request>
</XLS>

Réponse XML :

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.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<XLS version="1.2" 
  ns4:schemaLocation="http://www.opengis.net/xls http://schemas.opengis.net/ols/1.2/olsAll.xsd" 
  xmlns="http://www.opengis.net/xls" 
  xmlns:ns4="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:xlsext="http://www.opengis.net/xlsext" 
  xmlns:gml="http://www.opengis.net/gml">
    <ResponseHeader/>
    <Response version="1.2" requestID="1">
        <GeocodeResponse>
            <GeocodeResponseList numberOfGeocodedAddresses="2">
                <GeocodedAddress>
                    <gml:Point>
                        <gml:pos>44.194056 0.886431</gml:pos>
                    </gml:Point>
                    <Address countryCode="PositionOfInterest">
                        <StreetAddress>
                            <Street></Street>
                        </StreetAddress>
                        <Place type="Municipality">rennes</Place>
                        <Place type="Departement">47</Place>
                        <Place type="Bbox">0.886431;44.194056;0.886431;44.194056</Place>
                        <Place type="Importance">8</Place>
                        <Place type="Commune">Saint-Maurin</Place>
                        <Place type="Nature">Lieu-dit habité</Place>
                        <Place type="Territoire">FXX</Place>
                        <PostalCode>47270</PostalCode>
                    </Address>
                    <GeocodeMatchCode matchType="City" accuracy="1.0"/>
                </GeocodedAddress>
                <GeocodedAddress>
                    <gml:Point>
                        <gml:pos>47.767373 0.543563</gml:pos>
                    </gml:Point>
                    <Address countryCode="PositionOfInterest">
                        <StreetAddress>
                            <Street></Street>
                        </StreetAddress>
                        <Place type="Municipality">rennes</Place>
                        <Place type="Departement">72</Place>
                        <Place type="Bbox">0.543563;47.767373;0.543563;47.767373</Place>
                        <Place type="Importance">8</Place>
                        <Place type="Commune">Lhomme</Place>
                        <Place type="Nature">Lieu-dit habité</Place>
                        <Place type="Territoire">FXX</Place>
                        <PostalCode>72340</PostalCode>
                    </Address>
                    <GeocodeMatchCode matchType="City" accuracy="1.0"/>
                </GeocodedAddress>
            </GeocodeResponseList>
        </GeocodeResponse>
    </Response>
</XLS>

Recherche par unités administratives

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

Corps de la requête du POST XML :

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>

Réponse XML :

La localisation géographique stockée dans la balise Point correspond à un ponctuel situé sur bâtiment préfectoral 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.

<?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.127320 -1.694190</gml:pos>
          </gml:Point>
          <Address countryCode="Administrativ">
            <StreetAddress>
              <Street/>
            </StreetAddress>
            <Place type="Municipality">Bretagne</Place>
            <Place type="Bbox">-5.141330;47.277990;-1.015770;48.900850</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>

Recherche par adresses

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

Recherche non structurée :

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 countryCode de la balise Address d'une requête sert à spécifier le type de recherche (adresse, lieu-dit, parcellaire). Pour une recherche d'adresse, il doit être égal à "StreetAddress".

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.

Réponse XML :

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 issue 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 :
    Source des donnéesPrécisionTraduction dans l'attribut PREC_PLANI
    Photogrammétrie, plan ou fichier métrique0,5 à 1,5 m1.5
    Levé GPS dynamique, BD TOPO® version antérieure, BD PARCELLAIRE® recalée1,5 à 2,5 m2.5
    Orthophotographie, plan ou fichier non métrique, levé terrain, BDPARCELLAIRE®2,5 à 5 m5
    Carte 1/25000 (SCAN 25® ), calculé, image satellite5 à 10 m10
    BD CARTO® , GEOROUTE®> à 10 m30
  • Pour un géocodage issue de la table "Adresse" l'attribut Qualite retourne la valeur de l’attribut TYPE_LOC de l’adresse selon le tableau de correspondance suivant :
    ValeursDescription
    Plaque adresseIl s'agit d'un ponctuel adresse corespondant à la plaque adresse sur le terrain, ou plus généralement de l'entrée d'une parcelle
    ProjectionLa position de la plaque adresse n'est pas connue. L'adresse est issue d'une projection vers le tronçon routier correspondant à 4,5m de celui-ci(du bon côté), soit à partir du centroïde de la parcelle, soit de toute autre position éloignée de moins de 50m d'un tronçon.
    EntréeLorsqu'il est possible de préciser l'entrée d'un bâtiment dans un ensemble d'immeubles, l'adresse est positionnée à cette entrée. L'attribut TYP_LOC ne sera rempli avec cette valeur que lorsque ces adresses seront réellement positionnées à l'entrée des bâtiments
    Zone d'adressageL'adresse est positionnée sur une zone d'adressage (ZAC, lieu-dit habité, hameau, carrefour nommé, etc.) dont le toponyme figure dans l'adresse.

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 :

  • sreet 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).
    <?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="uid42" version="1.2">
            <GeocodeResponse>
                <GeocodeResponseList numberOfGeocodedAddresses="1">
                    <GeocodedAddress>
                        <gml:Point>
                            <gml:pos>48.843556 2.423248</gml:pos>
                        </gml:Point>
                        <Address countryCode="StreetAddress">
                            <StreetAddress>
                                <Building number="2"/>
                                <Street>av pasteur</Street>
                            </StreetAddress>
                            <Place type="Municipality">Saint-Mandé</Place>
                            <Place type="Qualite">Plaque adresse</Place>
                            <Place type="ID">ADRNIVX_0000000270868421</Place>
                            <Place type="Departement">94</Place>
                            <Place type="Bbox">2.423248;48.843556;2.423248;48.843556</Place>
                            <Place type="Commune">Saint-Mandé</Place>
                            <Place type="INSEE">94067</Place>
                            <Place type="Territoire">FXX</Place>
                            <Place type="ID_TR">TRONROUT0000000004406492</Place>
                            <PostalCode>94160</PostalCode>
                        </Address>
                        <GeocodeMatchCode accuracy="1.0" matchType="Street number"/>
                    </GeocodedAddress>
                </GeocodeResponseList>
            </GeocodeResponse>
        </Response>
    </XLS>

Recherche structurée :

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 :
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<XLS version="1.2" ns4:schemaLocation="http://www.opengis.net/xls http://schemas.opengis.net/ols/1.2/olsAll.xsd" xmlns="http://www.opengis.net/xls" xmlns:ns4="http://www.w3.org/2001/XMLSchema-instance" xmlns:xlsext="http://www.opengis.net/xlsext" xmlns:gml="http://www.opengis.net/gml">
    <ResponseHeader/>
    <Response version="1.2" requestID="1">
        <GeocodeResponse>
            <GeocodeResponseList numberOfGeocodedAddresses="1">
                <GeocodedAddress>
                    <gml:Point>
                        <gml:pos>49.104518 6.214748</gml:pos>
                    </gml:Point>
                    <Address countryCode="StreetAddress">
                        <StreetAddress>
                            <Building number="1"/>
                            <Street>r marconi</Street>
                        </StreetAddress>
                        <Place type="Municipality">Metz</Place>
                        <Place type="Qualite">Tronçon</Place>
                        <Place type="Departement">57</Place>
                        <Place type="Commune">Metz</Place>
                        <Place type="Territoire">FXX</Place>
                        <PostalCode>57000</PostalCode>
                    </Address>
                    <GeocodeMatchCode matchType="StreetNumber" accuracy="1.0"/>
                </GeocodedAddress>
            </GeocodeResponseList>
        </GeocodeResponse>
    </Response>
</XLS>

Ajout d'une BBOX à la recherche par adresses :

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>

Recherche par parcelles cadastrales

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

Corps de la requête du POST XML :

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). (Remarque : 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 de parcelle : '940670000D0041'. Si l'identifiant est incomplet (par exemple '940670000D'), le service renverra uniquement les 25 premiers résultats pouvant correspondre.

Cas particuliers de Paris, Lyon, Marseille et Toulouse :

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>

Réponse XML :

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.

<?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.844489 2.424518</gml:pos>
          </gml:Point>
          <Address countryCode="CadastralParcel">
            <StreetAddress>
              <Street>940670000D0041</Street>
            </StreetAddress>
            <Place type="Municipality">Saint-Mandé</Place>
            <Place type="Numero">0041</Place>
            <Place type="Feuille">1</Place>
            <Place type="Section">0D</Place>
            <Place type="Departement">94</Place>
            <Place type="CommuneAbsorbee">000</Place>
            <Place type="Commune">067</Place>
            <Place type="INSEE">94067</Place>
            <Place type="Type">Parcelle</Place>
          </Address>
          <GeocodeMatchCode accuracy="1.0"/>
        </GeocodedAddress>
      </GeocodeResponseList>
    </GeocodeResponse>
  </Response>
</XLS>

Recherche inverse

Le service de géocodage inverse a pour but de retourner, à partir d'un ou plusieurs points géographiques indiqués en latitude/longitude, la ou les entités géolocalisées les plus proches correspondantes, parmi les adresses, toponymes, parcelles cadastrales, et/ou unités administratives.

Pour cela, il effectue une projection de la position sur les rues environnantes, et renvoie les coordonnées de la projection la plus proche, avec un numéro interpolé calculé à partir des numéros voisins.

Corps de la requête du POST XML

Recherche simple

Le XML suivant est un exemple de requête de Géocodage inverse simple relativement à un point :

<?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:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.opengis.net/xls http://schemas.opengis.net/ols/1.2/olsAll.xsd">
    <RequestHeader/>
    <Request methodName="ReverseGeocodeRequest" maximumResponses="10" requestID="abc" version="1.2">
       <ReverseGeocodeRequest>
          <ReverseGeocodePreference>StreetAddress</ReverseGeocodePreference>
          <Position>
             <gml:Point>
                <gml:pos>48.8033333 2.3241667</gml:pos>
             </gml:Point>
          </Position>
       </ReverseGeocodeRequest>
  </Request>
</XLS>
  • La balise Request contient les paramètres de la requête ; l'attribut maximumResponses permet de limiter le nombre de réponses à une valeur particulière.
  • La balise ReverseGeocodePreference permet de spécifier le type de localisant retourné :
    • StreetAddress : des adresses seront retournées ;
    • PositionOfInterest : des toponymes seront retournées ;
    • CadastralParcel : des parcelles cadastrales seront retournées ;
    • Administratif : des unités administratives (départements et régions) seront retournées ;
    • pour rechercher plusieurs types de localisant à la fois (par exemple adresses et toponymes), il faut utiliser plusieurs occurences de la balise ReverseGeocodePreference, une pour chaque localisant.
  • la balise Position contient les coordonnées (latitude longitude) du point à partir duquel lancer la recherche ;
Recherche avec une contrainte de distance

Le XML suivant est un exemple de requête de Géocodage inverse relativement à un point avec un rayon limite de recherche :

<?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:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.opengis.net/xls http://schemas.opengis.net/ols/1.2/olsAll.xsd">
    <RequestHeader/>
    <Request methodName="ReverseGeocodeRequest" maximumResponses="10" requestID="abc" version="1.2">
       <ReverseGeocodeRequest>
          <ReverseGeocodePreference>StreetAddress</ReverseGeocodePreference>
          <Position>
             <gml:Point>
                <gml:pos>48.8033333 2.3241667</gml:pos>
             </gml:Point>
             <gml:CircleByCenterPoint>
                <gml:pos>48.8033333 2.3241667</gml:pos>
                <gml:radius>150</gml:radius>
             </gml:CircleByCenterPoint>
          </Position>
       </ReverseGeocodeRequest>
  </Request>
</XLS>

La balise gml:CircleByCenterPoint permet de spécifier un cercle à l'intérieur duquel la recherche s'effectuera :

  • la balise gml:pos permet de préciser le centre du cercle ;
  • la balise gml:radius permet de préciser le rayon du cercle ;
Recherche avec une contrainte polygonale

Le XML suivant est un exemple de requête de Géocodage inverse relativement à un point et limitée à un polygone :

<?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:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.opengis.net/xls http://schemas.opengis.net/ols/1.2/olsAll.xsd">
    <RequestHeader/>
    <Request methodName="ReverseGeocodeRequest" maximumResponses="10" requestID="abc" version="1.2">
       <ReverseGeocodeRequest>
          <ReverseGeocodePreference>StreetAddress</ReverseGeocodePreference>
            <Position>
               <gml:Point>
                        <gml:pos>48.8033333 2.3241667</gml:pos>
               </gml:Point>
               <gml:Polygon>
                  <gml:exterior>
                      <gml:LinearRing>
                          <gml:pos>48.8033 2.3241</gml:pos>
                          <gml:pos>48.8033 2.3242</gml:pos>
                          <gml:pos>48.8032 2.3242</gml:pos>
                          <gml:pos>48.8032 2.3241</gml:pos>         
                      </gml:LinearRing>
                  </gml:exterior>
               </gml:Polygon>
            </Position>
       </ReverseGeocodeRequest>
  </Request>
</XLS>

La balise gml:Polygon permet de décrire le contour du polygone (ici, un rectangle).

Réponse du service

La réponse du service est un document XML conforme à la syntaxe définie par le standard OpenLS version 1.2. Ce qui suit est un exemple réponse retournée :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<XLS version="1.2" xsi:schemaLocation="http://gpp3-wxs.ign.fr/schemas/olsAll.xsd" xmlns:xls="http://www.opengis.net/xls" xmlns="http://www.opengis.net/xls" xmlns:xlsext="http://www.opengis.net/xlsext" xmlns:gml="http://www.opengis.net/gml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <ResponseHeader/>
    <Response version="1.2" requestID="abc">
        <ReverseGeocodeResponse>
            <ReverseGeocodedLocation>
                <gml:Point>
                    <gml:pos>48.803159 2.324278</gml:pos>
                </gml:Point>
                <Address countryCode="StreetAddress">
                    <StreetAddress>
                        <Building number="580"/>
                        <Street>av aristide briand</Street>
                    </StreetAddress>
                    <Place type="Municipality">Bagneux</Place>
                    <PostalCode>92220</PostalCode>
                </Address>
                <xlsext:ExtendedGeocodeMatchCode>point adresse</xlsext:ExtendedGeocodeMatchCode>
                <SearchCentreDistance value="23.02"/>
            </ReverseGeocodedLocation>
            (...)
        </ReverseGeocodeResponse>
    </Response>
</XLS>

La balise ReverseGeocodeResponse contient l'ensemble des localisants trouvés :

  • la balise ReverseGeocodedLocation décrit un localisant trouvé :
    • la balise gml:Point contient les coordonnées du localisant ;
    • la balise Address contient les caractéristiques du localisant ; la valeur de l'attribut countryCode indique le type de localisant ("StreetAddress" pour une adresse, "PositionOfInterest" pour un toponyme, "Administratif" pour une unité administrative, "CadastralParcel" pour une parcelle cadastrale) ;
    • la balise SearchCentreDistance indique la distance entre le point de recherche et la géométrie du localisant trouvé.

Requêtes GET KVP

Toutes les URLs précédentes répondent aussi à la méthode GET.

Syntaxe de la requête GET

Il suffit d'insérer le corps de la requête XML 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/VOTRE_CLE/geoportail/ols?xls=YourEncodedRequest

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, etc.).

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

Exemple d'URL GET complète :

    http://wxs.ign.fr/VOTRE_CLE/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

Encapsulation de la réponse XML dans une syntaxe JSON

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 :

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

La réponse est alors du type :

{
  "http":{
    "status":200,
    "error":null
  },
  "xml":"<?xml (...)>"
}

Protocole JSONP

Enfin, l'utilisation du paramètre callback avec comme valeur un nom de fonction permet de mettre en oeuvre le protocole JSONP. Ainsi, la réponse du service (encapsulée en JSON), sera intégrée comme paramètre de l'appel javascript de la fonction spécifiée.

http://wxs.ign.fr/VOTRE_CLE/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>"
  }
)

Le service d'autocomplétion

Le service d'autocomplétion a pour but de suggérer des localisants probables au fur et à mesure de la saisie d'adresses ou de noms de lieux.

http://wxs.ign.fr/VOTRE_LICENCE/ols/apis/completion?

Il est accessible en HTTP / GET. Les requêtes peuvent comprendre les paramètres suivants :

  • text : une chaine de caractères à compléter ;
  • terr : une limitation de la zone de recherche de localisants correspondant à :
    • 'METROPOLE' pour une recherche sur la métropole et la corse ;
    • 'DOMTOM' pour une recherche sur les DOM­ TOMs uniquement ;
    • une liste de codes de départements pour une recherche limitée à ces département spécifiés ;
  • type : le type de localisants recherchés :
    • 'PositionOfInterest' pour une recherche parmi les noms de lieux,
    • 'StreetAddress' pour une recherche parmi des adresses ou les deux valeurs séparées par une virgule pour une recherche parmi les deux types de localisants ;
  • maximumResponses : le nombre maximum de réponses que l'on souhaite voir retournées.

Exemple de requête:

Autocomplétion par adresse :

http://wxs.ign.fr/VOTRE_LICENCE/ols/apis/completion?text=2%2C%20avenue%20pasteur%20saint%20m&type=StreetAddress&maximumResponses=5
Réponse :

La réponse du service est, en cas de succès, au format JSON:

{"status":"OK",
 "results":[{"country":"StreetAddress",
             "city":"Saint-Malo",
             "x":-2.004141,
             "y":48.655722,
             "zipcode":"35400",
             "street":"2 av pasteur",
             "classification":7,
             "kind":"",
             "fulltext":"2 av pasteur,35400 Saint-Malo"},
             ...
           ]
}

où :

  • status : indique le statut de la réponse : 'OK' s'il y a des résultats ; 'ERROR' s'il n'y en a pas ;
  • results : est un tableau contenant les résultats retournés, avec, pour chacun, les champs suivants :
    • country : le type du localisant proposé ('StreetAddress' ou 'PositionOfInterest') ;
    • fulltext : la proposition complète de localisant pour l’autocomplétion ;
    • street : forme décomposée de la proposition, rue ou toponyme ;
    • city : forme décomposée de la proposition, ville ;
    • zipcode : forme décomposée de la proposition : code postal ;
    • classification : classification ;
    • kind : type ;
    • x,y : coordonnées du localisant (en longitude, latitude).

En cas d'erreur du service (code HTTP différent de 200), la réponse est au format JSON. Par exemple :

{"status":"ERROR","results":[]}