IGN - API Geoportail - Modes opératoires

Développer avec l'API

API Web 2D en Javascript

Organisation de l'API

La première étape pour développer avec l'API du Géoportail est de télécharger cette dernière (Voir Téléchargements). Le projet API utilise Maven pour sa compilation et son installation. Python est aussi utilisé pour la compression des Javascripts, et Perl pour un proxy CGI en local.

L'API doit être décompactée dans un répertoire visible par un service Web. L'architecture globale de l'API est comme suit :

trunk	le répertoire principal contenant les sources, les builds, ... les fichiers de test sont localisés dans le répertoire `trunk/main/webapp/test`
target	le répertoire où est construite l'API. Après la compilation, il contient l'API et le site. L'API peut être non compressée via la commande `mvn -Penv-local`, ou compressée via `mvn -Penv-dev`

Le répertoire contenant le code Javascript réside dans trunk/main/javascript. Ce répertoire est divisé en plusieurs parties :

build	Ce répertoire contient les scripts ant nécessaires à diverses opérations
geoportal	C'est le répertoire source de l'API
openlayers	C'est le répertoire source d'OpenLayers utilisé par l'API
proj4js	C'est le répertoire source de PROJ4JS utilisé pour les reprojections.

Les répertoires openlayers et proj4js contiennent le code original. Toutes modifications apportées à ces sources sont localisées dans le répertoire geoportal/lib :

Geoportal	Contient le code source principal de l'API La structure globale est la même que pour OpenLayers
OpenLayers	Contient les fichiers de surcharge d'OpenLayers `OverloadedOpenLayersMinimum.js`, `OverloadedOpenLayersStandard.js` et `OverloadedOpenLayersExtended.js`.
proj4js	Contient le fichier de surcharge de PROJ4JS `OverloadedProj4js.js`, ainsi que les répertoires `catalogues` et `projCode`. Le premier supporte un catalogue EPSG partiel et un catalogue IGNF. Ces catalogues décrivent les systèmes de référence spatiale utilisés par l'API. Le second répertoire contient les nouveaux algorithmes utilisés par l'API si nécessaire.

Développement avec l'API

Le développeur peut utiliser sa licence pour afficher les données du Géoportail. La première étape consiste à prévenir l'API de ne pas charger le fichier compressé Geoportal.js :

<script
    type="text/javascript"
    src="http://api.ign.fr/geoportail/api?v=VERSION&amp;key=CLEF&amp;instance=VISU&amp;includeEngine=false&amp;">
<!--//--><![CDATA[//><!-- //--><!]]>
</script>

En mode développement, il peut être intéressant d'afficher des messages d'exécution via l'utilisation des méthodes d'OpenLayers.Console :

<html xmlns="http://www.w3.org/1999/xhtml" debug="true">
...
<script type="text/javascript" src="../js/VERSION/lib/openlayers/lib/Firebug/firebug.js">
<!--//--><![CDATA[//><!-- //--><!]]>
</script>

Puis, il faut charger le script local compressé ou non de l'API. Pour l'API non compressée, le fragment de code suivant montre comment faire (il suppose que votre page web est située dans un répertoire au même niveau que celui de l'API) :

<script type="text/javascript" src="../js/VERSION/lib/geoportal/lib/Geoportal.js">
<!--//--><![CDATA[//><!-- //--><!]]>
</script>

La valeur de VERSION est expliquée dans la page Intégration.

La page web peut être testée localement. Il n'est nul besoin de publier celle-ci sur le site web déclaré pour l'obtention de la licence. Ceci permet au développeur de coder son application en local avant son déploiement sur son site.

Le code suivant montre une page complète uncompressed_local.html permettant d'utiliser l'API dans ces conditions de test (en local) :

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" debug="true">
<head>
    <title>uncompressed_local.html</title>
    <!-- indicates UTF-8 to get proper display of API labels : -->
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
    <link rel="shortcut icon" type="image/x-icon" href="img/favicon.ico" />
    <!-- include CSS for easying overwriting of styles : -->
    <!-- OpenLayers styles : -->
    <link id="__OpenLayersCss__" rel="stylesheet" type="text/css" href="../js/VERSION/lib/openlayers/theme/default/style.css"/>
    <!--[if lte IE 6]>
    <link id="__IE6OpenLayersCss__" rel="stylesheet" type="text/css" href="../js/VERSION/lib/openlayers/theme/default/ie6-style.css"/>
    <![endif]-->
    <!-- if OpenLayer.Layer.Google is used : -->
    <!--
    <link id="__GoogleOpenLayersCss__" rel="stylesheet" type="text/css" href="../js/VERSION/lib/openlayers/theme/default/google.css"/>
      -->
    <!-- if OpenLayers.Popup.FramedCloud is used : -->
    <!--
    <link id="__FramedCloudOpenLayersCss__" rel="stylesheet" type="text/css" href="../js/VERSION/lib/openlayers/theme/default/framedCloud.css"/>
      -->
    <link id="__GeoportalCss__" rel="stylesheet" type="text/css" href="../js/VERSION/lib/geoportal/theme/geoportal/style.css"/>
    <!--[if lte IE 6]>
    <link id="__IE6GeoportalCss__" href="../js/VERSION/lib/geoportal/theme/geoportal/ie6-style.css" type="text/css" rel="stylesheet"/>
    <![endif]-->
    <!-- if Geoportal.Viewer.Standard is used : -->
    <!--
    <link id="__StandardCss__" rel="stylesheet" type="text/css" href="../js/VERSION/lib/geoportal/theme/geoportal/standard.css"/>
      -->
    <style type="text/css"><!--/*--><![CDATA[/*><!--*/
    /* overwritten styles or new styles : */
    div#footer {
        font-size:x-small;
        text-align:center;
        width:800px;
    }
    div#footer a, div#footer a:link, div#footer a:visited, div#footer a:hover {
        text-decoration:none;
        color:black;
    }
    /*]]>*/--></style>
</head>
<body onload="myOnLoad();">                                         <!-- call myOnLoad when onload event is fired -->
    <div id="viewerDiv" style="width:800px;height:600px;"></div>    <!-- the map div -->
    <div id="footer"><a href="https://api.ign.fr/geoportail/document.do?doc=legal_mentions" target="_blank">Terms of Use</a> - &copy;IGN 2008-2011</div>
    <script type="text/javascript"><!--//--><![CDATA[//><!--
    var viewer= null;//the viewer instance
    if (window.__Geoportal$timer===undefined) {
        var __Geoportal$timer= null;
    }

    // onload event will call myOnLoad :
    function myOnLoad() {
        if (__Geoportal$timer!=null) {
            window.clearTimeout(__Geoportal$timer);
            __Geoportal$timer= null;
        }
        if (typeof(OpenLayers)=='undefined'              ||
            typeof(Geoportal)=='undefined'               ||
            typeof(Geoportal.Viewer)=='undefined'        ||
            typeof(Geoportal.Viewer.Default)=='undefined') {
            __Geoportal$timer= window.setTimeout('myOnLoad();', 300);
            return;
        }
        // build a new viewer :
        viewer= new Geoportal.Viewer.Default(           // Default viewer (one could use Geoportal.Viewer.Standard)
                "viewerDiv",                            // div id where to display dataset
                OpenLayers.Util.extend({                // viewer parameters :
                    mode:'normal',
                    territory:'FXX',
                    projection:'IGNF:GEOPORTALFXX',
                    displayProjection:'IGNF:RGF93G',
                    proxy:PROXY+'?url=',
                    nameInstance:'viewer'},
                    gGEOPORTALRIGHTSMANAGEMENT          // API configuration with regard to the API key
                )
        );
        if (!viewer) {
            alert('failed loading viewer');
            return;
        }
        viewer.addGeoportalLayers();                    // load all available layers
        // default center and zoom location :
        viewer.getMap().setCenter(viewer.viewerOptions.defaultCenter,viewer.viewerOptions.defaultZoom);
    }
    //--><!]]></script>
    <!-- get the API configuration, but without the API javascript : -->
    <script type="text/javascript" src="http://api.ign.fr/geoportail/api?v=VERSION&amp;key=VOTRE_CLEF&amp;includeEngine=false&amp;"><!--//--><![CDATA[//><!--
    //--><!]]></script>
    <script type="text/javascript" src="../js/VERSION/lib/openlayers/lib/Firebug/firebug.js"><!--//--><![CDATA[//><!--
    //--><!]]></script>
    <!-- load local API : -->
    <script type="text/javascript" src="../js/VERSION/lib/geoportal/lib/Geoportal.js"><!--//--><![CDATA[//><!--
    //--><!]]></script>
</body>
</html>

L'exemple ci-dessus peut être visualisé par http://localhost/VOTRE_CONTEXTE/uncompressed_local.html.

Note : sous windows, nous vous conseillons d'utiliser ZazouMiniWebServer comme service web (serveur HTTP) pour sa simplicité d'utilisation.

Développement avancé avec l'API (à partir de la version 1.0beta4)

Le modèle précédent est destiné aux responsables de site qui veulent rapidement afficher des données en ligne. Dans le cas de développements nécessitant de s'affranchir des limitations de base de l'API, il est possible de procéder comme suit.

Le développeur a toujours besoin de déclarer sa licence, mais cette fois sans fournir le paramètre VISU :

<script
    type="text/javascript"
    src="http://api.ign.fr/geoportail/api?v=VERSION&amp;key=VOTRE_CLEF&amp;includeEngine=false&amp;">
<!--//--><![CDATA[//><!-- //--><!]]>
</script>

Note : l'utilisation du paramètre includeEngine à "false" permet de ne pas recevoir le Javascript GeoportalMin.js (si VERSION vaut "VERSION-m") ou Geoportal.js ou GeoportalExtended.js (si VERSION vaut "VERSION-e") de l'API. Ceci peut être utile pour mettre le script en cache.

L'API retournera alors le code Javascript suivant :

var window.gGEOPORTALRIGHTSMANAGEMENT= {};
gGEOPORTALRIGHTSMANAGEMENT.apiKey= 'CLEF';
gGEOPORTALRIGHTSMANAGEMENT['CLEF']= {
  tokenServer:{url:'SERVEUR_DE_JETONS',ttl:TTL},
  tokenTimeOut:TTO,
  bounds: [LONMIN,LATMIN,LONMAX,LATMAX],
  allowedGeoportalLayers:[],
  resources:{}
};
gGEOPORTALRIGHTSMANAGEMENT['CLEF'].allowedGeoportalLayers.push('NOM_COUCHE:TYPE_DE_SERVICE');
gGEOPORTALRIGHTSMANAGEMENT['CLEF'].resources['NOM_COUCHE:TYPE_DE_SERVICE']=
  {name:'NOM_COUCHE',type:'TYPE_DE_SERVICE',url:'http://wxs.ign.fr/geoportail/SERVICE'};
...

Le contenu de la variable globale gGEOPORTALRIGHTSMANAGEMENT peut alors être utilisé pour créer la carte :

...
my options= OpenLayers.Util.extend(
    {
        mode:"normal"
    },
    gGEOPORTALRIGHTSMANAGEMENT
);
...
VISU= new Geoportal.Viewer.Default("LocalDiv", options);
...

C'est alors au développeur d'insérer son code dans son application.

Des modèles de développement sont présents là :

Comportement par défaut de l'API

Quant le code suivant est écrit dans la page web :

<script
    type="text/javascript"
    src="http://api.ign.fr/geoportail/api?v=VERSION&amp;key=CLEF&amp;instance=VISU&amp;">
<!--//--><![CDATA[//><!-- //--><!]]>
</script>

L'API retourne le fragment Javascript inséré à la fin de l'en-tête de la page :

 var VISU= null;
function geoportalLoadVISU(idDivMap, mode, territoire, crs, dispcrs, proxy){
  var options= {};
  if(mode) {options.mode= mode;}
  if(territoire) {options.territory= territoire;}
  if(crs) {options.projection= crs;}
  if(dispcrs) {options.displayProjection= dispcrs;}
  if(proxy) {options.proxy= proxy;}
  options.nameInstance= 'VISU';
  options.apiKey= [];
  options.apiKey.push('CLEF');
  options['KEY']= {
    tokenServer:{url:'SERVEUR_DE_JETONS',ttl:600},
    tokenTimeOut:600,
    transport:'json',
    bounds: [LONMIN,LATMIN,LONMAX,LATMAX],/* l'emprise du contrat CLEF */
    allowedGeoportalLayers:[],
    resources:{}
  }
  /* pour chaque couche dans le contrat CLEF : */
  options['CLEF'].allowedGeoportalLayers.push('NOM_COUCHE:TYPE_DE_SERVICE');
  options['CLEF'].resources['NOM_COUCHE:TYPE_DE_SERVICE']= {
    name:'NOM_COUCHE',
    type:'TYPE_DE_SERVICE',
    url:'http://wxs.ign.fr/geoportail/SERVICE'
  };
  /* fin pour chaque */
  VISU= new Geoportal.Viewer.Default(idDivMap, options);
  return VISU;
}
// Geoportal API version 1.0 (MODE)
var __Geoportal$listenerLoaded= false;
var __Geoportal$loadComplete= false;
var __Geoportal$onloadCallbacks= null;
var __Geoportal$ready= false;
var __Geoportal$nof= function(){};
var __Geoportal$timer= null;
var __Geoportal$ua= navigator.userAgent.toLowerCase();
var __Geoportal$browser= {" + this.newLine +
  version:(__Geoportal$ua.match(/.+(?:rv|it|ra|ie)[\\/: ]([\\d.]+)/) || [0,'0'])[1],
  safari:/webkit/.test(__Geoportal$ua) && !/chrome/.test(__Geoportal$ua),
  opera:/opera/.test(__Geoportal$ua),
  msie:/msie/.test(__Geoportal$ua) && !/opera/.test(__Geoportal$ua),
  mozilla:/mozilla/.test(__Geoportal$ua) && !/(compatible|webkit)/.test(__Geoportal$ua),
  chrome:/chrome/.test(__Geoportal$ua)
};

function __Geoportal$launch() {
  if (__Geoportal$timer!=null) {
    window.clearTimeout(__Geoportal$timer);
  }
  if (viewer==null && typeof(initGeoportalMap)=='function') {
    initGeoportalMap();
  }
}

function __Geoportal$init() {
  __Geoportal$loadListener();
  if (!__Geoportal$loadComplete) {
    __Geoportal$loadComplete= true;
  } else if (!__Geoportal$ready) {
    if (__Geoportal$timer!=null) {
      window.clearTimeout(__Geoportal$timer);
      __Geoportal$timer= null;
    }
    __Geoportal$ready= (typeof(Geoportal)!=='undefined' && typeof(Geoportal.Viewer)!=='undefined' && typeof(Geoportal.Viewer.Standard)!=='undefined');
    if (!__Geoportal$ready) {
      __Geoportal$timer= window.setTimeout('__Geoportal$init();',500);
      return;
    }
    var __Geoportal$onloadCallbacks= window.onload || __Geoportal$nof;
    if (__Geoportal$onloadCallbacks===__Geoportal$nof) {
      __Geoportal$launch();
    } else {
      __Geoportal$timer= window.setTimeout('__Geoportal$launch();',500);
    }
  }
}

function __Geoportal$loadListener() {
  if (__Geoportal$listenerLoaded) {return;}
    __Geoportal$listenerLoaded= true;
    /*Mozilla*/
    if (document.addEventListener && !/(webkit|opera)/.test(__Geoportal$ua)) {
      document.addEventListener("DOMContentLoaded", function() {
        document.removeEventListener("DOMContentLoaded", arguments.callee, false);
        __Geoportal$init();
      }, false);

    /*IE*/
    } else if (document.attachEvent && !/opera/.test(__Geoportal$ua)) {
      if (document.readyState==="complete"){
        __Geoportal$init();
      } else {
        document.attachEvent("onreadystatechange", function() {
          if (document.readyState==="complete") {
            document.detachEvent("onreadystatechange", arguments.callee);
            __Geoportal$init();
          }
        });
      }

      if (document.documentElement.doScroll && window==window.top) (function() {
        if (__Geoportal$loadComplete) {return;}
        try {
          document.documentElement.doScroll("left");
        } catch (error) {
          setTimeout(arguments.callee, 0);
          return;
        }
        __Geoportal$init(); })();

      /*Safari, Opera, Chrome*/
      } else if (/(webkit|opera)/.test(__Geoportal$ua)) {
        var __timer= setInterval(function() {
          if (/loaded|complete/.test(document.readyState)) {
            clearInterval(__timer);
            __Geoportal$init();
          }
        }, 10);
      }


   if (window.addEventListener) {
      window.addEventListener("load", function(e) {
        if (window.removeEventListener && e.eventPhase == 3) {
          window.removeEventListener("load", arguments.callee, false);
        }
        __Geoportal$init();
      },false);
   } else if (window.attachEvent) {
     window.attachEvent("onload", function() {
       if (window.detachEvent) {
         window.detachEvent("onload",arguments.callee);
       }
       __Geoportal$init();
     });
   }
}

/* quand includeEngine est omis ou true : */
function __Geoportal$onloadcheck() {
  if (this.readyState=='loaded' || this.readyState=='complete') {
    this.onreadystatechange= null;
    this.onload();
    this.onload= null;
  }
}
/* fin quand */

(function() {
  __Geoportal$onloadCallbacks= window.onload;
  window.onload= __Geoportal$nof;
  /* quand includeEngine est omis ou true : */
  var _sGP= document.createElement('script');
  _sGP.type= 'text/javascript';
  _sGP.src= "http://api.ign.fr/geoportail/api/js" + VERSION + "GeoportalMODE.js';
  _sGP.charset= 'utf-8';
  _sGP.onload= __Geoportal$loadListener;
  _sGP.onerror= function(){//utile seulement pour FireFox (pour lever une erreur en cas de 404)
    throw ('The script ' + this.src + ' has not been found.');
  };
  if (/msie/.test(__Geoportal$ua) || /webkit/.test(__Geoportal$ua)) {
    _sGP.onload= __Geoportal$init;
    _sGP.onreadystatechange= __Geoportal$onloadcheck;
  }
  var nodes= document.getElementsByTagName('head');
  var head= nodes.length>0? nodes[0]: document.body;
  head.appendChild(_sGP);
  /* sinon */
  __Geoportal$loadListener();
  /* fin quand */
})();

API minimale, standard et étendue (à partir de la version 1.0beta4)

L'API minimale permet au développeur d'utiliser les connecteurs vers les services protégés par la GeoRM (WMS, WFS et WMS-C). Elle fournit aussi le logo du Géoportail (Voir les Conditions d'Utilisation). La bibliothèque PROJ4JS est aussi embarquée dans cette API. Ce niveau d'API permet d'intégrer dans un site web basé sur OpenLayers les données en provenance du Géoportail (Voir le site web des métadonnées françaises).

L'API standard propose les fonctionalités de l'API minimale plus certains connecteurs d'OpenLayers (accès aux services WMS, aux formats KML, GPX, aux contrôles de base). Elle embarque aussi un visualiseur par défaut qui était proposé dans les versions antérieures. Un autre visualiseur basé sur le site web du Géoportail est aussi fourni en exemple.

L'API étendue contient l'API standard et toutes les fonctionalités d'OpenLayers.

Développer avec l'API sous windows

Pré-requis :

Maven : pour la compilation, l'installation de l'API dans le dépôt web local et la génération de la documentation ;
Python : pour la compression des codes sources Javascript ;
Perl ou Php : pour l'utilisation d'un proxy CGI en local ;
Zazou Mini Web Server ou des serveurs web plus lourds IIS ou Apache : pour tester les pages web de l'API.

Etapes :

Télécharger les codes sources de l'API et les enregistrer dans le répertoire du projet API (chemin_répertoire_api par exemple) ;
Copier ZazouMiniWebServer.exe dans le répertoire chemin_répertoire_api\src\main\webapp ;

Ouvrir l'invite de commandes sous Windows, se placer dans le répertoire chemin_répertoire_api et saisir la commande suivante :

mvn -e -Penv-local -Dpython_path="chemin_python\python.exe" \
    -Durl_site="chemin_répertoire_api\target" \
    clean compile site-deploy

Double cliquer sur ZazouMiniWebServer.exe : les exemples sont disponibles via l'adresse suivante http://localhost/test/index.html

Sommaire

Utilisateurs

Développeurs

Exemples