search.ch
  1. Introduzione
  2. Primi passi
  3. Riferimenti Geo
  4. Esempi
  5. Riferimento di classe
  6. Condizioni d'utilizzo

Introduzione

map.search.ch API permette di integrare la mappa interattiva della Svizzera in una website oppure in un'applicazione web, con la possibilità di posizionare dei propri Points-of-Interest (POIs). Mediante la qui seguente documentazione di API, potrà acquisire familiarità e apprendere dagli esempi riportati.

Primi passi

La variante più semplice per integrare le mappe interattive è data dalla funzione "integrare mappa" a sinistra, a fianco della mappa normale. Essa può essere utilizzata anche da persone senza conoscenza di JavaScript.

Integrazione manuale

API e la presente documentazione è ideata per persone che hanno familiarità con JavaScript e con la programmazione secondo gli oggetti. Premesse necessarie sono anche le conoscenze basilari di HTML e CSS

Ai fini dell'integrazione della mappa è sufficiente caricare il nostro API-JavaScript e instanziare la classe map, indicando alcuni parametri. L'estratto della mappa viene collegato ad un container esistente (ad es., un <div>) e assume la sua dimensione e posizione nel documento. L'esempio qui di seguito riportato evidenzia una mappa di 500x400 pixel, con al centro Zurigo.

<!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="//map.search.ch/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>

L'esempio, spiegato passo per passo

Come prima cosa occorre caricare l'API-Script di map.search.ch. A titolo opzionale, tramite il parametro è possibile indicare anche la lingua (lang):

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

In un proprio Script-Tag sarà instanziata la classe SearchChMap e legata al container "mapcontainer" (nome default), definito nel body della pagina HTML. In fase di instanziamento sarà anche indicato come parametro il centro della mappa (Zurigo):

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

La mappa si avvia automaticamente, appena la pagina sarà stata completamente caricata. Naturalmente API offre anche altre funzioni per la configurazione e il pilotaggio della mappa. Tali funzioni sono documentate nel Riferimento di classe e sono descritte più dettagliatamente negli esempi.

Browser supportati

API si basa su JavaScript e DOM e ha quindi bisogno di un browser di nuova generazione. La compatibilità del browser utilizzato viene verificata automaticamnte; potrà eseguire tale verifica però anche da sé nel suo script per visualizzare eventuali avvertimenti o alternative. A tale scopo è a disposizione la funzione statica SearchChMap.isBrowserCompatible().

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

Attualmente sono supportati i seguenti browser:

  • Internet Explorer 8+ (Windows)
  • Apple Safari 5+
  • Chrome 12+
  • Mozilla Firefox 10.0+
  • Opera 15+
  • iOS Safari 6.1+
  • Android 3+

Riferimento Geo

Per definire il centro della mappa e per posizionare dei propri POI, può utilizzare i seguenti modi di scrittura:

Esempi

Un modo semplice per integrare la mappa nella sua website è quello di scegliere un esempio riportato e di adattarlo alle sue esigenze. Gli esempi qui di seguito riportati descrivono solo la parte rilevante del JavaScript-Code e non mostrano più tutto il file HTML. Potrà tuttavia scaricare l'esempio di interesse tramite il link e adeguarla.

Mappa con elementi di pilotaggio

Elementi di pilotaggio come zoom, tipo di mappa o scala della mappa possono essere indicati come parametri al costruttore, o attivati/disattivati anche in riferimento al tempo di funzionamento tramite il metodo set().

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

Prima viene creata una mappa con elementi di pilotaggio per zoom, tipo di mappa e scala della mappa. La funzione hideControls() disattiva tutti gli elementi, ad eccezione della scala della mappa, showControls() fa nuovamente apparire tutti gli elementi di pilotaggio disponibili.

Centro della mappa e animazione

Il centro della mappa può essere indicato anche in riferimento al tempo di funzionamento tramite il metodo set(). Il metodo go() muove la mappa in maniera animata verso il nuovo centro e verso il nuovo grado di zoom (optional).

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

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

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

I valori valevoli per il parametro zoom sono riportati nel Riferimento di classe.

Visualizzazione di Points-of-Interest

map.search.ch dispone di numerosi POI, suddivisi in diversi gruppi. Tramite API, potrà visualizzare sulla mappa singole categorie o interi gruppi di POI. A tale scopo sono a disposizione i metodi per oggetto showPOIGroup() e hidePOIGroup().

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

I livelli di POI preferiti possono essere attivati anche già nel costruttore, tramite il parametro poigroups come mostrato nell'esempio. Durante l'esecuzione possono essere attivate e disattivate a piacimento tutti i livelli voluti. La lista completa di tutte le categorie POI e i relativi raggruppamenti sono riportati nel Riferimento di classe.

Posizionare sulla mappa i propri simboli (POI)

API offre anche funzioni per indicare i propri Points-of-Interest sulla sua mappa. I simboli di questo tipo vengono instanziati come oggetto nella classe SearchChPOI (o una classe derivante) e aggiunti all'oggetto della mappa tramite il metodo per oggetti addPOI().

var Map = new SearchChMap({ center:"Bern,Kramgasse", marker: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);

Centrare la mappa intorno i propri simboli

Se i propri simboli vengono posizionati sulla mappa è possibile avere la mappa di determinare automaticamente il livello di zoom e il centro per mostrare tutti i simboli non specificando center e zoom e aggiungendo centerpois:true.

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.gif" }));
Map.addPOI(new SearchChPOI({ center:"Zürich HB", title:"Zürich HB", html:"Zurich main station", icon:"p2.gif" }));
Map.addPOI(new SearchChPOI({ center:"Grossmünster Zürich", title:"Grossmünster", html:"Famous church in Zurich", icon:"p2.gif" }));

Calcolo del percorso

La funzione di pianificazione dei percorsi di map.search.ch può essere utilizzata anche via API. Il percorso viene tracciato sulla mappa e vengono visualizzati la distanza e il tempo di viaggio. Per ottenere la descrizione del percorso occorre innanzitutto collegarsi direttamente a map.search.ch.

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 });
  return false;
}

Il punto iniziale e il punto finale di un percorso vengono indicati al costruttore con i campi from e to o il metodo set(). Una vola caricato il percorso, questo potrà essere rilevato nell'evento change. Con get('routeinfo') vengono visualizzati dettagli quali il tempo di viaggio e la distanza. Per offrire un link alla descrizione del percorso, l'oggetto mappa fornisce con getPermUrl('directions') l'URL completo.

Lettura delle coordinate

L'API permette di leggere le coordinate svizzere in base alla posizione del mouse muovendo e facendo clic con il mouse. Tali coordinate vengono indicate anche nei campi mx e my dell'evento. Queste informazioni vengono messe a disposizione solo se è stata indicata una coordinata, una città o una via come punto centrale della mappa. Se si indica un indirizzo completo come punto centrale della mappa, per motivi legali non siamo autorizzati a fornire queste informazioni.

var start, poi;
var Map = new SearchChMap({ center:"Zürich,Rämistr.101", marker: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("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";
  }
});

Ha voglia di saperne di più? Nel Riferimento di classe trova tutti i dettagli sulle funzioni di API.