Premiers pas

Avant d'accéder à l'API, il faut passer par les étapes suivantes :

  • créer un compte

    Suite à l'inscription, un courriel de confirmation est envoyé. Une fois confirmé, il suffit de se connecter.

  • créer un contrat

    Pour la version bêta, les paramètres de création d'un contrat sont l'URL du site où elle va être déployée et le territoire concerné par les données à afficher. Une fois créé, un courriel de confirmation avec la licence est envoyé. Cette dernière donne accès aux cartes et aux ortho-photographies. Plusieurs licences peuvent être créées suivant les URLs, les territoires pour un même contrat.

API Web 2D en Javascript

Intégration de la visualisation IGN dans une page HTML

Pour pouvoir utiliser l'API IGN du Géoportail 2D dans une page HTML, il faut:

  • Placer une balise script qui fait appel à la page de vérification de licence. Vous devez remplacer le paramètre key par votre clé de licence;
  • Remplacer le paramètre instance par le nom que vous voulez donner à la carte et qui vous servira ensuite pour configurer cette carte. Ce nom sera celui de la variable Javascript de votre carte;
  • Placer dans le corps de la page HTML une balise DIV dont les attributs ID class et style sont renseignés comme dans le code qui suit;
  • Définir la fonction Javascript initGeoportalMap() cette fonction sera exécutée au chargement de la page pour initialiser votre carte;

    Le code HTML suivant contient tous les éléments nécessaires à l'inclusion d'une carte de l'API :

    <html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title></title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
    <script
        type="text/javascript"
        src="http://api.ign.fr/geoportail/api?v=VERSION&amp;key=VOTRE_LICENCE&amp;instance=maCarte&amp;">
    <!--
      -->
    </script>
    <script type="text/javascript">
    <!--
        function initGeoportalMap() {
            //Cette fonction sera exécutée au chargement de la page HTML
            //La carte doit y être créée et paramétrée
        }
      -->
    </script>
  </head>
  <body>
    <div id="plancheCartographique" style="width:800px;height:600px;"></div>
  </body>
</html>

    Le code précédent définit les éléments HTML nécessaires pour insérer une carte, mais ne la génère pas. Pour réaliser cette opération, il faut instancier un objet Geoportal.Map dans la fonction initGeoportalMap() définie ci-dessus. Le nom de la fonction à appeler est geoportalLoad + nom de l'instance. Si le nom de l'instance est maCarte, la fonction qui sera appelée sera geoportalLoadmaCarte(). Il est important de noter que l'appel au script avec votre clé de licence génère la variable Javascript passée en paramètre de instance, il n'est donc pas besoin de la déclarer à nouveau.

Tester l'intégration sur un poste local

Une fois l'intégration à votre page web réalisée vous allez pouvoir tester son bon fonctionnement sur votre poste local. Pour ce faire il est nécessaire d'équiper votre poste d'un serveur HTTP.
Une adresse de type http://localhost/maPageApi.html ou http://127.0.0.1/maPageApi.html est en effet nécessaire pour accéder aux données des couches Géoportail.

Parmi les nombreux serveurs HTTP libres et gratuits disponibles aujourd'hui (Apache, lighttpd, ...) nous conseillons aux utilisateurs peu familiers avec ce type de technologies et travaillant sous Microsoft Windows, l'utilisation de Zazou Mini Web Server.

Il vous suffit en effet de :

1ère étape :
Télécharger l'exécutable de Zazou Mini Web Server seul sur le site de Zazou Mini Web Server
2ème étape :
Copier l'exécutable dans le dossier contenant votre site ou page webLancement Zazou Mini Web Server
3ème étape :
Lancer l'exécutable en double-cliquant sur celui-ciLancement Zazou Mini Web Server
4ème étape :
Votre site/page est désormais accessible dans votre navigateur à l'adresse http://localhost/Visualisation de la page

Pare-feux personnels

Il est important de noter que la présence d'un pare-feu actif sur la machine peut provoquer l'affichage d'une carte vide ou "zébrée". Dans ce cas, il faut autoriser les flux en provenance de l'infrastructure du Géoportail de passer votre pare-feu : *.ign.fr et *.geoportail.fr devraient donc être autorisés dans les règles du pare-feu.

Versions de l'API

Le paramètre v, dont la valeur est VERSION dans l'exemple ci-dessus, est directement lié à la version de l'API Géoportail standard :

v Basée sur Tailles
minimum (compressée) 
standard (compressée) 
étendue (compressée)		 État
1.0beta Cf. 1.0beta1 N/A (N/A) 
N/A (N/A) 
749ko (N/A)		 Désactivé 
Redirigé sur 1.0beta3
1.0beta1 OpenLayers 2.5 N/A (N/A) 
N/A (N/A) 
749ko (N/A)		 Désactivé 
Redirigé sur 1.0beta3
1.0beta2 OpenLayers 2.6 N/A (N/A) 
N/A (N/A) 
809ko (N/A)		 Désactivé 
Redirigé sur 1.0beta3
1.0beta3 OpenLayers 2.7 N/A (N/A) 
N/A (N/A) 
925ko (N/A)		 Activé jusqu'à 1.0 
(+1 an)
1.0beta4 OpenLayers 2.7 117ko ( 28ko) 
641ko (149ko) 
981ko (219ko)		 Activé jusqu'à 1.0 
(+1 an)
1.0 OpenLayers 2.8 250ko ( 62ko) 
914ko (215ko) 
1400ko (300ko)		 Activé
1.1 OpenLayers 2.9.1 277ko ( 69ko) 
1100ko (251ko) 
1500ko (335ko)		 Activé
1.2 OpenLayers 2.10 288ko ( 72ko) 
1100ko (263ko) 
1600ko (353ko)		 Activé
Autre valeur Erreur retournée
à l'application
cliente		 N/A (N/A) 
N/A (N/A) 
N/A (N/A)		 N/A

La valeur du paramètre v peut être suivie de la chaîne "-m" pour obtenir l'API minimum.

La valeur du paramètre v peut être suivie de la chaîne "-e" pour obtenir l'API étendue.

Si le butineur supporte l'en-tête HTTP "Accept-Encoding: gzip", alors l'API est retournée compressée (son poids est réduit jusqu'à quatre fois la taille non compressée).

Types de visualisateur par défaut

Dans notre cas, on a passé dans la balise script instance=maCarte&amp;, donc l'appel se fera de cette manière :

geoportalLoadmaCarte("plancheCartographique","normal");

Le premier paramètre à donner est le nom de la DIV dans laquelle sera insérée la carte. Les paramètres suivant, tous optionnels, sont le type de carte souhaité, le territoire, la projection des données et celle d'affichage des coordonnées.

Il existe 2 types de visualisateur :

  • normal : carte de grande taille avec tous les panneaux visibles (gestionnaire de couche, boîte à outils et panneau d'information);
  • mini : carte de petite taille sans panneaux. Les déplacements et les zooms sont possibles via la souris.

Systèmes de référence spatiale

Certains codes EPSG sont aussi autorisés (e.g., EPSG:2154 correspond au code IGNF:LAMB93). Les codes sont définis via le projet PROJ4JS.

Divers

La carte ainsi générée est vide, il faut maintenant ajouter des couches de données. Pour ajouter les couches auxquelles votre licence vous donne l'accès, il suffit d'insérer les lignes suivantes :

if(maCarte.allowedGeoportalLayers){
    maCarte.addGeoportalLayers(maCarte.allowedGeoportalLayers);
}

ou, depuis la 1.0beta4 :

maCarte.addGeoportalLayers();

Il est important de retenir que les données sont affichées en projection équidistante cylindrique IGNF:GEOPORTALxxx (xxx étant le code du territoire) et que les informations en provenance des contrôleurs (telle les coordonnées de la souris) sont exprimées dans le système de référence géographique sous-jacent à la projection. Pour obtenir la projection des données, on utilise le fragment de code suivant :

var projection_carte= maCarte.getMap().getProjection();

Pour obtenir le système d'affichage des contrôleurs, on utilise le fragment de code suivant :

var projection_ctrl= maCarte.getMap().getDisplayProjection();

Pour centrer l'affichage sur une coordonnées GPS, on utilise le fragment de code suivant :

maCarte.getMap().setCenterAtLonLat(longitude, latitude);

Dans cet exemple, longitude et latitude peuvent être :

  • soit exprimées en degrés décimaux (Number) ;
  • soit exprimées en degrés sexagésimaux (String) avec les syntaxes suivantes :
    \s?-?(\d{1,3})[.,°d]?\s?(\d{0,2})[']?\s?(\d{0,2})[.,]?(\d{0,})(?:["]|[']{2})?
  \s?(\d{1,3})[.,°d]?\s?(\d{0,2})[']?\s?(\d{0,2})[.,]?(\d{0,})(?:["]|[']{2})?\s?([NSEW])?

    Ainsi, pour se centrer sur le marégraphe de Marseille :

    maCarte.getMap().setCenterAtLonLat("5d21'13,62161E", "43°16'43.56108 N");

La plupart des composants OpenLayers possède une méthode transform(OpenLayers.Projection ini,OpenLayers.Projection fin), consulter la documentation Openlayers pour de plus amples informations.

Ainsi, pour transformer un point en coordonnées géographiques type GPS en coordonnées de la carte, on utilise le fragment de code suivant :

var p= new OpenLayers.LonLat(longitude, latitude);
p.transform(OpenLayers.Projection.CRS84, maCarte.getMap().getProjection());

L'objet Geoportal.Map possède d'autres méthodes qui vous permettent de configurer votre carte. Pour les découvrir consulter la JSDoc de Geoportal.Map. Vous pouvez également consulter les examples de cartes.

  • CSS

    Les styles par défaut de l'API Géoportail et d'OpenLayers (style.css) sont automatiquement chargés par les API standard et étendue si nécessaire. En API minimum ou pour charger soi-même les styles, il faut utiliser les URLs suivantes :

    • CSS OpenLayers :
      http://api.ign.fr/geoportail/api/js/VERSION/theme/default/style.css
http://api.ign.fr/geoportail/api/js/VERSION/theme/default/ie6-style.css
http://api.ign.fr/geoportail/api/js/VERSION/theme/default/google.css
http://api.ign.fr/geoportail/api/js/VERSION/theme/default/framedCloud.css
      • ie6-style.css pour IE 6 ou moins (correction canal alpha png);
      • google.css quand OpenLayers.Layer.Google est utilisée;
      • framedCloud.css quand OpenLayers.Popup.FramedCloud est utilisée;
    • CSS Geoportail :
      http://api.ign.fr/geoportail/api/js/VERSION/theme/geoportal/style.css
http://api.ign.fr/geoportail/api/js/VERSION/theme/geoportal/standard.css
      • standard.css surcharge les styles quand Geoportal.Viewer.Standard est utilisée.

L'exemple Changement de l'affichage montre comment charger les CSS.

Il est important de noter que les CSS sont par défaut calibrées pour une carte de 800 par 600 pixels. Il est fortement conseillé d'adapter les règles à d'autres tailles.

  • Mode de compatibilité IE 8 :

    Jusqu'à la version 1.0beta4 il est nécessaire d'insérer le fragment de code suivant pour le support d'IE 8. Ce fragment doit être inséré avant toute autre balise meta. Il peut être inséré après la balise title :

        <!-- IE8 compatibility mode -->
    <!--[if IE 8]>
    <meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7"/>
    <![endif]-->

API et territoires

Le nom du territoire est un code ISO3166 alpha-3 :

  • Codes standards de l'ISO 3166 alpha-3 du territoire. Les valeurs possibles sont :
    ATF Terres Arctiques Australes (non encore en ligne)
    FXX France métropolitaine
    GLP Guadeloupe
    GUF Guyane
    MTQ Martinique
    MYT Mayotte
    NCL Nouvelle Calédonie
    PYF Polynésie Française
    REU Réunion
    SPM Saint Pierre et Miquelon
    WLF Wallis et Futuna
  • Les valeurs suivantes sont des extensions de l'ISO 3166 alpha-3 pour le Géoportail :
    ANF Antilles Française (GLP, MTQ, SMA, SBA)
    CRZ Crozet
    EUE Union Européenne
    KER Kerguelen
    SBA Saint-Barthélémy
    SMA Saint-Martin
    ASP Saint-Paul-Amsterdam (non encore en ligne)
    WLD La Terre

    La valeur par défaut est "FXX".

  • Les projections de données et d'affichage sont une chaîne de caractères du type IGNF:Code RIG. La documentation des codes RIG est içi. En l'absence de ces paramètres, l'API retrouve les systèmes de coordonnées des données et géographique du territoire.