Technical documentation of Geoportal API

  • FR
  • UK

Index / Documentation / Technical documentation

Using the High Level API

First steps 
Initializing the map 
Setting the map after it is loaded

The High Level API is a light javascript API which allows developpers to initialize and interact with a map based on a Flash, 3D or javascript viewer with the same syntax. It is comosed of a function called loader which allows to load the map and returns an InterfaceViewer object which allows developpers to interact whith the map throw dedicated methods.

This section outlines the steps for loading a 2D JavaScript, Flash 2D and 3D viewer using the High Level API.

We will see how initialize the viewer by specifying for example the Geoportal layers taht can be added to the map.

We will also see how to change the settings after loading the viewer, when adding an external button to change the the map's zoom for example.

First steps

Adding the DIV tag that will contain the map

In order to display the map, we must add in the web page a DIV element and set it's size using style attributes as shown below;

Loading the Geoportal API

Add a <script> tag that contains the location of a JavaScript file that loads all definitions you need for using the Geoportal API.

We consider here that we use 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 Flash API, load library la bibliothèque GeoportalFlash.js.
  • If you use the mobile Javascript API, load library GeoportalMobile.js.

NB: If you use the Flash API, download the Geoportail-Flash-Viewers.zip file, expand it and place the swf viewers in the same location as your HTML page.

Loading the map:

Before loading the map, the JavaScript API code must be fully loaded. To do so, use the JavaScript event "window.onLoad" or any other means provided by other environments.

The event is set to a callback function that executes the method Geoportal.load (also called loader):

window.onload=function() {
    Geoportal.load( div, key, pos, zoom, options );
}

The loader inserts and configures the visualization client (called viewer) in the HTML page using these parameters:

  • Div : the id of the div tag that will contain the map, "viewerDiv" in our case.
  • Key: an array containing the API keys
  • Pos: An object containing the position of the center of the map
  • Zoom: an integer corresponding to the desired zoom level, from 0 (world wide) to 21 (street level).
  • Options: an object containing all the mandatory and optional parameters to configure the viewer.

The following code shows how to load a JavaScript 2D viewer :

To load a different type of viewer, add to the loader the option 'type' (don't forget to load the adapted API script):

{ //loader's options

   // type : type of viewer among the following: 'flash', 'js', '3 D' (defaults to 'js')
   type  : 'flash'
}

Initializing the map

Set the map's center

If the developer does not specify a center, the map is centered on the default coordinates (eg Paris).

  • Center: instance of the OpenLayers.LonLat class with the coordinates (longitude, latitude) in WGS84;
    { // map's center
      center:new OpenLayers.LonLat(2.731525,45.833333)
    }
  • lon : longitude in WGS84
  • lat : latitude in WGS84

    These two parameters longitude and latitude can be:

    • expressed in decimal degrees (Number);
    • expressed in sexagesimal degrees (String);

    To focus on Marseille:

    { // map's center in sexagesimal degrees
      lon: "5d21'13,62161E",
      lat: "43°16'43.56108 N"
    };
    
    { //  map's center in decimal degrees
      lon: 5.353784,
      lat: 43.278767
    };
  • place : name of the desired position;
    { //  map's center
      place:"marseille"
    };
  • address : "street name, postcode, city";
    { // map's center
      address:'73 avenue de Paris, 94165, Saint-Mandé Cedex'
    };
  • geolocate : Boolean. true if one wishes to use geolocation;
    { // map's center
      geolocate:true
    }

Change the label and descriptive text of the popup

{ //loader's options

    //label: popup's title
    label:'SMNE Saint-Mandé - IGN',

    //description: description of the popup that appears in the center of the viewer
    description:'More details about the permanent GNSS station network <a href="http://rgp.ign.fr/STATIONS/fiche.php?type=station&ident=SMNE" target="_blank" title="SMNE">SMNE</a>'
}

Change Geoportal basemaps loaded by default

Depending on the viewer loaded (2D Javascript, Flash 2D or 3D), the API loads by default the following Geoportal layers:

  • 2D Javascript: Ortho-photographies and scanned maps
  • 2D Flash: orthophotos and cadastral parcels

    To add the other layers to which your license gives you access, add to the loader the option 'layers' which is an object containing the list of layers identifiers :

    { //loader's options
    
      //layers: list of identifiers of the Geoportal layers to use
      layers:['ORTHOIMAGERY.ORTHOPHOTOS','GEOGRAPHICALGRIDSYSTEMS.MAPS','ADMINISTRATIVEUNITS.BOUNDARIES']
    }

To change the default display options such as layers transparency, add to the loader the option 'layersOptions':

{ //loader's options

    layers:['ORTHOIMAGERY.ORTHOPHOTOS','GEOGRAPHICALGRIDSYSTEMS.MAPS',ADMINISTRATIVEUNITS.BOUNDARIES],

    //layersOptions: options related to the Geoportal layers.
    layersOptions:{
       'ADMINISTRATIVEUNITS.BOUNDARIES':{ visibility:true, opacity:0.7 }
    }
}

Chang the type of viewer (2D Javascript API)

By default, it is the simple viewer that is used: the map contains no sign and the zoom is possible via the mouse.

There are two other types of viewers:

  • Default: large map with all signs visible (layer manager and information panel);
    {   //loader's options
        viewerClass: Geoportal.Viewer.Default
    }
  • Standard: Same as default except the first and last panel are outside the map.

Change the .swf file used to load the 2D Flash viewer

To change the swf file used, add to the loader's options the option 'viewerClass' with the file name without the swf extension as value :

{ //loader's options
  ...
  viewerClass: 'newFile'
}

Set the map's theme

Add to loader the option 'theme':

{ // loader's options

    // theme: object containing the CSS urls available, their identifiers and the DOM node which links the elements of the theme
     theme:{name:'black',styles:[{css:'http://api.ign.fr/geoportail/api/js/1.3.0/theme/black/style.css'}]}
}

Add / remove components

Add to loader the option 'controlsOptions':

{ // loader's options

    //controlsOptions {Object} : The list of components to add / edit. This object is composed, for each component of the list of options.
    controlsOptions:{
        {
            ComponentName1: {
                PropertyName1:value, PropertyName2:value, ...
            }
        }, {
            ComponentName2: {
                PropertyName1:value, PropertyName2:value, ...
            }
        }, ...
    }
}

other options

{ // loader's options

    // language: {String} : The application's language defined by two characters IETF 4646
     language : 'EN',

     //displayProjection: {Array({String})} || {String} : The display projection used (only for 2D viewers)
    displayProjection : 'EPSG:4326',

    //proxyURL : {String} : The URL of the proxy to use
    proxyURL : '../proxy.php'
}

Add external layers

Add to loader the option 'overlays':

{ //loader's options

    //overlays: list of layers to add. This object is composed, for each protocol, of an array of objects containing the information needed to add layers
    overlays:{

        // Case of services "WMS", "WMTS", "WFS" ou "GEORSS"
        'Type_of_layer1':[{
            'name':'layer_name', 'access url':'urlOfOverlay', options:{params{service_parameters}, options{layer_parameters}}
        }, {
            'name':layer_name', 'access url':'urlOfOverlay', options:{params{service_parameters}, options{layer_parameters}}
        }, ... ],

        // Case of files "KML", "GPX" ou "OSM"
        'Type_of_layer2':[{
            'name':'layer_name', 'access url':'urlOfOverlay', options:{params{layer_parameters}, options{popup_parameters}}
        }, {
            'name':'layer_name', 'access url':'urlOfOverlay', options:{params{layer_parameters}, options{popup_parameters}}
        }, ... ],
        ...
    }
}

The details of parameters used is here.

Example of adding a KML,GPX, WMS,WFS layer.

Map's events management

Add to loader the following options:

{ // loader's options

    onView: set to the name of the function to be triggered once the viewer loaded and configured

    onBeforeView: set to the name of the function to be triggered before loading the viewer
}

Setting the map after it is loaded

After running the loader, it loads the viewer and creates a JavaScript object named interfaceViewer:

var iv=null;

window.onload=function() {
    iv=Geoportal.load( div, key, pos, zoom, options );
}

The interfaceViewer contains a set of setters to modify the viewer after it's loading. Among these setters, we can find:

Setter's nameRole
setCenterpositions the center of the map in WGS84 (decimal degrees or sexagesimal): 
iv.setCenter(2.731525,45.833333);
setZoomdefines the zoom of the map at certain zoom or resolution given: 
iv.setZoom(13);
panmoves the center of the map (in pixels) 
iv.pan(5,5);
setLayerOpacitymanages the opacity of a layer 
iv.setLayerOpacity('ORTHOIMAGERY.ORTHOPHOTOS',0.3);
setLayerVisibilitymanages the visibility of a layer 
iv.setLayerVisibility('ADMINISTRATIVEUNITS.BOUNDARIES',true);
addGeoportalLayeradds a layer geoportal by specifying its identifier 
iv.addGeoportalLayer('id_couche');
addLayer(s)adds an external layer 
iv.addLayer("Type","Nom", "Url", Service_parameters, Layer_parameters);
toggleControldevelops or iconify a component by specifying its identifier or the name of its class 
var LS= viewer.getMap().getControlsByClass("Geoportal.Control.LayerSwitcher")[0]; 
iv.toggleControl(LS.id);
setLanguagedefines the language of the viewer (two characters IETF 4646) 
iv.setLanguage('en');
setSizedefines the size (height and width) of the viewer. 
iv.setSize('500','300');
setThemesets the style of the viewer
addComponentadds a component to the map. 
iv.addComponent('Geoportal.Component.LayerCatalog');