search.ch

Einführung

Das map.search.ch API lässt Sie die interaktive Schweizerkarte in eine Website oder eine Web-Applikation einbinden und eigene Points-of-Interest (POIs) darauf positionieren. Machen Sie sich mit der nachfolgenden Dokumentation des APIs vertraut und lernen Sie von den Beispielen.

Erste Schritte

Die einfachste Variante zum Einbinden von interaktiven Karten besteht in der Funktion "Karte einbinden" links neben der normalen Karte. Sie kann auch von Personen ohne JavaScript-Kenntnisse eingesetzt werden.

Manuelle Einbindung

Das API und diese Dokumentation richtet sich an Personen, die mit JavaScript und objektorientierter Programmierung vertraut sind. Grundkenntnisse in HTML und CSS sind ebenfalls Voraussetzung.

Zur Einbindung der Karte genügt das Laden unseres API-JavaScripts und das Instanziieren der Map-Klasse unter Angabe einiger Parameter. Der Kartenausschnitt wird an einen bestehenden Container (z.B. ein <div>) gebunden und übernimmt dessen Grösse und Position im Dokument. Das nachfolgende Beispiel zeigt eine Karte 500x400 Pixel gross, mit Zentrum Zürich.

<!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>search.ch/map/ API Example</title>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <script type="text/javascript" src="//search.ch/map/api/map.js"></script>
  <script type="text/javascript">
  //<![CDATA[

  var map = new SearchChMap({ center:"Zürich" });

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

Das Beispiel Schritt für Schritt erklärt

Zuerst wird das API-Script von map.search.ch geladen. Optional kann noch die Sprache über den Parameter lang angegeben werden:

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

In einem eigenen Script-Tag wird die Klasse SearchChMap instanziiert und an den Container "mapcontainer" (Default-Name) gebunden, der im Body der HTML-Seite definiert ist. Beim Instanziieren wird auch gleich das Zentrum der Karte (Zürich) als Parameter angegeben:

<script type="text/javascript"> var map = new SearchChMap({ center:"Zürich" }); </script>

Die Karte startet automatisch, wenn die Seite vollständig geladen wurde. Natürlich bietet das API noch weitere Funktionen zur Konfiguration und Steuerung der Karte. Diese sind in der Klassenreferenz dokumentiert und werden in den Beispielen näher beschrieben.

Geo-Referenzierung

Zur Bestimmung des Kartenzentrums und zur Positionierung eigener POIs können Sie folgende Schreibweisen verwenden:

Beispiele

Eine einfache Art, die Karte in Ihre Website einzubinden ist, ein bestehendes Beispiel auszusuchen und nach Ihren Bedürfnissen anzupassen. In den folgenden Beispielen wird nur noch der relevante Teil des JavaScript-Codes beschrieben und nicht mehr die ganze HTML-Datei angezeigt. Sie können das jeweilige Beispiel jedoch über den angefügten Link herunterladen und anpassen.

Karte mit Steuerelementen

Steuerelemente wie Zoom, Kartentyp oder Kartenmassstab können entweder als Parameter dem Konstruktor angegeben werden oder über die Methode set() auch zur Laufzeit ein- resp. ausgeblendet werden.

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" });
}

Zuerst wird eine Karte mit Steuerelementen für Zoom und Kartentyp sowie Kartenmassstab erstellt. Die Funktion hideControls() blendet alle Elemente bis auf den Kartenmassstab aus, showControls() lässt alle verfügbaren Steuerelemente erscheinen.

Kartenzentrum und Animation

Das Kartenzentrum kann auch zur Laufzeit über die Methode set() neu gesetzt werden. Die Methode go() bewegt die Karte animiert zum neuen Zentrum und auf die neue Zoomstufe (optional).

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

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

// Animated movement to Zürich-Seebach
function movetoSeebach() {
  map.go({ center:[683371,252535], zoomlevel:15 })
}

Die gültigen Werte für den Parameter zoom sind in der Klassenreferenz aufgeführt.

Anzeige von Points-of-Interest

map.search.ch verfügt über eine grosse Auswahl an POIs, die in verschiedene Gruppen unterteilt sind. Via API können Sie einzelne POI-Kategorien oder ganze Gruppen auf der Karte anzeigen lassen. Dazu stehen die Objektmethoden showPOIGroup() und hidePOIGroup() zur Verfügung.

var map = new SearchChMap({ container:"mapwidget", center:"Zürich,Niederdorfstr.10", 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");
}

Die gewünschten POI-Ebenen können auch bereits im Konstruktor über den Parameter poigroups aktiviert werden, wie im Beispiel gezeigt. Zur Laufzeit können beliebige Ebenen ein- und ausgeblendet werden. Die komplette Liste aller POI-Kategorien und deren Gruppierung finden Sie in der Klassenreferenz.

Eigene Symbole (POIs) auf der Karte positionieren

Das API bietet auch Funktionen an, eigene Points-of-Interest auf Ihrer Karte anzuzeigen. Solche Symbole werden als Objekt der Klasse SearchChPOI (oder einer abgeleiteten Klasse) instanziiert und mittels Objektmethode addPOI() dem Kartenobjekt hinzugefügt.

function info(html) {
  document.getElementById("info").innerHTML = html;
}

var map = new SearchChMap({ center:"Bern,Kramgasse", marker:false, poigroups:"-" });

p1 = new SearchChPOI({
  center:[601062,199596],
  title:"Point of Interest",
  html:"The mystical ghost house",
  icon:"p1.png"
});
p2 = new SearchChPOI({
  center:[600686,199650],
  title:"Sightseeing",
  html:"The famous <b>Zytglogge<\/b> tower",
  icon:"p2.png"
});
p3 = new SearchChPOI({
  center:[600500,199800],
  title:"Draggable",
  html:"Drag this POI wherever you want",
  icon:"p4.png",
  draggable:true
});
p1.addEventListener("popupopen",  function(e){ info("POI-Box popped up!"); });
p1.addEventListener("popupclose", function(e){ info(""); });
p3.addEventListener("dragstart",  function(e){ info("dragstart: " + e.mx + "," + e.my); });
p3.addEventListener("dragend",    function(e){ info("dragend: "   + e.mx + "," + e.my); });

map.addPOI(p1);
map.addPOI(p2);
map.addPOI(p3);

Karte um eigene Symbole (POIs) zentrieren

Wenn eigene POIs auf der Karte angezeigt werden, kann die Karte durch weglassen von center und zoom aber setzen von centerpois:true automatisch den Ausschnitt so wählen, dass alle Punkte sichtbar sind.

var map = new SearchChMap({ centerpois:true, marker:false, poigroups:"-" });

// Add custom POIs, map will be centered around them
map.addPOI(new SearchChPOI({ center:"Förrlibuckstr. 62", title:"search.ch", html:"Office of search.ch", icon:"p1.png" }));
map.addPOI(new SearchChPOI({ center:"Zürich HB", title:"Zürich HB", html:"Zurich main station", icon:"p2.png" }));
map.addPOI(new SearchChPOI({ center:"Grossmünster Zürich", title:"Grossmünster", html:"Famous church in Zurich", icon:"p2.png" }));

Routen berechnen

Die Routenplaner-Funktion von map.search.ch kann ebenfalls via API genutzt werden. Die Route wird auf der Karte eingezeichnet und es können Distanz sowie Reisezeit ausgelesen werden. Für die Wegbeschreibung muss vorerst direkt auf map.search.ch verlinkt werden.

var map = new SearchChMap({ center:"Zürich,Förrlibuckstr. 62", 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, routemode:form.elements.routemode.value });
  return false;
}

Start- und Zielpunkt einer Route werden mit den Feldern from und to dem Konstruktor oder der Methode set() angegeben. Ist die Route fertig geladen, kann dies im Event change detektiert werden. Mit get('routeinfo') werden Details wie Reisezeit und Distanz angeboten. Um einen Link auf die Wegbeschreibung anzubieten, liefert das map-Objekt mit getPermUrl('directions') die vollständige URL dazu.

Koordinaten auslesen

Das API bietet die Möglichkeit, bei Mausbewegungen und Klicks die Schweizer Landeskoordinaten der Mausposition auszulesen, diese werden in den Feldern mx und my des Events mitgegeben (mx=E, my=N).

var start, poi;
var map = new SearchChMap({ center:"Zürich,Rämistr.101", marker:false });
map.addPOI(poi = new SearchChPOI({ html:"Start", icon:"p1.png" }));
map.addEventListener("load", function(e) {
  if (e.mx)
    start = [e.mx, e.my];  // Set start first time map is ready
});
map.addEventListener("contextmenu", function(e) { // move start on right click or long press on touchscreens
  if (e.mx)
    poi.set({ center:(start = [e.mx, e.my]) });
});
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";
  }
});

Lust auf mehr? In der Klassenreferenz finden Sie alle Details zum Funktionsumfang des APIs.