Application Programming Interface
API infopage
 Start 
 Map 
EN ▼

Introduction

The API of map.search.ch lets you embed the interactive map of Switzerland in any website or web-based application. Using the API you can also add custom Points of Interest (POIs) to the map widget. Please read the following step-by-step introduction and learn from the examples. Advanced users will find detailed information in the class reference

First steps

The easiest way to integrate the map is to use the code generator with the link "Embed map" on the left side of the regular map. Just copy & paste the code snippet to your page. No special knowledge of JavaScript is required for this procedure.

Manual integration

This API is designed for people familiar with JavaScript and object-oriented programming concepts. Basic knowledge in HTML and CSS is required as well.

To embed the map you just need to load the API script and create an instance of the map class. The interactive map is bound to an existing container (e.g. a <div>) and adopts it's size and position within the document. The following example shows a map of 500x400 pixels centered in Zurich.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>map.search.ch API Example</title>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <script type="text/javascript" src="http://map.search.ch/api/map.js"></script>
  <script type="text/javascript">
  //<![CDATA[

  var Map = new SearchChMap({ center:"Zuerich" });

  //]]>
  </script>
</head>
<body>
  <div id="mapcontainer" style="width:500px; height:400px; border:2px inset #ccc"></div>
</body>
</html>

The example in detail

First we load the API script from map.search.ch. The desired language can be specified using the parameter named lang. If omitted, the default language of the user's browser will be used.

<script type="text/javascript" src="http://map.search.ch/api/map.js?lang=en"></script>

Now we create an instance of the class SearchChMap and bind it to the container named "mapcontainer" (default name) which should be defined somewhere in the HTML body. The center of the map (Zurich) is specified as a named parameter of the constructor:

<script type="text/javascript"> var Map = new SearchChMap({ center:"Zuerich" }); </script>

The map will start automatically when the page is loaded. That's it. Of course there are more parameters and functions available to control the map. These are fully documented in the class reference. Some will be described in the following examples.

Supported browsers

The API uses JavaScript and DOM functionality and therefore requires a modern browser. The compatibility of the user's browser will be checked automatically but there's no automatic behavior when detecting an incompatible browser. You can also execute this check in your script in order to display warnings or alternative content. The static function SearchChMap.isBrowserCompatible() will return true if the current browser fits the requirements.

if (!SearchChMap.isBrowserCompatible()) alert("Your browser is not ready for map.search.ch");

The following browser are currently supported:

  • Internet Explorer 5.5+ (Windows)
  • Mozilla Firefox 1.0+
  • Mozilla Suite 1.7+
  • Netscape 7.1+
  • Apple Safari 1.2+
  • Opera 8.02+
  • Konqueror 3.2+

Geographic references

To specify the center of the map and to place custom POIs you can use one of the following ways to define a geographic position:

Examples

An easy method to embed the map in your website is to choose an example and modify the settings according to your needs. The following examples only show the relevant part of the JavaScript code. You can download the complete HTML file using the links displayed below each example.

Map showing control UI

UI elements to control the map zoom, view type or to pan the map can either be enabled when instantiating the map class or by using the method set() at runtime.

var Map = new SearchChMap({ center:[679520, 212273], controls:"type,zoom,ruler" });

// Hide map controls except ruler
function hideControls() {
  Map.set({ controls:"ruler" });
}

// Show all map controls
function showControls() {
  Map.set({ controls:"all" });
}

First we create a map with controls for zoom and view type as well as the display of the current scale. The function hideControls() hides all elements except the scale and showControls() switches on all available controls.

Center of the map and movement

The center of the map can be changed at runtime using the method set(). The object method go() will smoothly move the map to the new center and optionally switch to a new zoom level.

var Map = new SearchChMap({ controls:"all" });

// Set new center of the map
function gotoZuerich() {
  Map.set({ center:"Zürich", zoom:8 });
}

// Animated movement to Zürich-Seebach
function movetoSeebach() {
  Map.go({ center:[683371,252535], zoom:2, animated:true })
}

Valid values for the property zoom are listed in the class reference.

Controlling the map with mouse and keyboard

The default settings activate the same modes for user interaction as on map.search.ch. This behavior can be changed individually when creating a map instance or at runtime.

var Map = new SearchChMap({ controls:"all", enable:"dragging,clickzoom,pois" });

function keyboard() {
  Map.disable("dragging,clickzoom");
  Map.enable("keyboard");
}

Using the object methods enable() and disable() the interaction-modes can be activated and deactivated at any time. A list of available modes and their exact name can be found in the class reference.

Showing Points-of-Interest

map.search.ch provides a huge selection of POIs which are organized in several groups. Using the API you can display your own selection of POI categories or a whole group of them. The object methods showPOIGroup() and hidePOIGroup() are available to achieve this.

var Map = new SearchChMap({ container:"mapwidget", center:"Zuerich/Niederdorfstr.", poigroups:"verkehr" });

// Show POI layer with restaurants, bars and cafes
function showRestaurants() {
  Map.showPOIGroup("restaurant,bar,cafe");
}

// Hide all public transport POIs
function hidePublicTransports() {
  Map.hidePOIGroup("verkehr");
}

The desired POI categories can be activated when instantiating the map class using the property poigroups as shown in the example. Any of the POI layers can be turned on and off at runtime. The complete list of POI categories and their grouping can be found in the class reference.

Add custom icons (POIs) to the map

The API is also capable to display your custom Points of Interest on the swiss map. Such icons are created as an instance of the class SearchChPOI (or a derived class) and are added to the map object using it's method addPOI().

var Map = new SearchChMap({ center:"Bern/Kramgasse", circle:false, poigroups:"-" });

// Add a custom POI
Map.addPOI(new SearchChPOI({ center:[600686,199650], title:"Sightseeing",
                             html:"The famous <b>Zytglogge<\/b> tower", icon:"p2.gif" }));

// Create a POI object and attach event listeners
var P1 = new SearchChPOI({ center:[601062,199596], title:"Point of Interest",
                           html:"The mystical ghost house", icon:"p1.gif" });
P1.addEventListener("popupopen", function(e){ window.status = "POI-Box popped up!"; });
P1.addEventListener("popupclose", function(e){ window.status = ""; });
Map.addPOI(P1);

Displaying routes

The route planner of map.search.ch is also avilable in the API. The route is displayed on the map and one can read informations like distance and estimated time from the map object. In order to show the route directions you currently need to link to map.search.ch.

var Map = new SearchChMap({ center:"Zug/Grafenauweg 12", type:"street" });

// Add event handler that gets the new properties after the map changed
Map.addEventListener("change", function(e) {
  if (e.route && e.route != window.current_route) {  // Check if route info has changed
    var routeinfo = Map.get('routeinfo');
    document.getElementById("info").innerHTML =
      "Drive: " + routeinfo.distance + ", ca. " + routeinfo.time +
      ', <a target="_top" href="' + Map.getPermUrl('directions') + '">Directions<\/a>';
    document.getElementById("destination").value = Map.get('from');
    window.current_route = e.route;
  }
});

// handler for the form submit action
function routeFormSubmit(form)
{
  if (form.elements.from.value)
    Map.set({ from: form.elements.from.value, to: form.elements.to.value });
  return false;
}

Set start and destination address of a route by providing the fields from and to to the constructor or when calling set(). Once the route is loaded the event change is triggered. Calling get('routeinfo') retrieves details of the route to display them on the page. Finally link to the directions page of the current route by fetching the according URL from getPermUrl('directions').

Getting coordinates

Our API also allows you the read the current Swiss coordinates when moving the mouse or on mouse clicks within the map. These are passed to the event handler using the fields mx and my of the event object. Please note that this information is only available if the center of the map is either a pair of Swiss coordinates, a city or a street name. If the center is a fully qualified address (including house number), we're not allowed to provide the coordinates due to legal restrictions.

var start, poi;
var Map = new SearchChMap({ center:"Zuerich", circle:false });
Map.addPOI(poi = new SearchChPOI({ html:"Start", icon:"p1.gif" }));
Map.addEventListener("load", function(e) {
  if (e.mx)
    start = [e.mx, e.my];  // Set start first time map is ready
});
Map.addEventListener("mouseclick", function(e) {
  // Check if coordinates provided, left button clicked and zoom at 0.25m per pixel
  var setpoi = e.mx && (e.button == 1) && (Map.get("zoom") <= 0.25);
  if (setpoi)
    poi.set({ center:(start = [e.mx, e.my]) });
  return !setpoi;  // Only zoom if not setting poi
});
Map.addEventListener("mousemove", function(e) {
  if (start && e.mx) { // Check if coordinates provided
    var dx = start[0] - e.mx, dy = start[1] - e.my;
    document.getElementById("info").innerHTML =
      "Distanz vom Start (" + start + "): " + Math.round(Math.sqrt(dx*dx + dy*dy)) + " m";
  }
});

Still want to know more about the API? The class reference comes up with all the details of the API.