====== Introduction ======

This is the technical reference of the GeoAPI, which lists all methods available to developers, along with their methods and properties, and as far as possible, implementation examples.

===== HTTPS Connection =====

The GeoAPI is available both as HTTP and HTTPS, for applications that need all resources to be encrypted.

//api.geoportail.lu/builds

//api.geoportail.lu/builds
===== API Builds =====

The API has a build system, which contains a [[//api.geoportail.lu/builds/latest| /builds/latest ]] directory, which is updated automatically to the latest version of the GeoAPI. This can cause problems for advanced systems if functionality or interfaces change. If you want to manage the API build levels manually, we create for each update of the API a defined build (for example [[ //api.geoportail.lu/builds/201310161641 | /builds/201310161641 ]]. It is then up to the API user to manually update the GeoAPI build as the need arises. 

A full list of the builds available and the link addresses for the javascript and css files can be found at //api.geoportail.lu/builds
===== geoadmin.API(options) =====
Creates a GeoAPI instance. 
<code javascript>
geo = new geoadmin.API({lang: 'de'});
</code>
**Options parameters** 
  * lang: //String//
  * map: //OpenLayers.Map//
  * mapPanel: //GeoAdmin.MapPanel//
  * activatePopup: //Boolean//
  * selectCtrl: //OpenLayers.Control.SelectFeature// 
  * debug: //String// set the debug mode (prod or debug)
  * isMainApp: //Boolean// define is the API is an instance of the main application or of a derived application
  * baseUrl: //String// base url of the main application
  * initialExtent: //String// initial extent of the map
  * searchUrl: //String// search url

==== API.layers ====
Object list of layers objects.

Please note: the list of layers available in the API is restricted to specific themes (roughly matching the different thematic portals: map.geoportail.lu, tourisme.geoportail.lu ...). In most applications, we load api.js to load the layers contained in the api theme (map.geoportail.lu). You can load other themes layers, by replacing main.js by tourisme.js for example.

<code html>
<script type="text/javascript" src="//api.geoportail.lu/tourisme.js"></script>
</code>

==== API.createMap(options) ====
Creates a Map instance. 
<code javascript>
geo.createMap({
   div: 'ex1',
   easting: lonLat.lon,
   northing: lonLat.lat,
   zoom: 8,
   bgLayer: 'pixelmaps-gray'
});
</code>
**Options parameters** 
  * div: //String//
  * easting: //Number//
  * northing: //Number//
  * zoom: //Integer//
  * layers: //String// Comma separated value(s) 
  * layers_indices: //String// Comma separated value(s)
  * layers_opacity: //String// Comma separated values, between 0 and 1
  * bgLayer: //String// Background layer, see layer list
  * bgOpacity: //String// Background pixelmap opacity, between 0 and 100

==== API.createMapPanel(options) ====
Creates a MapPanel instance. 
<code javascript>
geo.createMapPanel({
   mapInfo: {
      zoom: 8,
      easting: lonLat.lon,
      northing: lonLat.lat,
      bgLayer: 'pixelmaps-gray',
      bgOpacity: 0			
   }
});
</code>
**Options parameters** 
  * any GeoAdmin.MapPanel parameter
  * mapOptions: //Object// Object containing options for the map, see API.createMap() constructor options

==== API.createToolbar(options) ====
Creates a Toolbar instance. 

**Options parameters**
  * items: //Array// List of functions to activate. Possible values: 'ZoomToMaxExtent', 'Navigation', 'ZoomBox','LengthMeasure', 'AreaMeasure', 'NavigationHistory','ZoomOut', 'DrawFeature', 'ClearFeatures'

==== API.createTooltipFeature(options) ====
Creates a TooltipFeature instance. 	

**Options parameters** 
  * tooltipUrl: //String// Absolute URL of the search server endpoint (<nowiki>"//map.geoportail.lu/bodfeature/search"</nowiki>). 
  * requestOnlyVisibleLayers: //Boolean// 			

==== API.createLayerTree() ====
Creates a LayerTree instance. 

==== API.addLayerToMap(layer) ====

  * layer: //String// Name of the layer to add to map

==== API.showMarker(options) ====
Creates a marker instance and adds it to the map. Associates a popup if the html content property is set.

**Options parameters** 
   * easting: //Integer// position of the marker, default: map center
   * northing: //Integer// position of the marker, default: map center
   * iconPath: //String// path of a custom icon for the marker (url or relative), default: /mfbase/openlayers/img/marker-gold.png
   * recenter: //Boolean// define if the map has to recentered at the marker position, default: false
   * graphicHeight: //Integer// height of the height, default: the icon height
   * graphicWidth: //Integer// width of the height, default: the icon width
   * fillOpacity: //Number// opacity of the marker (from 0 to 1), default: 1
   * html: //String// html content of a popup, default: null

==== API.showFeatures(layer,ids) ====
Sets Map view to show selected features and zoomlevel.

  * layer: //String// Name of the layer to add to map
  * ids: //Array// list of feature id's to display

==== API.createMyMapLayer(options) ====
Add a layer with a specific MyMap Layer to the map. 
<code javascript>
geo.createMyMapLayer({ 
   mapId:'dc5c7fd7a13c4dcda2a74971f6f3a136',
   callback: function(features){
	var c = features.features[0].geometry.getCentroid();
	geo.map.setCenter([c.x,c.y]);
   }
});
</code>
**Options parameters** 
  * mapID: //String// ID of the MyMap Layer to be displayed.
  * remoteUrl: //String// Optional endpoint of MyMap service. Normally not needed
  * callback: //function// As the MyMapLayer is loaded asynchronously, the callback function here allows to execute code after the layer has been loaded. The callback function is provided with a features object containing all the features of the MyMapLayer. 

==== API.showProfile(options) ====
Generate and display a height profile window for a given feature geometry. Used commonly in the callback of the .createMyMapLayer() method. 
<code javascript>
geo.showProfile({ 
   feature:features.features[0],
   renderProfileWindowTo:'profileWindow'
});
</code>
**Options parameters** 
  * feature: //OpenLayers.Feature// A feature object for which to generate the profile.
  * renderProfileWindowTo: //String// Optional: ID of a Div to which to render the window too.

==== API.geocode(options,callback) ====
Calls the geocoder service to geocode an Address. The Address can be given as a string, or as a options object with the constituent address parts.

Also see the following example implementation: //apps.geoportail.lu/exemple_api/exemplesWikiGeoAPI/geoCoding.html
<code javascript>
geoadmin.geocode({
            num: "12",
            street: "Avenue Gaston Diderich",
            zip: "",
            locality:"Luxembourg"
    }, function(success,json) {
        if (success){
            geo.showMarker({
                iconPath: '//apps.geoportail.lu/exemple_api/exemplesWikiGeoAPI/lion.png', //absolute url to image file
                graphicHeight: 35, 
                graphicWidth: 35,
                easting: json[0].easting,
                northing: json[0].northing,
                html: json[0].name,
                title: "Quality of the geocoding: " + json[0].accuracy,
                hover: true //display marker popup on mouseover
            });
        }     
});
</code>

If the address constituent parts are not known, alternatively you can supply a simple address string to be geocoded, replacing the options Object:

<code javascript>
geoadmin.geocode(  "12, Avenue Gaston Diderich, Luxembourg", 
                    function(success,json){ 
                        //...callback processing... 
                    }
);
</code>

  * options: //Options// Address Object containing address parts.
  * address: //String// Alternative to options if address components are not known.
  * callback: //Callback// A callback function which is called when the geocoding request completes. Is passed callback return values (see below).

**Options Parameters**
  * num: //String// Street Number
  * street: //String// Street Name
  * zip: //String// Postcode
  * locality: //String// Village, Town or City

**Callback Return Values**
  * success: //Boolean// True if an address was found. False if not. 
  * result: //Object// Result of the geocoding process. See Result Object example below:

<code javascript>
{
    "count": 1, //Number of results returned
    "results": [
        {
            "ratio": 1, //certainty of geocoding result
            "name": "54,Avenue Gaston Diderich 1420 Luxembourg",
            "easting": 75983.84375,
            "address": "54 Avenue Gaston Diderich,1420 Luxembourg",
            "geom": {
                "type": "Point",
                "coordinates": [
                    75983.84375, //easting given in LUREF
                    75110.6796875 //northing given in LUREF
                ]
            },
            "northing": 75110.6796875,
            "AddressDetails": {
                "street": "Avenue Gaston Diderich",
                "locality": "Luxembourg",
                "zip": "1420",
                "postnumber": "54"
            },
            "matching street": "Avenue Gaston Diderich",
            "accuracy": 8 //Level of accuracy of result: 
                          //8. at house number level 
                          //7. at point of interest level 
                          //6. at street level
                          //5. at locality level
                          //1. at national level (Luxembourg) 
        }
    ],
    "success": true
}
</code>


==== API.reversegeocode(options,callback) ====
Calls the geocoder service to reverse geocode a LUREF coordinate to the closest address. Returns an address JSON object. 
Also see the following example implementation: 

//apps.geoportail.lu/exemple_api/exemplesWikiGeoAPI/reversegeocoding.html

<code javascript>
geoadmin.reversegeocode({
		easting: 90285,
		northing: 81538,
	}, function(success,json) {
		if (success){
			geoadmin.showMarker({
				iconPath: '//apps.geoportail.lu/exemple_api/exemplesWikiGeoAPI/lion.png', //absolute url to image file
				graphicHeight: 35, 
				graphicWidth: 35,
				easting: json[0].easting,
				northing: json[0].northing,
				html: json[0].name,
				title: "Distance from the point: " + Math.round(json[0].distance),
				hover: true //display marker popup on mouseover
			});
		}			
	});
</code>

  * options: //Options// LUREF Coordinate Object.
  * callback: //Callback// A callback function which is called when the reverse geocoding request completes. Is passed callback return values (see below).

**Options Parameters**
  * easting: //Integer// LUREF X axis.
  * northing: //Integer// LUREF Y axis coordinate. 

**Callback Return Values**
  * success: //Boolean// True if an address was found. False if not. 
  * result: //Object// Result of the reverse geocoding process. See Result Object example below:

<code javascript>
{
   "count":1,
   "success":true,
   "results":[
      {
         "distance":4.1557157933240303, //distance to nearest address
         "geom":{
            "type":"Point",
            "coordinates":[
               90288.3515625,
               81540.45703125
            ]
         },
         "name":"11,Rue Aloyse Hoffmann 6913 Roodt-sur-Syre",
         "easting":90288.3515625,
         "northing":81540.45703125,
         "address":"11 Rue Aloyse Hoffmann,6913 Roodt-sur-Syre",
         "matching street":"Rue Aloyse Hoffmann",
         "AddressDetails":{
            "zip":"6913",
            "locality":"Roodt-sur-Syre",
            "id_caclr_street":"5499",
            "street":"Rue Aloyse Hoffmann",
            "postnumber":"11",
            "id_caclr_building":"159419"
         }
      }
   ]
}
</code>