Documentation technique de l'API Géoportail

  • FR
  • UK

Accueil / Documentation / Documentation technique

Clef API et droits d'accès aux services Web.

Cette page traite du mode de sécurisation de la plateforme Géoportail au travers des clefs d'accès.

Principe 
Clefs 
Autoconfiguration 
Autoconfiguration en local 

Principe

Chaque requête aux serveurs nécessite une clef d'accès qui dispose d'un mode d'authentification propre. Une clef d'accès est représentée par une chaîne unique de 24 caractères alpha-numériques.

Une clef donne accès à des services accessibles via des URL du type :

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

Il faut insérer la clef entre le nom du domaine et le chemin au service, ainsi on obtient :

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

Il peut exister jusqu'à 3 contextes différents pour la plupart des services :

  • geoportail : les données/services fournis par l'infrastructure Géoportail sous condition d'utilisation IGN;
  • inspire : les données/services dans le cadre INSPIRE fournis par l'infrastructure Géoportail sous condition d'utilisation INSPIRE;
  • edugeo : les données/services pour l'Education Nationale fournis par l'infrastructure Géoportail sous condition d'utilisation spécifique.

    Exemples d'URL :

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

Clefs

Obtention d'une clef

Deux sites permettent d’obtenir des clefs d’accès à la plateforme Géoportail :

1. le site api.ign.fr qui délivre des clefs de développement

2. le site professionnels.ign.fr qui délivre des clefs d’exploitation

Les clefs délivrées par le site api.ign.fr sont des clefs dites “de développement” pour une utilisation en mode "bac à sable". A savoir :

1. l'utilisateur vérifie qu'il peut réaliser son projet avec les services de la plateforme Géoportail à l'aide de ces clefs. Ce temps de vérification est limité dans la durée et ne nécessite pas un accès à toutes les ressources disponibles. Par contre, il permet un accès à tous les types de clefs (web, sig, mobile et web3D) et de ressources (OpenLS, WMTS, WFS, WMS et Altimétrie).

2. Lorsqu'il se lance dans la réalisation de son projet, il passe sur des clefs du site professionnels.ign.fr même pour sa plateforme de développement, de recette, de qualification ou autre environnement de ce genre. En effet, il s’agit d’environnements destinés à perdurer le temps du projet et pour lesquels l’accès à des ressources particulières peut-être nécessaire.

Les clefs délivrées par le site professionnels.ign.fr permettent un accès à toutes les ressources de la plateforme Géoportail auquelles les licences d’exploitation donnent accès. Le site professionnels.ign.fr permet au détenteur de la clef de gérer lui même la durée de son contrat, d’accéder aux statistiques d’utilisation des différentes ressources de sa clef et gérer le nombre de ressources.

Types de clefs

Il existe plusieurs types de clefs :

  • Les clefs referer/IP/User-Agent sont authentifiées auprès des serveurs à partir d'un ou plusieurs de ces trois critères. Certaines clefs ont une sécurité qui porte uniquement sur le Referer, d'autres plus restrictives ont une sécurité qui porte à la fois sur l'IP et le User-Agent de la requête entrante. Toutes les combinaisons sont possibles. Ces paramètres sont lus à partir des informations obtenues par la requête entrante;
    • Sécurisation par referer : Le Referer est la valeur de l'entête HTTP "referer" véhiculée dans les requêtes HTTP émises par les navigateurs. Cette valeur est l'URL de la page consultée émettrice de la requêtes. Si la clef comprend une sécurisation par referer alors la plateforme Géoportail va vérifier que la valeur de l'entête "referer" est un sous-domaine de l'URL déclarée lors de la création de la clef. La sécurisation par referer est donc préconisée pour les accès à la plateforme via une application WEB.
    • Sécurisation par IP ou plage d'IPs : Lorsque la clef est sécurisée selon ce mode, la plateforme Géoportail va vérifier que la requête est émise par unes des adresses IPs déclérées lors de création de la clef. Cet type de sécurisation est destiné à des applications tournant sur un nombre limité de poste (par exemple pour un intranet).
    • Sécurisation par User-Agent : Le user-Agent est la valeur de l'entête HTTP "User-Agent" véhiculée dans les requêtes HTTP émises par diverses applications (dont les navigateurs). Cette valeur permet d'identifier l'application émettrice de la requête (notamment, nom, numéro de version,... ). Si la clef comprend une sécurisation par User-Agent alors la plateforme Géoportail va vérifier que la valeur de l'entête "User-Agent" correspond à celle déclarée lors de la création de la clef. La sécurisation par User-Agent est préconisée pour les accès à la plateforme via des applications lourdes ou mobiles, capables de forger elles-même leur entête User-Agent.
  • Les clefs login/password sont authentifiées par le protocole HTTP AuthBasic qui consiste à envoyer dans un en-tête d'authentification l'identifiant et le mot de passe cryptés de l'utilisateur. Pour utiliser ce type de clef et accéder aux services, il est nécessaire d'être en possession de l'identifiant/mot de passe associé à la clef. Il est recommandé d'utiliser le protocole HTTPS pour ce type de clef. La sécurisation par Login/password est préconisée pour les accès à la plateforme via des applications de type SIG.

    En cas d'erreur d'authentification, une erreur HTTP 403 est retournée. Une erreur 401 peut-être retournée lorsque il s'agit d'une clef login/password et que l'en-tête d'authentification est absent. Dans ce cas, le navigateur affiche une fenêtre permettant la saisie de ces informations.

Services disponibles

Ci-dessous une liste non exhaustive des services du Géoportail protégés par le droits d'accès aux services :

  • WMS en version 1.3.0
  • WFS en version 2.0.0
  • WMTS en version 1.0.0
  • OpenLS en version 1.2.0
  • CSW ISO API en version 2.0.2
  • Service Altimétrique (interface REST ou WPS)
  • Vecteurs tuilés (KML)
  • KML/Collada (diffusion d'objets 3D)

Ressources disponibles pour une ou plusieurs clefs - autoconfiguration des APIs

L'infrastructure du Geoportail propose un service, dit d'auto-configuration qui, pour une ou plusieurs clefs données, retourne des informations telles que :

  • les paramètres permettant de configurer une visualisation web par défaut (taille, territoire, couches à afficher) ;
  • les paramètres techniques (configuration des services WMTS : TileMatrixSets, listes des résolutions, configuration des territoires : emprise, centre de visualisation, ...) ;
  • la liste des ressources (couches) disponibles et les informations permettant d'y accéder (url, emprises, echelles d'affichage, ...).

Accès au service

On accède au service via une URL de ce type :

http://wxs.ign.fr/CLEF/autoconf/?keys=CLEF,CLEF2,...

où CLEF, CLEF2, ... sont des clefs de contrat API. Si aucune clef n'est spécifiée, la description de toutes les ressources exposées par l'infrastructure Géoportail est retournée.

Réponse du service

La réponse du service est un fichier XML dont la structure hérite du standard OGC Web Map Context. Ce fichier est donc constitué d'une balise principale <ViewContext> qui comprend deux grandes parties. Une comprenant des paramètres communs à tous les services de la plateforme (balise <General>) et une autre consacrée aux ressources accessibles à l'aide d'une clef (balise <LayerList>).

  • La balise <General>

    On trouvera dans cette balise des informations sur :

    • la définition des territoires français couverts par la plateforme Géoportail (balise <gpp:Territories>). Notamment, leurs noms, identifiants, les SRS supportés, leurs emprises géographiques, les échelles min et max de visualisation sur ces territoires, les centres pour la visualisation (qui ne sont pas forcément des centroïdes) et les couches d'affichage par défaut pour ces territoires. Ex. :
      <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>
    • la définition des niveaux d'échelle pour le WMTS (balise <gpp:TileMatrixSets>) qui permet de définir les pyramides des caches WMTS (cf. la page sur le sujet). Ainsi, pour une pyramide donnée (balise <wmts:TileMatrixSet>), chaque niveau est détaillé (balise <wmts:TileMatrix>) avec son identifiant (le niveau), son dénominateur d'échelle correspondant, le positionnement de l'origine de la grille et le nombre de tuiles en largeur et hauteur pour la grille. Exemple :
      <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>
    • les résolutions correspondantes à chaque niveau d'échelle dans le système natif Pseudo Mercator (balise <gpp:Resolutions>).
    • la description de certains services de la plateforme (balise <gpp:Services>). Cette balise fournit les URLs "absolues" (à savoir sans clefs) de certains services tels que le Géocodage et l'autocompletion. Cette balise sera bientôt dépréciée. La récupération de l'URL des services doit se faire à l'aide des balises relatives aux resources autorisées qui comprennent la clef avec laquelle l'interrogation su service d'autoconfiguration a été faite.
  • La balise <LayerList>

    Cette balise décrit les ressources accessibles à l'aide de la clef fournie. Chaque ressource est décrite par une balise <Layer>. Selon le type de ressource, le contenu peut changer.

    • Resource de type WMTS (Couche) :

      Il s'agit d'une couche du service WMTS de la plateforme Géoportail.

      La balise <Name> contient le nom de la couche au sens du service ;

      la balise <FormatList> permet de préciser les différents formats d'image dans lesquels la couche est accessible ;

      la balise <StyleList> décrit les valeurs possibles pour le paramètre Style d'uen requête GetTile ;

      la balise <gpp:Originators> permet de préciser les informations relatives aux organismes originaires des données servies en fonction de l'échelle et de l'emprise d'affichage ;

      la balise <gpp:Legends> fournit les liens vers les différents fichiers de légende en fonction du niveau d'échelle ;

      la balise <wmts:TileMatrixSetLink> précise les restrictions sur le TMS ;

      la balise <gpp:MetadataURL> contient les liens vers les fichiers de métadonnées relatifs à la donnée servie ;

      la balise <gpp:Keys> contient les URLs d'accès au service avec la clef utilisée pour l'autoconfiguration.

      Exemple de balise <Layer> pour une ressource WMTS :

      <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="CLEF">http://wxs.ign.fr/CLEF/geoportail/wmts</gpp:Key>
                   </gpp:Keys>
              </gpp:Layer>
          </Extension>
      </Layer>
    • Resource de type OpenLS (Géocodage direct ou inverse) ou d'Autocomplétion :

      Les droits d'accès au géocodage reposent sur le type de données géocodées (PositionOfInterest, StreetAddress, CadastralParcels). Pour chacun de ces types, on aura une balise pour le service de Gécodage Direct, une pour le Géocodage Inverse et une autre pour le service d'Autocomplétion. Pour chacune des trois, la signification des balises est la même.

      Exemple de balise <Layer> pour une ressource de type Géocodage :

      <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="CLEF">http://wxs.ign.fr/CLEF/geoportail/gazetteer</gpp:Key>
                  </gpp:Keys>
              </gpp:Layer>
          </Extension>
      </Layer>

Utilisation du service

Les apis web mises à disposition par l'IGN utilisent toutes ce service de manière transparente pour le développeur web pour initialiser la fenêtre cartographique.

Mise en cache du service d'autoconfiguration des APIs

La réponse du service d'autoconfiguration des APIs est assez volumineuse et cela augmente avec le nombre de ressources disponibles. Cela peut parfois peser dans le temps de chargement d'une page web utilisant les APIs Géoportail.

Pour pallier à ce problème, il est possible d'enregistrer la réponse de ce service pour la clef de son application sur le serveur de cette dernière. Ainsi le chargement se fera directement depuis le serveur de la page sans accéder aux serveurs de l'IGN.

Pour cela, il faut procéder en deux étapes :

1. Récupérer le fichier d'autocnfiguration en local.

L'API Javascript charge ce fichier avec le protocole JSONP. Il faut donc le récupérer selon le même principe. Si CLEF est la clef du contrat, on récupère notre fichier via l'url :

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

2. Paramétrer l'API pour qu'elle utilise le fichier en local.

Si on a sauvegardé le résultat du service d'autoconfiguration dans le fichier chemin/vers/autoconf.js alors, on indique à l'API Javascript qu'il faut utiliser ce fichier de la manière suivante :

  • avec le Loader.

    Le chemin vers le fichier d'autoconfiguration est précisé avec la propriété "geormUrl" du cinquième paramètre de la fonction Geoportal.load()

           iv= Geoportal.load(
                // div's ID:
                'viewerDiv',
                // API's keys:
                [CLEF],
                {// map's center :
                    // longitude:
                    lon:2.731525,
                    // latitude:
                    lat:45.833333
                },
                10,
                {
                  ...
                  geormUrl:'chemin/vers/autoconf.js',
                  ...
                }
            );
  • Sans le loader.

    On rajoute le chemin vers le fichier dans les paramètres de l'appel à la fonction Geoportal.GeoRMHandler.getConfig() :

        Geoportal.GeoRMHandler.getConfig(
            [APIkey], 
            null,
            'chemin/vers/autoconf.js', 
            {
              onContractsComplete: initMap
            }
        );
  • Remarques :

    1. le chemin vers le fichier est un chemin (du point de vue du navigateur) relatif à partir de l'emplacement de la page html qui charge les fichiers.

    2. Si vous modifiez les droits associés à votre clef, il faudra renouveler l'opération de façon à mettre à jour le fichier de réponse qui aura changé.