Technical documentation of Geoportal API

  • FR
  • UK

Index / Documentation / Technical documentation

Search engines

Geographical names search 
Administrative units search 
Address search 
Cadastral parcels search 
Reverse search 
KVP GET requests 
The autocompletion Service 

The Géoportail's search services rely upon the OGC's Location Utility Service (OpenLS) standard. OpenLS services support both XML POST and KVP GET requests.

As the access to search engines is under web services access rights protection, the request URL must contain an up-to-date token in order to get a result from the search engine.

Geographical names search

When the countryCode attribute of the Address tag included in the requests equals "PositionOfInterest", it specifies a geographical name search.

XML POST Request :

http://wxs.ign.fr/YOUR_LICENSE/geoportail/ols? 
XML POST body :

The freeFormAddress tag contains the location to search :

<?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>
XML Response :

The geographical location is stored in the Point tag, while the Address tag contains the found address, with the Street tag holding the exact address, the Place tag holding the city, the PostalCode tag holding the postal code. The GeocodeMatchCode holds an accuracy number.

<?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>

Administrative units search

When the countryCode attribute of the Address tag included in the requests equals "Administratif", it specifies an administrative units search.

XML POST body :

The freeFormAddress tag contains the department or region name to search :

<?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>

XML Response :

The geographical location stored in the Point tag refers to the prefectural building of the administrative unit.

The Address tag contains the department or region name, geographical extent, administrative center, and INSEE code. The GeocodeMatchCode holds an accuracy number.

<?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>

Address search

Non structured Addresses search :

When the countryCode attribute of the Address tag included in the requests equals "StreetAddress", it specifies an address search. The srsName attribute of the RequestHeader tag specifies the coordinate system in which the adresses of the response will be expressed. This attribute is optional and the default value is "epsg:4326" (WGS84 system used by GPS). The returnFreeForm attribute of the GeocodeRequest tag indicates the structure of the response, false if the user want a structured address (number, street, city and attributes) or an condensed address (number, street and city in a single string). This attribute is optional and the default value is "false". The maximumResponses attribute of the Request tag indicates the maximum number of returned adresses. This attribute is optional and the default value is "25".

XML POST body :
<?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>
XML Response :

The geographical location is stored in the Point tag, while the Address tag contains the found address, with the Street tag holding the exact address, the Place tag holding the city, the PostalCode tag holding the postal code.  The Street tag contains the adresse.
The Place tags contain the attributes of the adress, the name of the attribute is in the Type attribute.  The Municipality attribute contains the city, the PostalCode tag contains the postal code.  The ID attribute contains the identifier of the address point in the "Adresse" table of the BD ADRESSE® database of the IGN.
The ID_TR attribute contains the identifier of the road on which is the adress in the "Route Adresse" table of the BD ADRESSE® database of the IGN.
The Qualite attribute depends on the geocoding result :

  • When the geocoding is derived from the ROUTE ADRESSE® database (the address is interpolated on the road), the Qualite attribute returns the value of the PREC_PLANI attribute of the road section according to the following table of correspondence :\
    Data sourceAccuracyTraduction of the PREC_PLANI attribute
    Photogrammetry, plan or metric file0,5 to 1,5 m1.5
    Dynamic GPS survey, BD TOPO® earlier version, BD PARCELLAIRE® realigned1,5 to 2,5 m2.5
    Orthophotography, plan or non metric file, survey of the territory, BDPARCELLAIRE®2,5 to 5 m5
    Map 1/25000 (SCAN 25® ), calculated, satellite image5 to 10 m10
    BD CARTO® , GEOROUTE®> 10 m30
  • When the geocoding is derived from the "Adresse" table, the Qualite attribute returns the value of the TYPE_LOC attribute of the address according to the following table of correspondence :
    ValuesDescription
    Plaque adresseThis is a point address matching the address field plate, or more generally to the input of a parcel.
    ProjectionThe position of the plate is not known address. The address comes from a projection to the road section, corresponding to 4.5m of this one (on the right side), or from the centroid of the parcel, or in any other position away within 50m of a stretch.
    EntréeWhen it is possible to specify the entrance to a building in a complex of buildings, the address is set to this entry. The TYP_LOC attribute will be filled with this value when these addresses are really positioned at the entrance of buildings.
    Zone d'adressageThe address is set to an address area (populated locality, named crossroads, etc.) whose the toponym appears in the address

The GeocodeMatchCode holds an accuracy number.
The matchType attribute takes the following values :

  • sreet number : The exact address geocoding ;
  • street enhanced : geocoding the address with the address interpolation between the start and end of the section of the street ;
  • street : geocoding the street without interpolation address ;
  • city : geocoding the town (no match found with the other elements of the address).
    ?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>

Structured Addresses search:

XML POST body :

The Street tag contains the street informations, while the Place tag contain the city name for the search.

<?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>
XML Response :
<?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>

Adding a BBOX to the addresses search :

Request example with an address with geographic filtering lat/lon :
<?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>
Request example with an address with attribute filtering:
<?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>
Request example with an address with attribute Multi-attribute filtering:
<?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>

Cadastral parcels search

When the countryCode attribute of the Address tag included in the requests equals "CadastralParcel", it specifies a cadastral parcels search.

XML POST body :

The freeFormAddress tag contains the cadastral parcel number to search.

For information, cadastral parcel number consists of 14 figures and letters, that mean, from left to right :

  • department code (2-digit number)
  • municipality code (3-digit number),
  • absorbed municipality INSEE code, or '000' (3-digit number),
  • section (2 figures or letters),
  • parcel number (4 figures or letters).

    Example : '940670000D0041'. If the number is not complete, only the first 25 matching results will be returned.

Special cases of Paris, Lyon, Marseille and Toulouse :

Concerning Paris and Lyon parcels, the parcel number absorbed municipality code is replaced by the arrondissement code (from 101 to 120 for Paris districts, and from 381 to 389 for Lyon districts). So the parcel number consists in : department (2), municipailty code (3), arrondissement code (3), section (2), number (4).
Example of a Paris cadastral parcel number : 75056112CH0020.

Concerning Marseille, the commune code is replaced by the arrondissement code (from 201 to 216). So the parcel number consists in : department (2), arrondissement code (3), absorbed municipality code (3), section (2), number (4).
Example of a Marseille cadastral parcel number : 132159050K0003.

As for Toulouse, absorbed municipality codes correspond to Toulouse districts : from 801 to 846. Example of a Toulouse cadastral parcel number : 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>

XML Response :

The parcel geographical location is stored in the Point tag.

The Address tag contains information about the matching cadastral parcel (municipality INSEE code and name, department, absorbed municipality, section, number, sheet), in the Place tags.

The Place tag with the "Type" attribute gives information about the origin of the matching cadastral parcel :

  • "Parcelle" means the response comes from the "BDParcellaire vecteur" Parcel class (the parcel geometry was vectorized)
  • "Localisant" means the response comes from the "BDParcellaire vecteur" Location class (only the parcel number location on the paper cadastral plan was vectorized)

    The Street tag holds the searched cadastral parcel number.

    The GeocodeMatchCode holds an accuracy number.

    <?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>

Reverse search

Reverse search aims to provide geographical names, addresses, cadastral parcels, or administrative units, given geographical coordinates.

POST XML body request

basic search

Following XML is a sample of reverse search given a single 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>
  • Request tag holds request parameters ; maximumResponses attribute provides a mean to limit the number of responses.
  • ReverseGeocodePreference tag holds the type of the geographical location searched :
    • StreetAddress : addresses are returned ;
    • PositionOfInterest : geographical names are returned ;
    • CadastralParcel : cadastral parcels are returned ;
    • Administratif : administrative units (departments and regions) are returned ;
    • in order to have several types returned (for instance address geographical names), use several ReverseGeocodePreference tags, one for each type.
  • Position tag holds coordinates from where to search.
reverse search with a distance limit

following XML is a sample of request limited to a certain circle :

<?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>

gml:CircleByCenterPoint tag holds information about the circle that limits the search :

  • gml:pos tag holds the coordinates of the center of the circle ;
  • gml:radius tag holds the radius of the circle.
Reverse search whith a polygonal constraint

Following XML is a sample of a reverse search request limited to a polygon area :

<?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>

gml:Polygon tag holds the description of the polygon limits (here a rectangle).

Service response

Service response is an XML document that satisfies OpenLS standard release 1.2 syntax. For exemple :

<?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>

ReverseGeocodeResponse tag holds all geographical names or addresses found :

  • ReverseGeocodedLocation tag describes on geographical name or address
    • gml:Point tag holds coordinates of the geographical place ;
    • Address tag holds the description of the geographical place ; the value of countryCode attribute gives the type of the place ("StreetAddress" : address or "PositionOfInterest" : geographical name, "Administratif" : administrative unit, "CadastralParcel" : cadastral parcel)
    • SearchCentreDistance tag holds the distance between searc point and the place returned.

KVP GET requests

All the above URLs also listen to GET requests.

GET requests syntax

In order to do so, the encoded XML request body has to be added to the service URL, in the xls parameter, as follows :

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

The XML request body to be encoded is exactly the same as in case of a POST request. You can refer to the above explanations concerning XML request bodies for different kind of search (Geographical names, cadastral parcels, reverse search).

To encode your XML request, encodeURI() JavaScript function can be used, as well as an online encoder.

Full GET URL example :

    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

XML response integration in a JSON syntax

Moreover, adding the output parameter with 'json' value indicates the XML response to be inserted in a JSON encoding :

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

The response syntax will be as follows :

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

JSONP protocol

Finally, JSONP protocol is also supported. It can be implemented by adding the callback parameter, that holds a function name as value. In this way, the response (integrated in a JSON syntax) will be inserted as a parameter of the specified function javascript call.

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

JSONP response example :

JSONPResultProcessFunction(
  {
    "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>"
  }
)

The autocompletion Service

This service's goal is to suggest probable locations as entering addresses or place names.

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

It is accessible by HTTP / GET. Requests can include the following parameters:

  • text : a string to complete ;
  • terr :a limitation of the of locations corresponding to :
    • 'METROPOLE' for research on the mainland and Corsica ;
    • 'DOMTOM' for research only on DOM-TOMs ;
    • a list of departments codes or towns INSEE codes for a limited research over these departments of specified towns;
  • type : type of locations sougtht :
    • 'PositionOfInterest' for a research among place names ;
    • 'StreetAddress' for a research among adresses or two value separated with a comma for a research among both types of locations ;
  • maximumResponses : the maximum number of responses you want to see returned ;

Request example:

Autocompletion by address :

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

The service response is, if successful, in JSON format:

{"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"},
             ...
           ]
}

where :

  • status : indicates the status of the answer: 'OK' if there is a resullt; ERROR if there isn't ;
  • results : is a table containing the results returned, with for each the following fields: :
    • country : the location's type proposed ('StreetAddress' or 'PositionOfInterest') ;
    • fulltext : the location's complete proposal for the autocompletion ;
    • street : decomposed form of the proposal, street or place name ;
    • city : decomposed form of the proposal, city ;
    • zipcode : decomposed form of the proposal, postal code ;
    • classification : classification ;
    • kind : type ;
    • x,y : the location's coordinates (longitude, latitude).

If the service returns an error (HTTP code different from 200), the response is in JSON format. For example:

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