Technical documentation of Geoportal API

  • FR
  • UK

Index / Documentation / Technical documentation

API keys and web services access rights.

This page deals with geographic rights management on the geoportal plateform and acces keys.

Principle 
Keys 
Autoconfiguration 
Autoconfiguration locally 

Principle

Each request to servers is sent with an access key which use a specific authentication process (see next section). A key is represented by an 24 characters long alpha-numeric string.

A key grants access to a set of services. These services can be reached using URL that match the following pattern :

http(s)://wxs.ign.fr/context/service

Key must be inserted in the URL, between the domain name and the service path. Here is the result :

http(s)://wxs.ign.fr/KEY/context/service

There may be up to 3 different contexts for each service :

  • geoportail : datasets/services operated by the Geoportal infrastructure under IGN terms and conditions;
  • inspire : INSPIRE compliant datasets/services operated by the Geoportal infrastructure under INSPIRE terms and conditions;
  • edugeo : data for Ministry of Education operated by the Geoportal infrastructure under specific conditions.

    URL examples :

    http://wxs.ign.fr/KEY/geoportail/wms
    http://wxs.ign.fr/KEY/inspire/wfs

Keys

Getting a key

Keyscan be obtained on two sites :

1. http://api.ign.fr for development keys

2. http://professionnels.ign.fr for exploitation keys

development keys are meant for testing purpose :

1. user check if the geoportal platform fits to his needs. Thus, development keys have short term validity and a limited number of resources available but all kinds of services and key types can be tested.

2. when the use of the geoportal platform has been made, user may then get exploitation keys on professionnels.ign.fr site even for development or qualification platforms. Indeed, such environments are meant have long terms duration and may need to access particular resources.

exploitation keys allows access to all platform resources accordingly to terms of service that fit the use. The duration of the key, and the number of ressources used can be modified by the user himself directly on the professionels.ign.fr web site. Furthermore, individual statistics of the key usage can be consulted on this same site.

Kind of keys

Several kind of keys are delivered :

  • Keys based on Referer/IP/User-Agent : authentication is made against one or more of these 3 criteria. Some keys authenticate only against the Referer header contained in HTTP requests' headers. Some other keys authenticate against both IP addresses and User-Agent HTTP requests' header. Any combination of Referer, IP and User-Agent can be used to authenticate a key;
    • referer based security : the referer is a header of the http request sent to the service. It is filled by browser with the URL of the page being visited. With a referer secured key, the request will be accepted only if the referer value is a subdomain of the URL that has been declared when the key was created. This kind of security is thus meant to Web based application.
    • IP based security : with such a key, the request will be accepted only if the IP address from which it comes is part of the IPs list that has been declared when the key was created. This kind of security is aimed for applications deployed for an limited number of client machines (inside an intranet for instance).
    • User-Agent based security : the User-Agent is a header of the http request sent to the service. Applications generaly use it to identify themselves (name, release number, ...). With a User-Agent secured key, the request will be accepted only if the user-agent value iequals the value that has been declared when the key was created. This kind of security is thus meant to desktop or mobile applications that can build themselves the value of their User-Agent.
  • Key based on login/password : authentication is made using HTTP Basic authentication. The login and password are encrypted in the Authorization header of HTTP requests. In order to use this type of key, the developer needs to know the login/password associated with this key. It is recommanded to use the HTTPS protocol for such a key type. This kind of security is meant to applications such as SIGs that can deals with HTTP Basic Authentification.

    If authentication fails, a HTTP 403 error will be returned by web services. A HTTP 401 error may be returned when using a login/password key without specifying the Authorization header. The web browser will display a popup window asking for login and password.

Available web services

Below is a sample list of Geoportal web services under web services access rights protection :

  • WMS version 1.3.0
  • WFS version 2.0.0
  • WMTS version 1.0.0
  • OpenLS version 1.2.0
  • CSW ISO API version 2.0.2
  • Altimetric service (REST or WPS APIs)
  • Tiled vector (KML)
  • KML/Collada (3D objects)

Available resources - APIs autoconfiguration

This service is known as "auto-configuration service". Given one or more contracts keys, it will give access to information such as :

  • parameters for default visualisation in a web page (dimensions, territories, layers to display, ...) ;
  • technical parameters for geoportal services ( WMTS TileMatrixSets, resolutions lists, territories configuration, bounding boxes, ...) ;
  • available resources (layers) and information about them (url, bounding boxes, scales, ...).

Service access

One may invoke the service that way :

http://wxs.ign.fr/KEY/autoconf/?keys=KEY,KEY2,...

where KEY, KEY2, ... are the contract keys. If no key is given, the description of the whole geoportal resources will be returned.

Service response

Service response is an XML document which inherits from Web Map Context OGC standard. This document consists of a root tag <ViewContext> which contains two main parts. The first declares general parameters for all platform services (tag <General>) and the second handles specific resources authorised for the key (tag <LayerList>).

  • Tag <General>

    This tag gives information about :

    • French territories description (tag <gpp:Territories>). Especially their name, identifiers, supported SRS, bounding boxes, min and max scales, center for visualisation and default layers for each territories. For instance :
      <gpp:Territories>
          <gpp:Territory default="1" id="FXX" name="FXX">
          <gpp:defaultCRS>EPSG:3857</gpp:defaultCRS>
          <gpp:AdditionalCRS>CRS:84</gpp:AdditionalCRS>
          <gpp:AdditionalCRS>IGNF:RGF93G</gpp:AdditionalCRS>
          <gpp:AdditionalCRS>EPSG:4171</gpp:AdditionalCRS>
          <gpp:AdditionalCRS>IGNF:LAMB93</gpp:AdditionalCRS>
          <gpp:AdditionalCRS>EPSG:2154</gpp:AdditionalCRS>
          <gpp:AdditionalCRS>IGNF:LAMBE</gpp:AdditionalCRS>
          <gpp:AdditionalCRS>EPSG:27582</gpp:AdditionalCRS>
          <gpp:AdditionalCRS>EPSG:27572</gpp:AdditionalCRS>
          <gpp:BoundingBox>-31.17,27.33,69.03,80.83</gpp:BoundingBox>
          <sld:MinScaleDenominator>533</sld:MinScaleDenominator>
          <sld:MaxScaleDenominator>128209039</sld:MaxScaleDenominator>
          <gpp:Resolution>2445.984905</gpp:Resolution>
          <gpp:Center>
            <gpp:x>2.345274398</gpp:x>
            <gpp:y>48.860832558</gpp:y>
          </gpp:Center>
          <gpp:DefaultLayers>
            <gpp:DefaultLayer layerId="ORTHOIMAGERY.ORTHOPHOTOS$GEOPORTAIL:OGC:WMTS"/>
            <gpp:DefaultLayer layerId="GEOGRAPHICALGRIDSYSTEMS.MAPS$GEOPORTAIL:OGC:WMTS"/>
            <gpp:DefaultLayer layerId="CADASTRALPARCELS.PARCELS$GEOPORTAIL:OGC:WMTS"/>
            <gpp:DefaultLayer layerId="ELEVATION.ELEVATIONGRIDCOVERAGE$GEOPORTAIL:OGC:WMTS"/>
            <gpp:DefaultLayer layerId="ORTHOIMAGERY.ORTHOPHOTOS.3D$GEOPORTAIL:OGC:WMTS@aggregate"/>
          </gpp:DefaultLayers>
        </gpp:Territory>
      ...
      <gpp:Territories>
    • matrix levels for WMTS service (tag <gpp:TileMatrixSets>). Cf. the page dealing with that subject). For a given pyramid (tag <wmts:TileMatrixSet>), each level is detailed (tag <wmts:TileMatrix>) with identifier (the level), the corresponding scale denominator, grid origin positionning and its width and height given in tiles number. For instance :
      <gpp:TileMatrixSets>
          <wmts:TileMatrixSet>
              <ows:Identifier>PM</ows:Identifier>
              <ows:SupportedCRS>EPSG:3857</ows:SupportedCRS>
               <wmts:TileMatrix>
                  <ows:Identifier>0</ows:Identifier>
                  <wmts:ScaleDenominator>559082264.0287178958533332</wmts:ScaleDenominator>
                  <wmts:TopLeftCorner>-20037508 20037508</wmts:TopLeftCorner>
                  <wmts:TileWidth>256</wmts:TileWidth>
                  <wmts:TileHeight>256</wmts:TileHeight>
                  <wmts:MatrixWidth>1</wmts:MatrixWidth>
                  <wmts:MatrixHeight>1</wmts:MatrixHeight>
              </wmts:TileMatrix>
              <wmts:TileMatrix>
                  <ows:Identifier>1</ows:Identifier>
                  <wmts:ScaleDenominator>279541132.0143588959472254</wmts:ScaleDenominator>
                  <wmts:TopLeftCorner>-20037508 20037508</wmts:TopLeftCorner>
                  <wmts:TileWidth>256</wmts:TileWidth>
                  <wmts:TileHeight>256</wmts:TileHeight>
                  <wmts:MatrixWidth>2</wmts:MatrixWidth>
                  <wmts:MatrixHeight>2</wmts:MatrixHeight>
              </wmts:TileMatrix>
              ...
          </wmts:TileMatrixSet>
          ...
      </gpp:TileMatrixSets>
    • resolutions for each scale level expressed in Pseudo Mercator SRS (tag <gpp:Resolutions>).
    • few services description (tag <gpp:Services>). This tag will be deprecated : the information it gives can be found in tags relatives to each ressource available.
  • Tag <LayerList>

    This tag enumerates all resources available for the key given as parameter. Each resource is described with a <Layer> tag. Given the kind of resource described, its content may change.

    • WMTS resources (Layer) :

      A resource of that kind is a WMTS service layer.

      <Name> tag holds the layer name used in service GetTile requests ;

      <FormatList> tag lists the available formats for that layer ;

      <StyleList> tag lists the available styles for that laye r ;

      <gpp:Originators> tag contains informations about organisms that originates the data at particular scales or locations expressed by bounding boxes ;

      <gpp:Legends> tags holds links to legends files for the layer for particular scales ;

      <wmts:TileMatrixSetLink> tag holds specific limitations in the originel TileMatrixSet ;

      <gpp:MetadataURL> tag holds links to metadata files describing data used to build the layer ;

      <gpp:Keys> tag holds URL to the service with the key used to invoque the autoconfiguration service.

      This <Layer> tag is an example for a WMTS resource :

      <Layer hidden="0" queryable="0">
          <Server service="OGC:WMTS" title="Photographies aériennes" version="1.0.0">
          <OnlineResource xlink:href="http://wxs.ign.fr/geoportail/wmts" xlink:type="simple"/></Server>
          <Name>ORTHOIMAGERY.ORTHOPHOTOS</Name>
          <Title>Photographies aériennes</Title><Abstract>Photographies aériennes</Abstract>
          <sld:MinScaleDenominator>1067</sld:MinScaleDenominator>
          <sld:MaxScaleDenominator>559082265</sld:MaxScaleDenominator>
          <FormatList><Format current="1">image/jpeg</Format></FormatList>
          <StyleList><Style current="1"><Name>normal</Name><Title>Données Brutes</Title></Style></StyleList>
          <DimensionList>
              <Dimension name="Type" unitSymbol="" units="" userValue="">2D</Dimension>
              <Dimension name="VisibilityRange" unitSymbol="" units="" userValue="">0.2985821417389697,117407.27544603075,156543.033928041</Dimension>
              <Dimension name="VisibilityMode" unitSymbol="" units="" userValue="">resolution</Dimension>
              <Dimension name="NoDataValue" unitSymbol="" units="" userValue="">FFFFFF</Dimension>
          </DimensionList>
          <Extension>
              <gpp:Layer id="ORTHOIMAGERY.ORTHOPHOTOS$GEOPORTAIL:OGC:WMTS" order="9990000">
                  <gpp:Thematics><gpp:Thematic>Photographies</gpp:Thematic></gpp:Thematics>
                  <gpp:InspireThematics><gpp:InspireThematic>Ortho-imagerie</gpp:InspireThematic></gpp:InspireThematics>
                  <gpp:BoundingBox maxT="2013-07-25" minT="1997-07-08">-178.18713,-84.0,178.0,84.0</gpp:BoundingBox>
                  <gpp:Originators>
                      <gpp:Originator name="IGN">
                          <gpp:Attribution>Institut national de l'information géographique et forestière</gpp:Attribution>
                          <gpp:Logo>http://wxs.ign.fr/static/logos/IGN/IGN.gif</gpp:Logo>
                          <gpp:URL>http://www.ign.fr</gpp:URL>
                          <gpp:Constraints>
                              <gpp:Constraint>
                                  <gpp:CRS>EPSG:4326</gpp:CRS>
                                  <gpp:BoundingBox maxT="2013-07-25" minT="1997-07-08">-178.18713,-21.401329,55.85611,51.090965</gpp:BoundingBox>
                                  <sld:MinScaleDenominator>2133</sld:MinScaleDenominator>
                                  <sld:MaxScaleDenominator>2133</sld:MaxScaleDenominator>
                              </gpp:Constraint>
                              ...
                          </gpp:Constraints>
                       </gpp:Originator>
                       ...
                   </gpp:Originators>
                   <gpp:Legends>
                       <gpp:Legend>
                           <sld:MinScaleDenominator>2133</sld:MinScaleDenominator>
                           <gpp:LegendURL format="format"><OnlineResource xlink:href="http://wxs.ign.fr/static/legends/NOLEGEND.JPG" xlink:type="simple"/></gpp:LegendURL>
                       </gpp:Legend>
                       ...
                   </gpp:Legends>
                   <gpp:QuickLook><OnlineResource xlink:href="http://wxs.ign.fr/static/pictures/ign_ortho.jpg" xlink:type="simple"/></gpp:QuickLook>
                   <wmts:TileMatrixSetLink>
                       <wmts:TileMatrixSet>PM</wmts:TileMatrixSet>
                       <wmts:TileMatrixSetLimits>
                           <wmts:TileMatrixLimits>
                               <wmts:TileMatrix>10</wmts:TileMatrix>
                               <wmts:MinTileRow>31</wmts:MinTileRow>
                               <wmts:MaxTileRow>992</wmts:MaxTileRow>
                               <wmts:MinTileCol>5</wmts:MinTileCol>
                               <wmts:MaxTileCol>1018</wmts:MaxTileCol>
                           </wmts:TileMatrixLimits>
                           ....
                       </wmts:TileMatrixSetLimits>
                   </wmts:TileMatrixSetLink>
                   <gpp:MetadataURL format="xml"><OnlineResource xlink:href="http://wxs.ign.fr/geoportail/csw?service=CSW&version=2.0.2&request=GetRecordById&Id=IGNF_BDORTHOr_2-0.xml" xlink:type="simple"/></gpp:MetadataURL>
                   ....
                   <gpp:Keys>
                       <gpp:Key id="KEY">http://wxs.ign.fr/KEY/geoportail/wmts</gpp:Key>
                   </gpp:Keys>
              </gpp:Layer>
          </Extension>
      </Layer>
    • OpenLS resources (direct or reverse geocoding) or autocompletion :

      Geocoding acces rights depend on the kind of data that are geocoded (PositionOfInterest, StreetAddress, CadastralParcels). For each kind of data, there will be one <Layer> tag for direct geocoding, another for reverse geocoding and a third for autocompletion service. For those three tags, the content has the same meaning.

      <Layer> tag example :

      <Layer hidden="0" queryable="0">
          <Server service="OGC:OPENLS;ReverseGeocode" title="Géocodage inverse par lieux" version="1.2"><OnlineResource xlink:href="http://wxs.ign.fr/geoportail/gazetteer" xlink:type="simple"/></Server>
          <Name>PositionOfInterest</Name>
          <Title>Dénominations géographiques</Title>
          <Abstract>Noms de zones, de régions, de localités, de grandes villes, de banlieues, de villes moyennes ou d'implantations, ou tout autre élément géographique ou topographique d'intérêt public ou historique.</Abstract>
          <Extension>
              <gpp:Layer id="PositionOfInterest$GEOPORTAIL:OGC:OPENLS" visibleInCatalog="0">
                  <gpp:Thematics><gpp:Thematic>Toponymes</gpp:Thematic></gpp:Thematics><gpp:InspireThematics><gpp:InspireThematic>Dénominations géographiques</gpp:InspireThematic></gpp:InspireThematics>
                  <gpp:Keys>
                      <gpp:Key id="KEY">http://wxs.ign.fr/KEY/geoportail/gazetteer</gpp:Key>
                  </gpp:Keys>
              </gpp:Layer>
          </Extension>
      </Layer>

Service use

All IGN's web APIs make use of this service to configure web map applications transparently for the web developer.

Caching autoconfiguration result

autoconfiguration response has a non negligeable weight that growths with the number of available resources. The loading time of a page using the Geoportal API may thus be extended disgracefully.

A workaround for that issue is to access autoconf response that has been saved locally. Thus the initialisation will be made directly from the server that holds the web page without having to deals with IGN servers.

This can be made in two steps :

1. Putting the service response locally

Geoportal Javascript API interacts with the service throw JSONP protocol. One have thus to have the file in the corresponding format. If KEY is the contract key, the file will be fetched through the following URL :

http://wxs.ign.fr/KEY/autoconf?output=json&callback=OpenLayers.Protocol.Script.registry.regId1

2. Telling the API to get response locally

If the file that has been fetched has been saved in a location such as path/to/autoconf.js then we tell the Geoportal Javascript API to use that file that way :

  • Using the Loader.

    Path to autoconf file is given throw "geormUrl" property in the fifth parameter of Geoportal.load() function :

           iv= Geoportal.load(
                // div's ID:
                'viewerDiv',
                // API's keys:
                [KEY],
                {// map's center :
                    // longitude:
                    lon:2.731525,
                    // latitude:
                    lat:45.833333
                },
                10,
                {
                  ...
                  geormUrl:'path/to/autoconf.js',
                  ...
                }
            );
  • Without the loader.

    Path to the autoconf result file is given as the third parameter of function Geoportal.GeoRMHandler.getConfig() :

        Geoportal.GeoRMHandler.getConfig(
            [KEY], 
            null,
            'path/to/autoconf.js', 
            {
              onContractsComplete: initMap
            }
        );
  • NB :

    1. Path to autoconf result file is relative to the place of the html page (like other resources files it includes).

    2. If the rights to the keys are modified (adding or removing resources), the operation has to be renewed in order to take those new rights to be taken into account.