The MapAPI 1.0 is deprecated. Please use the new MapAPI 1.1.

Frequently Asked Questions

Getting started

What is the mapsuite Javascript API?
Why should I use the mapsuite Javascript API?
What browsers are supported by the API?
Does the API support mobile devices?
Does the API support HTTPS URLs?
Do I need server hardware to host a mapping application?
What is a VNR and a PNR, and how do I get them?
How can I get help to use the API on my site?
How do I report a bug?

Usage and Examples

How do I include the API in my application?
How can I change the mouse wheel function?
How can I limit the minimum and maximum map zoom?
How can I customize the graphics for the zoom slider and other controls?
How can I display my own POI icons on the map?
How can I use features from the Kartenverzeichnis-API in my existing MapAPI application?
I want to display multiple markers on the map. How can I choose the map view so that all markers are visible?
Can I display the routes via IWGraphics and affect the appearance (color, line thickness, transparency)?
My geodata are in a different projection. Can I still use it with the mapsuite API?
How many hits can I get up at reverseGeocodeByHits? What is the maximum radius at reverseGeocodeByRadius?

Map Types and Data

Which countries are covered by the API?
Which map types are supported by the mapsuite API?
Is it possible to configure the appearance of the roadmap?
How can I configure the categories and appearance of the POIs in the map?
What are dynamic POIs and what types are available?

Performance Optimization

How can I speed up tile loading?
How can I speed up map movement?
Can I speed up the display of markers like search hits?

Object-oriented Programming in Javascript

Do I have to use an object-oriented design for my application?
How does OOP it work in Javascript?
How do I extend MapAPI classes?

Answers

Getting started

•  
• Top of page
• What is the mapsuite Javascript API?
• By using the mapsuite Javascript API you can embed maps in your websites both for desktop and mobile browsers. You can control the visible section of the map by setting a coordinate or address, define user interaction with the map, add layers with Points of Interest (POIs), search hits or areas, calculate routes and visualize them on the map, and much more. Have a look at our tutorial for a brief overview of the API features.
  
  

  The API and implementation is plain Javascript, so map applications created by the MapAPI run in all modern browsers without plugins, addons etc. All you need to start is basic Javascript knowledge.

•  
• Top of page
• Why should I use the mapsuite Javascript API?
• There are the following reasons:
  • No hosting or special server infrastructure required
  • Start creating mapping applications without prior knowledge in mapping technologies
  • Additional GIS-services like routing, geocoding, and coordinate projection
  • Lots of powerful GUI controls and utility functions
  • Easily extendable, e.g. to implement custom controls
  • Configurable behavior and appearance of Points of Interest (POIs)
  • Freely customizable map style
  • Easy integration into existing web applications
•  
• Top of page
• What browsers are supported by the mapsuite API?
• Generally you should be able to use any current desktop browser. The infoware mapsuite Javascript API is tested in these browsers:

  Browser	Version
  Mozilla Firefox	3.0+
  Apple Safari	3.1.2+
  Google Chrome	Current version
  Opera	10.0+
  Microsoft Internet Explorer	6.0+

  Starting with version 1.1, mobile devices like smart phones and tablets are supported, too. On Android both the internal browser and Chrome are supported.
•  
• Top of page
• Does the API support mobile devices?
• No, this is not possible with MapAPI 1.0 but possible with MapAPI 1.1.
•  
• Top of page
• Does the API support HTTPS URLs?
• No, this is not possible with MapAPI 1.0 but possible with MapAPI 1.1.
•  
• Top of page
• Do I need server hardware to host a mapping application?
• The API is usually hosted on our servers, so no more hardware resources are required on your side. All our servers are hosted in Germany to provide fast access in Europe.
  
  

  However if you want to use your own server infrastructure, please contact us at mapapi@infoware.de.

•  
• Top of page
• What is a VNR and a PNR, and how do I get them?
• VNR and PNR are numbers used to identify a customer and product. Please contact us to get a valid VNR and PNR for your application/website.
•  
• Top of page
• How can I get help to use the API on my site?
• There is a lot of description available here. If you still have questions please send us an email at mapapi@infoware.de. Please feel free to contact us if you need any specific feature of the API which isn't available yet. We will see what we can do for you.
•  
• Top of page
• How do I report a bug?
• Just send us an e-mail to mapapi@infoware.de. Please include the following details:
  • A detailed description how to reproduce the bug if possible
  • System details (OS and browser including version)
  • The URL of the API you are using
  • The URL of your application if possible
  • A screenshot if necessary

Use and Examples

•  
• Top of page
• How do I include the API in my application?
• The easiest way is to include the complete API as one script (for loading modules see the next section): Just insert

  						<script type="text/javascript" src="<server-url>/MapAPI-1.0/js/mapping.js?vnr=[yourVNR]&pnr=[yourPNR]"></script>
  					

  into your page and start using the API after an onload event (or $(document).ready(yourInitHandler) when using jQuery).
•  
• Top of page
• How can I change the mouse wheel function?
• Based on your requirement, you may want to override the default mouse wheel functionality. We have provided two important functions. Page up / down and zoom maps. To change the zoom direction we give the following simple example:

  map.getOptions().setMouseWheelAction(IWMapOptions.CONTROL_NONE);
  var adapter = new IWMouseWheelAdapter(map, map.getContainer());
  IWEventManager.addListener(adapter, 'onmousewheel', function(event)
  {
  	if(event.delta < 0)
  	{
  		map.zoomIn();
  	}
  	else
  	{
  		map.zoomOut();
  	}
  }); 

•  
• Top of page
• How can I limit the minimum and maximum map zoom?
• In the mapsuite API, the functions setMinLevel, setMaxLevel and setPreferredLevel are provided. Below we show an example that limits down and up zoom level. The last line (setCenter) provides for a correction, if you are just outside the new zoom range.

  map.getCurrentMapType().setMinLevel(5);
  map.getCurrentMapType().setMaxLevel(10);
  map.getCurrentMapType().setPreferredLevel(8);
  map.setCenter(map.getCenter(), map.getZoom());

•  
• Top of page
• How can I customize the graphics for the zoom slider and other controls?
• Please refer points 5.3 (Create your own controls ) and 5.4 (Customize existing controls) from our mapsuite API tutorial Chapter 5 You can also use your own pictures of gif format.
•  
• Top of page
• How can I display my own POI icons on the map?
• The POI Symols are graphics of gif format and can be created by yourself with little skill and a photo editing program. Simply contact us at mapapi@infoware.de.
•  
• Top of page
• How can I use features from the Kartenverzeichnis-API in my existing MapAPI application?
• Using the Kartenverzeichnis-API in a MapAPI application is easy. Just first import the mapsuite API and then the Kartenverzeichnis-API in your page as seen in our example. As the main class SearchableMap extends IWMap, all your existing code will run without changes after switching to SearchableMap. Just have a look at our test application on how to add more features.
•  
• Top of page
• I want to display multiple markers on the map. How can I choose the map view so that all markers are visible?
• Below is a code snippet. For more details, please have a look at map suite JavaScript API - Part 1 Programmer's Guide → IWBounds.

  		var nw = new IWCoordinate(6.85465, 51.08357, IWCoordinate.WGS84).toMercator(); // north-west of Cologne	
  		var se = new IWCoordinate(7.20694, 50.64929, IWCoordinate.WGS84).toMercator();	// south-east of Bonn
  		var extCoor = new IWCoordinate(7.14512, 50.70001, IWCoordinate.WGS84).toMercator();  
  		var myBounds = new IWBounds(nw,se);
  		myBounds.extendBy(extCoor);			
  		map.setCenter(myBounds.getCenter(), map.getBoundsZoomlevel(myBounds));

  In the above Example extCoor is one of the chosen point and lies within the IWBounds and is used here to illustrate the use of the method extendBy (). The IWBounds may be extended with extendBy() as often as needed. If a new coordinate lies outside the IWBounds, then the rectangle is enlarged and possibly a different zoom level is chosen.
  
  In the case of a route, you can proceed as follows:

  map.setCenter(route.getBounds().getCenter(), map.getBoundsZoomlevel(route.getBounds()));

•  
• Top of page
• Can I display the routes via IWGraphics and affect the appearance (color, line thickness, transparency)?
• For the server-side-generated no possibility of manipulation is provided. But the line width is always adapted to the scale of the map. Transparency can be adjusted via style property: opacity. Note here that there are differences between the available browsers.
•  
• Top of page
• My geodata are in a different projection. Can I still use it with the mapsuite API?
• Most probably, you can. Mercator and WGS84 coordinates can be passed directly at the instantiation of IWCoordinate objects. Several other projections can be converted to Mercator via IWProjectionClient class. For details, please have a look at our tutorial Chapter 8.
  
  As of now we support following projections and conversions.
  
  

  projection	conversion	projection
  Mercator	↔	WGS 84
  LCC Europe	↔	WGS 84
  LCC Europe	→	LCC Germany Bessel AKA LCC TAO
  LCC Germany Bessel	→	LCC Europe
  LCC Germany Bessel	→	Mercator
  WGS84	→	UTM 32

  For more details, please have a look at map suite JavaScript API - Part 1 Programmer's Guide → IWProjectionType.
  
  If your desired projection does not exist, simply contact us at mapapi@infoware.de.
•  
• Top of page
• How many hits can I get up at reverseGeocodeByHits? What is the maximum radius at reverseGeocodeByRadius?
• The Server can return up to 256 results. If you need a bigger hit list for your purposes, you have to send multiple queries and then merge the results later.
•  

Map Types and Data

•  
• Top of page
• Which countries are covered by the API?
• The MapAPI can be used with various providers of geodata, covering Germany, european and worldwide countries. Please contact us to find the best data source for your requirements.
•  
• Top of page
• Which map types are supported by the mapsuite API?
• As of now mapsuite API supports roadmap, air, hybrid and bird's eye views. The map type is always set by a call to IWMap.setCenter(). To set a new map type, you can use this code snippet:

  					var type = map.getOptions().getMapTypeByName('hybrid');
  					map.setCenter(map.getCenter(), map.getZoom(), type);
  				

  For more details, please have a look at the documentation of IWMapType.

•  
• Top of page
• Is it possible to configure the appearence of the roadmap?
• Yes, if you host your own map servers (which are part of the mapsuite) the layout can be configured in a very flexible way. We provide an application called MapStyler which may be used to design the map layout. Please contact us for more information.
•  
• Top of page
• How can I configure the categories and appearance of the POIs in the map?
• The POIs are managed on backend servers. The selection of POI types, the appearance (i.e. the symbols), the zoom levels on which POIs are visible and more can be configured per application by a web application called MapCMS. Please contact us for details.
•  
• Top of page
• What are dynamic POIs and what types are available?
• We have several types of dynamic POIs available with either dynamic content or dynamic coordinates (or both). Examples are traffic information, weather, filling stations, parking grounds and cinemas. Please contact us for more information.

Performance Optimization

•  
• Top of page
• How can I speed up tile loading?
• The map is served as an image cut into several tiles. The browser aligns the tiles together back to a complete map. The tiles have to be loaded from the tile server. The number of tiles loaded depends on the screen size on the client and the number of border tiles which should be loaded additionally.
  
  

  This number is usually greater than 20 on desktop machines. Standard browsers of today allow 6 parallel connections to one server; or to be more precise, to one subdomain of a domain. The other requests are queued. So the loading speed can be optimized by loading the tiles from different servers, and thus creating more parallel connections. For details please see Parallelize downloads across hostnames.

  The MapAPI allows downloads from multiple servers. The load is spread equally among these servers. One tile is loaded always from the same server, so caching within the browser is fully used. To use multiple servers, or multiple subdomains on one server / server pool, you can configure aliases in the XML based MapAPI config file. For a MapAPI hosted on our servers, this already is configured.

•  
• Top of page
• How can I speed up map movement?
• The new MapAPI 1.1 uses new CSS3 techniques to move tiles on the map. It is a good idea to upgrade to this API.
•  
• Top of page
• Can I speed up the display of markers like search hits?
• The MapAPI offers two ways to draw markers on the map. The base class IWOverlay can be used to attach DOM objects to a coordinate on the map. Everytime the map is moved or zoomed it updates these overlays. An example is the class IWMarker, but of course you can implement own classes which extend IWOverlay. Every overlay you add to the map is a DOM object, so adding lots (e.g. thousands) of these objects will result in slower map movements.
  
  

  In this cases you should think of using layers. The markers in these layers are stored on the server and rendererd to a single image every time the map is moved. This is much faster for large amounts of markers. Examples for layers are POIs and routing layers.

  For more detailed descriptions see the chapters on overlays and shapes in the tutorial.

  	Overlays	Layers
  numer of markers	limited (depends on target plattform)	huge amounts (managed on the server)
  flexibility	high (own implementations with HTML, JS, CSS)	low (static images only)
  user interaction	fast (Javascript events)	slow (round-trip-time to server)

Object-oriented Programming in Javascript

•  
• Top of page
• Do I have to use an object-oriented design for my application?
• No, you don't have to. All features of the MapAPI can be used from procedural applications as well (unless you want to extend MapAPI classes, of course).
  
  

  Hoewever, we suggest an object-oriented approach for complex applications as it leads to the same advantages as in other programming languages, like an improved reusability, readability, testability and other benefits.

•  
• Top of page
• How does OOP it work in Javascript?
• If you are used to object-oriented languages like C++ or Java, OOP in Javascript won't look familiar to you. For example, there are no classes in Javascript but prototype-based inheritance. Here is a brief overview how OOP can be done with objects, constructor functions and prototypes. For a more detailed introduction see this article on MDN.
  
  

  Step 1: Using constructor functions

  The usual way to create an object in Javascript is var x = new Object(); (or the shorter notation var x = {};). The first step to introduce a "class" is to write a constructor function like this:

  					function Programmer(name)
  					{
  						this.name = name;
  						this.caffeine = 0;
  					}
  				

  When a constructor function is called with new, the newly created object becomes accessible in the function by the name this. Now you can create instances of your class by writing var x = new F();. The result is an object (typeof x will return 'Object') with the properties x and y.

  Step 2: Adding methods to your class

  As functions can be assigned to any variable, you can add functions as properties to your class to add methods. Again, use this to access the object and its properties from these functions:

  					function Programmer(name)
  					{
  						this.name = name;
  						this.caffeine = 0;
  						
  						this.work = function()
  						{
  							if (this.caffeine > 0)
  							{
  								console.log(name + ' produces some code');
  							}
  							else
  							{
  								throw name + ' is out of coffee!';
  							}
  						}
  						
  						this.drinkCoffee = function()
  						{
  							console.log(name + ' drinks coffee');
  							this.caffeine += 5;
  						}
  					}
  					
  					var codeMonkey = new Programmer('Code monkey'); // now create an instance and use it
  					try
  					{
  						codeMonkey.work();
  					}
  					catch (e)
  					{
  						codeMonkey.drinkCoffee();
  						codeMonkey.work();
  					}
  				

  Step 3: Using the prototype

  Assigning the methods in the constructor has two main disadvantages: The constructor becomes more complex (thus making it slower) and the methods have to be assigned to each object which is instantiated from the class (imagine you need a lot of code monkeys...). A more elegant solution is to use the prototype of the constructor function instead:

  					function Programmer(name)
  					{
  						this.name = name;
  						this.caffeine = 0;
  					}
  					
  					Programmer.prototype.work = function()
  					{
  						if (this.caffeine > 0)
  						{
  							console.log(name + ' produces some code');
  						}
  						else
  						{
  							throw name + ' is out of coffee!';
  						}
  					}
  					
  					Programmer.prototype.drinkCoffee = function()
  					{
  						console.log(name + ' drinks coffee');
  						this.caffeine += 5;
  					}
  				

•  
• Top of page
• How do I extend MapAPI classes?
• There are some abstract base classes in the MapAPI which are meant to be extended. For example you can extend IWControl to implement your own controls or IWWindowOverlay to create your own bubbles to display content on the map. Other classes can be extended as well, for example think of an extended version of IWCoordinate which supports your custom coordinate projection.
  
  

  To extend a class you have to do two steps: Make your constructor call the constructor of the base class, and create the prototype of your constructor as an instance of the base class. Let's have a look at this example:

  					function CustomCoordinate(x, y, projection)
  					{
  						// TODO calculate lat, lon from x, y
  						
  						IWCoordinate.call(this, lon, lat, IWCoordinate.WGS84); // (1)
  					}
  					
  					CustomCoordinate.prototype = new IWCoordinate(); // (2)
  					
  					CustomCoordinate.prototype.toCustomProjection = function()
  					{
  						var wgs84 = this.toWGS84();
  						var lat = wgs84.getY();
  						var lon = wgs84.getX();
  						
  						// TODO calculate x, y from lat, lon
  						
  						return new IWCoordinate(x, y, 'CustomProjection');
  					};
  				

  This class extends IWCoordinate to support a custom projection. To do this the lines marked with (1) and (2) are important. The first one calls the constructor IWCoordinate on the object "this", i.e. the object which is created by the CustomCoordinate constructor. For details see the documentation of Function.call().

  The line marked with (2) makes the prototype of CustomCoordinate an instance of IWCoordinate, thus inheriting all methods and constants defined for IWCoordinate. Now you can use your custom coordinate class as replacement for IWCoordinate, i.e. map.setCenter(new CustomCoordinate(1234, 5678)); will center the map on the WGS84 position corresponding to the coordinate (1234, 5678) in your custom projection.

Copyright 2007-2009 infoware GmbH, mapsuite Javascript Tutorial