Search engines

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 GeoRM protected, the request URL must contain an up-to-date token in order to get a result from the search engine.

Geographical names search :

XML POST Request :

http://wxs.ign.fr/geoportail/gazetteer/OpenLSPOST?gppkey=
  gC2UZGUr_JJi5Nm7QKN5hQG06pEAAAAAAAHWLRe_BD6d4QTVAAABHiB
  QmEAAAAAAAlgAAQECvZr3ME_66sRrEAaAwzQAAEM0AADCtAAAQrQAAA
XML POST body :

The freeFormAddress tag contains the location to search :

<xls:XLS xmlns:xls="http://www.opengis.net/xls" version="1.0">
  <xls:RequestHeader sessionID=""/>
  <xls:Request methodName="GeocodeRequest" version="1.0" requestID="" maximumResponses="50">
    <xls:GeocodeRequest>
      <xls:Address countryCode="FR">
        <xls:freeFormAddress>eifel</xls:freeFormAddress>
      </xls:Address>
    </xls:GeocodeRequest>
  </xls:Request>
</xls:XLS>
XML Response :

The geographical location is stored in the Point tag, while the Place tag holds the found location, the PostalCode tag holds the geographical names' type (See list of types for more informations). The GeocodeMatchCode holds an accuracy number.

<xls:XLS
  xmlns:xls="http://www.opengis.net/xls"
  version="1.000000"
  xmlns:gml="http://www.opengis.net/gml"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.opengis.net/xls LocationUtilityService.xsd">
  <ResponseHeader xmlns="http://www.opengis.net/xls"/>
  <Response xmlns="http://www.opengis.net/xls" requestID="" version="1.0">
    <GeocodeResponse>
      <GeocodeResponseList numberOfGeocodedAddresses="27">
        <GeocodedAddress>
          <Point xmlns="http://www.opengis.net/gml">
            <pos dimension="2">48.858263 2.294243</pos>
          </Point>
          <Address countryCode="BDNYME">
            <StreetAddress>
              <Street></Street>
            </StreetAddress>
            <Place type="Municipality">tour eiffel</Place>
            <PostalCode>Monument</PostalCode>
          </Address>
          <GeocodeMatchCode accuracy="0.904621" matchType="City"/>
        </GeocodedAddress>
        ...
      </GeocodeResponseList>
    </GeocodeResponse>
  </Response>
</xls:XLS>

KVP GET requests :

The POST body is to be encoded in order to pass it into a dedicated parameter xls :

http://wxs.ign.fr/geoportail/gazetteer/OpenLSPOST?gppkey=
  gC2UZGUr_JJi5Nm7QKN5hQG06pEAAAAAAAHWLRe_BD6d4QTVAAABHiB
  QmEAAAAAAAlgAAQECvZr3ME_66sRrEAaAwzQAAEM0AADCtAAAQrQAAA&
xls=%3Cxls%3AXLS%20xmlns%3Axls%3D%22http%3A%2F%2Fwww.opengis.net%2Fxls%22%20version%3D%221.0%22%3E
%3Cxls%3ARequestHeader%20sessionID%3D%22%22%2F%3E
%3Cxls%3ARequest%20methodName%3D%22GeocodeRequest%22%20version%3D%221.0%22%20requestID%3D%22%22%20maximumResponses%3D%2250%22%3E
%3Cxls%3AGeocodeRequest%3E
%3Cxls%3AAddress%20countryCode%3D%22FR%22%3E
%3Cxls%3AfreeFormAddress%3Eeifel
%3C%2Fxls%3AfreeFormAddress%3E%3C%2Fxls%3AAddress%3E
%3C%2Fxls%3AGeocodeRequest%3E
%3C%2Fxls%3ARequest%3E
%3C%2Fxls%3ARequest%3E
%3C%2Fxls%3AXLS%3E&
callback=MyCallBack

The callback parameter is optional (but usefull for JSONP requests).

JSON(P) response :

The response is a JSON string :

MyCallBack && MyCallBack({"http":{"code":200,"url":""},"xml":
"<xls:XLS
  xmlns:xls=\"http://www.opengis.net/xls\"
  version=\"1.000000\"
  xmlns:gml=\"http://www.opengis.net/gml\"
  xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"
  xsi:schemaLocation=\"http://www.opengis.net/xls LocationUtilityService.xsd\">
  <ResponseHeader xmlns=\"http://www.opengis.net/xls\"/>
  <Response xmlns=\"http://www.opengis.net/xls\" requestID=\"\" version=\"1.0\">
    <GeocodeResponse>
      <GeocodeResponseList numberOfGeocodedAddresses=\"27\">
        <GeocodedAddress>
          <Point xmlns=\"http://www.opengis.net/gml\">
            <pos dimension=\"2\">48.858263 2.294243</pos>
          </Point>
          <Address countryCode=\"BDNYME\">
            <StreetAddress>
              <Street></Street>
            </StreetAddress>
            <Place type=\"Municipality\">tour eiffel</Place>
            <PostalCode>Monument</PostalCode>
          </Address>
          <GeocodeMatchCode accuracy=\"0.904621\" matchType=\"City\"/>
        </GeocodedAddress>
        ...
      </GeocodeResponseList>
    </GeocodeResponse>
  </Response>
</xls:XLS>"})

Addresses search :

XML POST Request :

http://wxs.ign.fr/geoportail/ols/OpenLSPOST?gppkey=
  gC2UZGUr_JJi5Nm7QKN5hQG06pEAAAAAAAHWLRe_BD6d4QTVAAABHiB
  QmEAAAAAAAlgAAQECvZr3ME_66sRrEAaAwzQAAEM0AADCtAAAQrQAAA
XML POST body :

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

<xls:XLS xmlns:xls="http://www.opengis.net/xls" version="1.0">
  <xls:RequestHeader sessionID=""/>
  <xls:Request methodName="GeocodeRequest" version="1.0" requestID="" maximumResponses="50">
    <xls:GeocodeRequest>
      <xls:Address countryCode="FR">
        <xls:StreetAddress>
          <xls:Street>73, avenue de paris</xls:Street>
        </xls:StreetAddress>
        <xls:Place type="Municipality">saint mande</xls:Place>
        <xls:PostalCode/>
      </xls:Address>
    </xls:GeocodeRequest>
  </xls:Request>
</xls: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.

<xls:XLS
  xmlns:xls="http://www.opengis.net/xls"
  version="1.000000"
  xmlns:gml="http://www.opengis.net/gml"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.opengis.net/xls LocationUtilityService.xsd">
  <ResponseHeader xmlns="http://www.opengis.net/xls"/>
  <Response xmlns="http://www.opengis.net/xls" requestID="" version="1.0">
    <GeocodeResponse>
      <GeocodeResponseList numberOfGeocodedAddresses="1">
        <GeocodedAddress>
          <Point xmlns="http://www.opengis.net/gml">
            <pos dimension="2">48.845885 2.424274</pos>
          </Point>
          <Address countryCode="FR">
            <StreetAddress>
              <Street>73 AV DE PARIS</Street>
            </StreetAddress>
            <Place type="Municipality">Saint-Mandé</Place>
            <PostalCode>94160</PostalCode>
          </Address>
          <GeocodeMatchCode accuracy="1" matchType="Street number"/>
        </GeocodedAddress>
      </GeocodeResponseList>
    </GeocodeResponse>
  </Response>
</xls:XLS>

KVP GET request :

The overall mechanism is the same as the one explained above for the Geographical names search KVP GET.

New upcoming version of OpenLS 1.2

Geographical names search :

When the countryCode attribute of the Address tag included in the requests equals "PointOfInterest", 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="PointOfInterest">
       <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="1">
                <GeocodedAddress>
                    <gml:Point>
                        <gml:pos>48.111679 -1.681862</gml:pos>
                    </gml:Point>
                    <Address countryCode="PointOfInterest">
                        <StreetAddress>
                            <Street></Street>
                        </StreetAddress>
                        <Place type="Municipality">Rennes</Place>
                        <Place type="IRIS">RENNES;RENNES;ILLE-ET-VILAINE;BRETAGNE</Place>
                        <PostalCode>35238</PostalCode>
                    </Address>
                    <GeocodeMatchCode matchType="City" accuracy="1.0"/>
                </GeocodedAddress>
            </GeocodeResponseList>
        </GeocodeResponse>
    </Response>
</XLS>

Adding a BBOX :

XML POST Request :

XML POST body :
<?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="PointOfInterest">
       <freeFormAddress>rennes</freeFormAddress>
        <gml:pos> -2.494259 48.533782</gml:pos>
        <gml:pos>-1.07059 47.790983</gml:pos>
     </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>48.111679 -1.681862</gml:pos>
                    </gml:Point>
                    <Address countryCode="PointOfInterest">
                        <StreetAddress>
                            <Street></Street>
                        </StreetAddress>
                        <Place type="Municipality">Rennes</Place>
                        <Place type="IRIS">RENNES;RENNES;ILLE-ET-VILAINE;BRETAGNE</Place>
                        <PostalCode>35238</PostalCode>
                    </Address>
                    <GeocodeMatchCode matchType="City" accuracy="1.0"/>
                </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.

XML POST Request :
http://wxs.ign.fr/YOUR_LICENSE/geoportail/ols?
XML POST body :
<?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">
       <freeFormAddress>1 rue Marconi 57000 Metz</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="1">
                <GeocodedAddress>
                    <gml:Point>
                        <gml:pos>49.104565 6.214763</gml:pos>
                    </gml:Point>
                    <Address countryCode="StreetAddress">
                        <StreetAddress>
                            <Building number="1"/>
                            <Street>R MARCONI</Street>
                        </StreetAddress>
                        <Place type="Municipality">Metz</Place>
                        <Place type="IRIS">57463</Place>
                        <PostalCode>57463</PostalCode>
                    </Address>
                    <GeocodeMatchCode matchType="StreetNumber" accuracy="0.9495000000000001"/>
                </GeocodedAddress>
            </GeocodeResponseList>
        </GeocodeResponse>
    </Response>
</XLS>

Structured Addresses search:

XML POST Request :
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.104565 6.214763</gml:pos>
                    </gml:Point>
                    <Address countryCode="StreetAddress">
                        <StreetAddress>
                            <Building number="1"/>
                            <Street>R MARCONI</Street>
                        </StreetAddress>
                        <Place type="Municipality">Metz</Place>
                        <Place type="IRIS">57463</Place>
                        <PostalCode>57463</PostalCode>
                    </Address>
                    <GeocodeMatchCode matchType="StreetNumber" accuracy="0.9495000000000001"/>
                </GeocodedAddress>
            </GeocodeResponseList>
        </GeocodeResponse>
    </Response>
</XLS>

KVP GET requests

All the above URLs also listen to GET requests. The request body must be url encoded in the xsl parameter. Moreover, adding the output parameter with 'json' value still indicates the XML response to be inserted in a JSON encoding. The JSONP protocol is still supported by adding the callback parameter.