===== Basic GeoAPI tutorial =====
This step by step tutorial will show you how to add a map in any web page in 2 minutes.
==== 1. Create an empty Html Page ====
Create an empty web page map.html and place it in your web server directory. Check that you can call it with //your.server.lu/map.html. You will need to request access to the GeoAPI for the specific server address from the ACT.
GeoAPI Exemple
==== 2. Include the API resources ====
In the header of your example, place the following required references to CSS and Javascript GeoAPI resources:
GeoAPI Exemple
==== 3. Initialize the map ====
Still in the header, add a function called init(), which loads the GeoAPI and initialises a map display into the Div "map".
Inside the Html Body section, a Div is created with the id "map", which will contain the map.
Finally, add to the body opening tag a call to the init() function once the document is loaded (onload). This allows the browser to only initialize the GeoAPI and render the map once all the resources have been loaded.
GeoAPI Exemple
==== 4. Test the Map ====
You should now be able to go to load your webpage in a browser, and see the interactive GeoAPI map as below. //your.server.lu/map.html .
==== 5. Change the BaseMap ====
You can change the look of the base map by adding to the .createMap() method a bgLayer parameter. Possible choices include "pixelmaps" and "pixelmaps-gray" (a grayscale version of the colour topo map). To see the "ortho" aerial imagery, which is always included, you need to set another parameter, bgOpacity, to a value between 0 - 100.
...
function init(){
geo = new geoadmin.API({lang: 'fr'});
geo.createMap({
div: 'map',
bgOpacity: 0,
bgLayer: 'pixelmaps-gray'
});
};
...
==== 6. Start Location & Zoomlevel (Converting Coordinates to LUREF) ====
You can set the starting location for the map and zoomlevel to a specific place in the country. Latitude & longitude is one very common coordinate reference system (WGS84 projection) to refer to a geographic location. The luxembourgish coordinate reference system (LUREF projection), which the GeoAPI uses, is different from WGS84, but the GeoAPI offers the possibility to convert between the two systems. In this step, we will demonstrate how to setup a conversion and make use of this to set the starting place and zoomlevel of the map.
OpenLayers Projection functionality allows us to define two coordinate reference system objects, using their [[//spatialreference.org/|EPSG reference codes]]. Once these have been setup, the OpenLayers.LonLat object can be defined as the starting place in LonLat Coordinates (WGS84), and transformed to LUREF.
The .createMap() options can contain two parameters, easting and northing, which take a coordinate in LUREF form. We make use of our transformed OpenLayers.LonLat object properties, to give the starting location. Finally, we can set the start zoomlevel between 0 (whole country) and 11.
...
function init(){
lux = new OpenLayers.Projection("EPSG:2169"); // the luxembourg coordinate reference system
wgs = new OpenLayers.Projection("EPSG:4326"); // the WGS84 coordinate reference system, as used widely
lonLat = new OpenLayers.LonLat(6.12459923192738, 49.6188206257115 ).transform( wgs, lux );
geo = new geoadmin.API({lang: 'fr'});
geo.createMap({
div: 'map',
easting: lonLat.lon,
northing: lonLat.lat,
zoom: 8,
bgLayer: 'pixelmaps-gray'
});
};
...
==== 7. Adding a marker and popup window ====
Once we have the coordinate transformation setup, we can now also add a map marker (icon) to the map. The .showMarker() method will insert a standard marker into the map at the specified location (easting & northing parameters).
...
function init(){
lux = new OpenLayers.Projection("EPSG:2169"); // the luxembourg coordinate reference system
wgs = new OpenLayers.Projection("EPSG:4326"); // the WGS84 coordinate reference system, as used widely
lonLat = new OpenLayers.LonLat(6.12459923192738, 49.6188206257115 ).transform( wgs, lux );
geo = new geoadmin.API({lang: 'fr'});
geo.createMap({
div: 'map',
easting: lonLat.lon,
northing: lonLat.lat,
zoom: 8,
bgLayer: 'pixelmaps-gray'
});
marker = geo.showMarker({
easting: lonLat.lon,
northing: lonLat.lat,
});
};
...
The resulting marker can be further customised, with a custom icon, as well as showing a popup window which can have a custom title and content:
...
marker = geo.showMarker({
iconPath: '//apps.geoportail.lu/exemple_api/exemplesWikiGeoAPI/lion.png', //absolute url to image file
graphicHeight: 35,
graphicWidth: 35,
easting: lonLat.lon,
northing: lonLat.lat,
html: "This is the content of the popup, it also takes html tags",
title: "This is the title of the popup",
hover: true //display marker popup on mouseover
});
...
==== 8. Adding more layers ====
The GeoAPI gives access to most datalayers contained on the GeoPortail. To add a certain layer, for example the bus stops ('arrets_bus'), you simply use the .addLayer() method. In the following example, we have added both the road network, road names, as well as bus stops to the map.
...
function init(){
lux = new OpenLayers.Projection("EPSG:2169"); // the luxembourg coordinate reference system
wgs = new OpenLayers.Projection("EPSG:4326"); // the WGS84 coordinate reference system, as used widely
lonLat = new OpenLayers.LonLat(6.12459923192738, 49.6188206257115 ).transform( wgs, lux );
geo = new geoadmin.API({lang: 'fr'});
geo.createMap({
div: 'map',
easting: lonLat.lon,
northing: lonLat.lat,
zoom: 10,
bgOpacity: 0,
bgLayer: 'pixelmaps-gray'
});
geo.addLayerToMap('roads');
geo.addLayerToMap('roads_labels');
geo.addLayerToMap('arrets_bus');
};
...
Please note that in the above example, the order in which you add layers matters! Layers are always rendered in the inverse order of how they are added, meaning the last layer to be added, gets rendered on top!
==== 8. Getting the Mouse Position as Coordinates ====
Altough the API already displays the current Mouse Position in LUREF coordinates (top-right corner of Map Window), you can also get the coordinates for the mouse (or center of map) programmatically. This can be useful for example when integrating the GeoAPI in other web applications.
The following example uses the OpenLayers MousePosition Control Event to run at each mouse move over the map a function. Here we simply display the position in a Div:
...
Blank
...
Want to know more! You can continue with the [[extendedtutorial|Extended GeoAPI Tutorial]].