First steps

Getting a license

The first steps for getting access to the API are :

creating a account
Upon subscription, an email is sent for confirmation. Once confirmed, just log in.
creating a contract
For the beta release, based on the web site URL where the API will be used, the chosen territory (France main land, overseas administrative units, ...) of the displayed data, a contract is created. Upon creation, an email is sent with the license. This license gives access to maps and orthophotos. Several licenses can be created depending on URLs and territories for a same account.

2D Web Javascript API

Integrating the API into a web page

In order to use the Geoportal API into a web page, one has to :

insert a script tag that calls the license token. You have to replace the key parameter value by your license key;
replace the instance parameter by any name you want in order to identify the map you are building. This name will be the name of the Javascript variable that supports your map;
add somewhere in the web page a DIV tag whose class and style attributes are set up as shown below;

define the content of the initGeoportalMap() function which will be called upon body's load in order to create the map;

The following HTML snippet shows the minimum code needed to display a map with the Geoportal API :

<!DOCTYPE html>
<html>
  <head>
    <title>API Geoportail - your personal map</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
    <style type="text/css"><!--/*--><![CDATA[/*><!--*/
    div#viewerDiv {
        width:800px;
        height:600px;
        background-color:white;
        background-image:url(http://api.ign.fr/geoportail/api/js/VERSION/theme/geoportal/img/loading.gif);
        background-position:center center;
        background-repeat:no-repeat;
    }
    /*]]>*/--></style>

  </head>
  <body>
    <div id="viewerDiv"></div>
    <script type="text/javascript"><!--//--><![CDATA[//><!--
    window.onload= function() {
        Geoportal.load(
            // div's ID:
            'viewerDiv',
            // API's keys:
            ['YOUR_LICENSE'],
            {// map's center :
                // longitude:
                lon:2.731525,
                // latitude:
                lat:45.833333
            }
        );
    };
    //--><!]]></script>

    <script
        type="text/javascript"
        src="http://api.ign.fr/geoportail/api/js/VERSION/Geoportal.js"
        charset="utf-8">
  <!-- -->
  </script>
  </body>
</html>

The following HTML code contains all the pieces necessary to obtain the map through the Geoportal API and start developping more advanced usages :

<!DOCTYPE html>
<html>
  <head>
    <title></title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
  </head>
  <body >
    <div id="viewerDiv" style="width:800px;height:600px;"></div>
    <script type="text/javascript"><!--
        var iVIEWER= null;

        function loadAPI() {
            iVIEWER= new Geoportal.load(
                "viewerDiv",
                ['YOUR_LICENSE'],
                null,
                null,
                {
                    onView: initGeoportalMap,
                    layers:[
                        'LAYER_NAME'
                    ],
                    layersOptions:{
                        'LAYER_NAME':{ ... }
                    }
                }
            );
        }

        function initGeoportalMap() {
            // RETRIEVE the viewer :
            var VIEWER= iVIEWER.getViewer();
            //call on body's onLoad
            //the map must be created and configured here
        }

        window.onload= loadAPI;
     -->
    </script>
    <script
        type="text/javascript"
        src="http://api.ign.fr/geoportail/api/js/VERSION/Geoportal.js"
        charset="utf-8">
  <!-- -->
  </script>
  </body>
</html>

The above code uses the basic framework needed to build a map on your page, but does not generate it yet. In order to do it, you need to create the Geoportal.Map map object within the initGeoportalMap() function. This can be achieved by calling the geoportalLoad + instance name function. If the instance name is myMap, the function to call will be geoportalLoadmyMap(). It is worth noting that calling the script with your license key generates the Javascript variable after the name given in the instance parameter. It is then not necessary to declare it again.

Personal firewalls

It is worth noting that when a personal firewall is running on your machine, you may have blank or striped map displayed on the screen. In order to have the layers showing up, we have to enable streams coming from the Geoportal infrastructure : *.ign.fr and *.geoportail.fr should be enabled in the firewall rules.

API versions

The v parameter, whose value is VERSION in the above code fragment, is directly linked with the Geoportal standard API :

v	Based on	Sizes minimum (compressed) standard (compressed) extended (compressed) flash (compressed) mobile (compressée)	Status
1.0beta	See 1.0beta1	N/A (N/A) N/A (N/A) 749kb (N/A) N/A (N/A) N/A (N/A)	Deactivated Redirected to 1.0beta3
1.0beta1	OpenLayers 2.5	N/A (N/A) N/A (N/A) 749kb (N/A) N/A (N/A) N/A (N/A)	Deactivated Redirected to 1.0beta3
1.0beta2	OpenLayers 2.6	N/A (N/A) N/A (N/A) 809kb (N/A) N/A (N/A) N/A (N/A)	Deactivated Redirected to 1.0beta3
1.0beta3	OpenLayers 2.7	N/A (N/A) N/A (N/A) 925kb (N/A) N/A (N/A) N/A (N/A)	Active till 1.0 + 1 year
1.0beta4	OpenLayers 2.7	117kb ( 28kb) 641kb (149kb) 981kb (219kb) N/A (N/A) N/A (N/A)	Active till 1.0 + 1 year
1.0	OpenLayers 2.8	256kb ( 62kb) 920kb (215kb) 1400kb (301kb) N/A (N/A) N/A (N/A)	Active
1.1	OpenLayers 2.9.1	283kb ( 69kb) 1100kb (252kb) 1500kb (335kb) N/A (N/A) N/A (N/A)	Active
1.2	OpenLayers 2.10	296kb ( 73kb) 1100kb (264kb) 1600kb (354kb) N/A (N/A) N/A (N/A)	Active
1.3.0	OpenLayers 2.11	363kb ( 81kb) 1400kb (330kb) 1900kb (438kb) 211kb ( 54kb) 1300kb (289kb)	!Active
Other value	Error sent back to client application	N/A (N/A) N/A (N/A) N/A (N/A) N/A (N/A) N/A (N/A)	N/A

Whenever the v parameter's value is suffixed with the "-m" string then the Geoportal minimum API is returned.

Whenever the v parameter's value is suffixed with the "-e" string then the Geoportal extended API is returned.

Whenever the v parameter's value is suffixed with the "-f" string then the Geoportal Flash loader API is returned.

Whenever the v parameter's value is suffixed with the "-g" string then the Geoportal Mobile loader API is returned.

When the web browser supports the HTTP head "Accept-Encoding: gzip", the API is returned compressed (up to four times lighter than uncompressed).

Default viewer types

In our example, the parameter value is instance=myMap&, therefore the call will be :

geoportalLoadmyMap("layerDiv","normal");

The first parameter is the DIV identifier where the map will be inserted. The other parameters are optional and represent the type of the map, the territory of the map, the projection of the map and the projection of the displayed information (like coordinates).

There are 2 types of maps :

normal : a map with all controls activated and shown (layers switcher, zoom panel, information panel);
mini : a map without visible panels. Panning and zooming are controlled using the mouse and keyboard movements.

Spatial Reference Systems

Some EPSG codes are also supported (for instance, EPSG:2154 which is the equivalent of the IGNF:LAMB93 RIG code). The projection codes are defined through the PROJ4JS project embed in the Geoportal API.

Miscellaneous

The generated map is empty and layers are now ready to be added. To add licensed layers, just add the following code fragment :

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

Since 1.0beta4, one could also write :

myMap.addGeoportalLayers();

It is worth noting that displayed data are in IGNF:GEOPORTALxxx projection (Equidistant cylindrical, xxx is the territory code) and displayed control data (such as mouse coordinates) are in the underlying geographic reference system of the projection. To get access to the map's projection, use the following code snippet :

var map_projection= myMap.getMap().getProjection();

To get access to the controls' projection, use the following code snippet :

var ctrl_projection= myMap.getMap().getDisplayProjection();

To simply center the map to a given geographic GPS coordinates, use the following code snippet :

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

In this example, longitude and latitude can be :

either expressed in decimal degrees (Number) ;

or expressed in sexagecimal degrees (String) with the following syntaxes :

\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])?

For instance, to center on the Marseilles 0 sea-level point :

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

Most OpenLayers widgets supports re-projection through the use of the transform(OpenLayers.Projection ini,OpenLayers.Projection fin) method. Have a look at the OpenLayers API for more information.

Thus for re-projecting GPS geographical coordinates into map coordinates, one could use the following code snippet :

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

The Geoportal.Map interface contains more methods for configuring the map. To discover them, have a look at the Javascript document of Geoportal.Map. You may also consult the examples.

CSS
Default CSS styles for Geoportal API and OpenLayers (style.css) are automatically loaded by the standard and extended APIs if necessary. When using the minimum API or in order to load CSS styles, one can use the following URLs :
- 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 for IE 6 or before (png alpha channel fix);
  - google.css when OpenLayers.Layer.Google is used;
  - framedCloud.css when OpenLayers.Popup.FramedCloud is used.
- Geoportal :
```
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 overwrites styles when Geoportal.Viewer.Standard is used.

The example Changing the layout shows how to load CSS directly.

It is worth to know that CSS are set up for 800 by 600 default map size. It is advised to overwrite CSS rules when changing map's size.

IE 8 compatibility mode
Up to 1.0beta4, it is necessary to include the following code fragment in your page for IE 8 to work. This fragment must be inserted before any other meta tag. It can be inserted after the title tag :
```
    
    
```
This fragment is no more relevant since the 1.2 release.

API territories

The territory code is an extended ISO 3166 alpha-3 string :

For the standard ISO 3166 alpha-3 the allowed values are :

ATF	Arctic territory (not yet in production)
FXX	France mainland
GLP	Guadeloupe
GUF	Guyane
MTQ	Martinique
MYT	Mayotte
NCL	New Caledonia
PYF	French polynesia
REU	Reunion island
SPM	Saint-Pierre-et-Miquelon
WLF	Wallis and Futuna

The following extra values, extending ISO 3166 alpha-3, have been created for the Geoportal API :

ANF	French Antilla (GLP, MTQ, SMA, SBA)
CRZ	Crozet islands
EUE	European Union
KER	Kerguelen islands
SBA	Saint-Barthelemy islands
SMA	Saint-Martin islands
ASP	Saint-Paul-Amsterdam islands (not yet in production)
WLD	the World

The default value is "FXX".

The data and display projections are characters strings. Their syntax is IGNF:CodeRIG. RIG codes documentation is there. You need to know that the API retrieves the data and display projections using the territory code. The display projection is the underlying geographic projection of the data projection.

Index

Users

Developers

Examples