Technical documentation of Geoportal API

  • FR
  • UK

Index / Documentation / Technical documentation

Use the JavaScript API

Which API ?

Geoportal Javascript API is available in different sized packages given the fonctionnalities that are needed. This allows to optimize the loading payload of the html page.

Minimum, Standard, Extended, Mobile, 3D and Flash API

  • The minimum API gives the developer the connectors for the WMTS, WMS and WFS services protected by the services access rights. The Geoportal permanent logo is also part of this API (See Terms Of Use). PROJ4JS library is part of this API. The level of API allows web sites with an already existing mapping librarie to integrate Geoportal services. It is loaded that way :
    <script type="text/javascript" charset="utf-8" src="http://api.ign.fr/geoportail/api/js/${api-libraries-version}/GeoportalMin.js"><!-- --></script>
  • The standard API gives the minimum API features and some feature of OpenLayers (KML, GPX, WMS access, OpenLS features, Controls). It also embed a /jsdoc/files/Geoportal/Viewer/Default-js.html}default viewer which wears Geoportal site style. It is loaded that way :
    <script type="text/javascript" charset="utf-8" src="http://api.ign.fr/geoportail/api/js/${api-libraries-version}/Geoportal.js"><!-- --></script>
  • The extended API gives the standard API features and all OpenLayers features. It is loaded that way :
    <script type="text/javascript" charset="utf-8" src="http://api.ign.fr/geoportail/api/js/${api-libraries-version}/GeoportalExtended.js"><!-- --></script>
  • The mobile API gives access to mobile devices with a minimal graphical interface. It is loaded that way :
    <script type="text/javascript" charset="utf-8" src="http://api.ign.fr/geoportail/api/js/${api-libraries-version}/GeoportalMobile.js"><!-- --></script>
  • The High Level 3D API gives access to integration and interaction with a VirtualGeo plugin in a web page. It is loaded that way :
    <script type="text/javascript" charset="utf-8" src="http://api.ign.fr/geoportail/api/js/${api-libraries-version}/Geoportal3D.js"><!-- --></script>
  • The High Level Flash API gives access to integration and interaction with an SWF Viewer developped with Geoportal Flash API in a web page. It is loaded that way :
    <script type="text/javascript" charset="utf-8" src="http://api.ign.fr/geoportail/api/js/${api-libraries-version}/GeoportalFlash.js"><!-- --></script>

API versions sizes

versionweights  
minimum (compressed) 
standard (compressed) 
étendue (compressed) 
flash (compressed) 
mobile (compressed) 
3D (compressed)
2.1.11,2Mo (282ko) 
1,9Mo (467ko) 
2,5Mo (588ko) 
277ko ( 69ko) 
1,7Mo (413ko) 
287ko ( 72ko)
2.1.01,1Mo (276ko) 
1,9Mo (450ko) 
2,4Mo (572ko) 
270ko ( 71ko) 
1,7Mo (405ko) 
280ko ( 73ko)
2.0.3837ko (192ko) 
1,9Mo (458ko) 
2,5Mo (577ko) 
276ko (72 ko) 
1,7Mo (405ko) 
286ko (74 ko)
2.0.2383ko (91 ko) 
1,9Mo (443ko) 
2,4Mo (562ko) 
252ko (60 ko) 
1,8Mo (403ko) 
261ko (62 ko)
2.0.1376,7ko (92 ko) 
1,9Mo (436ko) 
2,4Mo (548ko) 
248ko (60ko) 
1,7Mo (396 ko) 
256ko (64 ko)
2.0.0369,3ko (87 ko) 
1,5Mo (350ko) 
2,0Mo (471ko) 
252ko (59 ko) 
1,3Mo (311ko) 
260ko (62 ko)

If the browser supports the HTTP header "Accept-Encoding : gzip", the API is returned compressed ( the weight is reduced up to four times the uncompressed size).

Which release to use ?

The different versions of the Geoportal API are mentionned in the path to the API's scripts :

http://api.ign.fr/geoportail/api/js/VERSION_NUMBER/Geoportal.js

Version numbers are in the following patterns : "2.x.y", "2.x" or "latest". "2.x" and "latest" are aliases for particular version numbers :

  • "latest" is the latest published release ;
  • "2.x" is the latest 2.x.y published release. As 2.1.y has been released, "2.0" is now definitively "2.0.3"

    Generaly, it is not a good practice to use aliases (especially "latest") for sites that are deployed for production purpose : they are so exposed to possible dysfonctions due to interface or behaviors changes when a new released is published.

Integrating a map

Method 1: Using the loader 
Method 2: Without using the loader

There are two ways for loading a 2D viewer JavaScript :

  • The first method consists in using the method called Geoportal.load and the event 'onView' to set the viewer after it is loaded.
  • The second method consists in developping all the steps needed to load the map (downloading JS library, recovering access rights from the API key, creating the viewer etc).

The choice between these two methods have to be done by the developer. If he prefers totally controlling the code, he will use low level methods (method 1). Else, he can use the hight level method for an easier development (method 2).

Method 1: Using the loader

Add to the loader the option 'onView', which set to the name of the function to be triggered once the viewer loaded and configured (here, initMap).

It is within this function that will grab the viewer and make our traitemets:

Sample code to copy / paste ;

Method 2: Without using the loader

Adding the DIV tag that will contain the map

Placer dans le corps de la page HTML une balise DIV dont l'identifiant et le style sont renseignés comme dans le code qui suit;

Inserting a script tag that imports the API script

We consider here that we use the the standard version of JavaScript API (Geoportal.js):

  • If you use the minimum Javascript API, load library GeoportalMin.js.
  • If you use the extended Javascript API, load library GeoportalExtended.js.
  • If you use the mobile Javascript API, load library GeoportalMobile.js.

Retrieving the configuration related to the key:

One can use window.onload or any other means provided by other frameworks to execute the method loadAPI when the explorer has finished loading the page.

This function calls the Geoportal.GeoRMHandler.getConfig method with the following parameters: the list of API keys, the url of the auto service and the method that is called after the configuration is returned (called callback function), here: initMap:

Laoding the map:

The initMap function loads the map in the Div whose id is 'viewerDiv'.

It creates an instance of the class Geoportal.Viewer.Default with this set of options ad a parameter:

Sample code to copy / paste ;