úterý 2. září 2008

Google Maps API

Google Maps (maps.google.com) nabízí možnost zobrazit mapu. Zdánlivě jednoduchá funkce se s Google Maps rozšiřuje na množství možností, mezi které patří přiblížení (nejmenší je celý svět, největší je naopak úroveň ulic) a plynulý posun po mapě. Mapa není jen klasická, ale k dispozici je i satelitní („fotografie z výšky“) a mapa terénu.

V tomto článku si ukážeme jak takovou mapu přidat na vlastní stránky.

Pro používání Google Maps API stačí základní znalost JavaScriptu a základy objektově orientovaného programování.

Před samotným použitím Google Maps API na stránkách je potřeba získat API klíč. Ten lze zdarma získat na code.google.com/apis/maps/signup.html.
Podmínkou je mít účet u Google (Google account, také zdarma, možno vytvořit při získávání API klíče). Klíč je vytvořen po odsouhlasení podmínek použití a zadaní domény (resp. doména/adresář, je možné získat klíč i pro „localhost“ nebo ip adresu) na které poběží stránka s mapou.



Tlačítko „Generate API Key“ vygeneruje API klíč

Poznámka k použití mapy:
Google nabízí Google Maps zdarma a Google Maps Enterprise (placená verze). Google Maps zdarma lze libovolně použít, ale stránka, kde je mapa umístěna, musí být přístupná všem návštěvníkům (nesmí jít tedy o stránku pro jejíž prohlížení je nutná registrace/přihlášení apod.)

Na následujících řádcích budeme používat API pomocí Google AJAX API Loader (co to je si můžete přečíst v článku Google AJAX API). Budeme tedy používat namespace google.maps. Druhou možností je používání přímo API Google Maps. Všechny metody zůstavají stejné, jediným rozdílem je jejich volání. Příkladem může být vytvoření mapy:

Google Maps API:
var mapa = new GMap2(document.getElementById("mapa"));

Google Maps API přes AJAX Loader:
var mapa = new google.maps.Map2(document.getElementById("mapa"));

Úvodem

Google Maps API používá javascript. Samotná mapa se vykresluje vždy jako několik obrázků (PNG soubor pro klasickou mapu a JPG soubor pro satelitní mapu, obojí o velikosti 256 x 256 pixelů) na zadané místo na stránce (zpravidla mezi <div></div> html značky).

Před vložením mapy na stránku, musíme načíst samotné mapy. To provedeme načtením obecného API (zde je nutné vložit API klíč):
<script type="text/javascript" src="http://www.google.com/jsapi?key=API_KLIC"></script>

Případně:
<script type="text/javascript" src="http://www.google.com/jsapi?key=API_KLIC&
hl=de"></script>

Kde je možné určit jazyk. Aktuální dostupné lokalizace jsou k dispozici na:
code.google.com/support/bin/answer.py?answer=60737&topic=12267

Nyní je potřeba načíst API Google Maps. To se provede zavoláním metody google.load.
Metoda vyžaduje dva parametry: jméno API (tady "maps") a verzi (stabilní verze 2, je
možné použít i 2.x, kde x nahrazuje požadovanou vývojovou verzi, aktuální verze je k dispozici na code.google.com a groups.google.com/group/Google-Maps-API):


<script type="text/javascript">
google.load("maps", "2");
</script>


Je možné ještě vložit volitelné parametry: google.load("maps", "2", PARAMETRY);
Parametrem může být např. nastavení lokalizace (locale):
google.load("maps", "2", {"locale" : "ja_JP"});

Vkládáme mapu

Na následujícím kódu si ukážeme vložení základní mapy:

Načtení obecného API:
<script type="text/javascript"
src="http://www.google.com/jsapi?key=API_KLIC"></script>

Načtení API Google Maps
<script type="text/javascript">
google.load("maps", "2");

Vytvoření funkce, která vytvoří mapu:
function GoogleMAPA() {
Vytvoření samotné mapy (objekt mapa):
var mapa = new google.maps.Map2(document.getElementById("mapa"));
Nastavení středu mapy pomocí LatLng(šířka, délka) a úrovně přiblížení (zde 7) :
mapa.setCenter(new google.maps.LatLng(37.4419, -122.1419), 7);
Uzavření funkce, její zavolání a uzavření skriptu:
}
google.setOnLoadCallback(GoogleMAPA);
</script>

Celý kód, včetně html tagů:


<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=windows-1250">
<title>Google Maps API - ukázka</title>

<script type="text/javascript"
src="http://www.google.com/jsapi?key=API_KLIC"></script>
<script type="text/javascript">
// nacteni API Google Maps
google.load("maps", "2");
function GoogleMAPA() {
// vytvoreni samotne mapy
var mapa = new google.maps.Map2(document.getElementById("mapa"));
// jeji nastaveni - stredu a urovne priblizeni
mapa.setCenter(new google.maps.LatLng(49.79545,15.732422), 7);
}
// zavolani funkce pro vytvoreni mapy
google.setOnLoadCallback(GoogleMAPA);

</script>
</head>

<body>
<!-- Vložení mapy do pole 500 x 500 pixelů -->
<div id="mapa" style="width: 500px; height: 500px"></div>
</body>

</html>


Pokud kód zkopírujete na web (se správným API klíčem) a otevřete v prohlížeči,
zobrazí se Vám
Google mapa v okně o rozměrech 500 x 500 pixelů.

Výsledkem by měla být takováto mapa:

 

Možnosti Google Maps API

V dalším textu se seznámíme s možnostmi Google Maps API.

Kompatibilita prohlížeče
Pokud chcete používat mapu na Vaší stránce, doporučujeme před jejím vytvořením
zkontrolovat, zda prohlížeč mapu zobrazí. Za tímto účelem je možné použít metodu
google.maps.BrowserIsCompatible()

Např.:
function GoogleMAPA() {
if (google.maps.BrowserIsCompatible()) {
var mapa = new google.maps.Map2(document.getElementById("mapa"));
mapa.setCenter(new google.maps.LatLng(49.79545,15.732422), 7);}
else document.write("Vypadá to, že Váš prohlížeč nepodporuje Google Maps!");
}
google.setOnLoadCallback(GoogleMAPA);


Zeměpisná šířka a délka
V příkladech výše se pro používá objekt LatLng pro určení, kde má vykreslená mapa střed. Objekt LatLng lze vytvořit následovně:
var SD = google.maps.LatLng(ZEMĚPISNÁ ŠÍŘKA, ZEMĚPISNÁ DÉLKA);

Tento objekt používá i mnoho jiných metod jako parametr (např.: google.maps.marker
či Info Window, viz. níže). ZEMĚPISNÁ ŠÍŘKA a ZEMĚPISNÁ DÉLKA jsou reálná čísla.

Typ mapy
Na začátku jsme zmínili, že Google Maps nemusí zobrazovat jen „obyčejnou“ mapu, ale že k dispozici jsou i satelitní a další mapy.  Typ zobrazované mapy lze snadno nastavit metodou setMapType(Typ_mapy);.
Typy map k dispozici jsou:
  • G_NORMAL_MAP – klasická mapa
  • G_SATELLITE_MAP – Satelitní mapa
  • G_HYBRID_MAP – Kombinace klasické a satelitní mapy
  • G_PHYSICAL_MAP – Mapa terénu
Navíc je k dispozici i pole všech map: G_DEFAULT_MAP_TYPES
Příklad:  mapa.setMapType(G_SATELLITE_MAP);

Informace
Do mapy je možné vložit jednoduché okénko s informací. Okno lze vložit pomocí metody:
openInfoWindow(KDE, CO);
Parametr KDE je objekt LatLng, CO je html kód – obsah okénka
Příklad:
mapa.openInfoWindow(mapa.getCenter(),
document.createTextNode("Hello, world"));

Další příklad naleznete v části Overlay níže.

Užitečné metody
Zde uvádíme některé metody, které se mohou hodit při vytváření vlastní mapy:
setCenter(LatLng); – nastaví střed zobrazené mapy na zadané koordináty (parametrem je objektLatLng)
panTo(LatLng); – změní střed mapy na zadané koordináty (skokem nebo pohybem)
getBounds(); – vrací hranice aktuálně zobrazené části mapy
getZoom(); – metoda vrací aktuální hodnotu přiblížení (rozsah: 0 (minimum, tj. svět) až 19 (maximum))
disableDragging(); – použití metody zakáže posouvání mapy

Události
Stejně jako je možné vytvářet mapu, je možné sledovat, co se s mapou děje. Pokud chcete události používat, jako první krok, je potřeba přidat metodu pro sledování událostí nad objektem:
google.maps.Event.addListener(objekt, co, funkce);

Parametry jsou:
Objekt – objekt, jehož události se sledují
Co – co se sleduje, např.: „click“ značí kliknutí na mapě
Funkce – funkce, která se spustí při události

Odebrání
Opakem této funkce je „vypnutí“ sledování událostí nad objektem. Občas se může hodit, že jakmile proběhne událost a na ni naváže Vámi definovaná akce, již nechcete, aby se akce opakovala.
Zrušení sledování se provede metodou:
Google.maps.Event.removeListener(sledovac);

Ovládací prvky
Stejně jako na maps.google.com, i na Vaši mapu můžete přidat ovládací prvky. Můžete si vybrat z následujících ovládacích prvků:
  • GLargeMapControl – panel pro ovládání mapy (posun a úroveň přiblížení)
  • GSmallMapControl – tlačítka pro posouvání mapy a nastavení úrovně přiblížení
  • GSmallZoomControl – tlačítka „+“ a „-“ pro ovládání úrovně přiblížení
  • GScaleControl – měřítko mapy
  • GOverviewMapControl – minimapa v rohu mapy
  • GMapTypeControl – tlačítka umožňující přepínaní mezi typy mapy
  • GHierarchicalMapTypeControl - tlačítka umožňující přepínaní mezi typy mapy
Prvek lze na mapu pomocí následující metody:
addControl(CO);
Např.: mapa.addControl(new GLargeMapControl());
Odstranění prvku naopak provádí metoda removecontrol(CO);

Vázání událostí a metod
Občas je potřeba svázat události s vlastní funkcí. K tomuto účelu slouží:
google.maps.Event.bind();

Příklad (použití událostí, přidání a odebrání ovládacího prvku a vázání):

<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=windows-1250">
<title>Google Maps API - ukázka</title>

<script type="text/javascript"
src="http://www.google.com/jsapi?key=API_KLIC"></script>
<script type="text/javascript">
google.load("maps", "2");

function GoogleMAPA() {
// kontrola kompatibility
if (google.maps.BrowserIsCompatible()) {
// vytvoreni mapy
this.mapa = new google.maps.Map2(document.getElementById("mapa"));
// nastaveni mapy
this.mapa.setCenter(new google.maps.LatLng(49.79545,15.732422),7);
this.mapa.setMapType(G_NORMAL_MAP);
// pocitadlo, bude potreba nize
this.pocitadlo = 0;
// vytvoreni ovladaciho prvku
this.ovladac = new GSmallMapControl();
// vytvoreni sledovace a jeho svazani s udalosti a funkci
var sledovac = GEvent.bind(this.mapa, "click", this, function(){
// pri kliknuti se vyhodnoti pocitadlo a:
// poprve se ukaze ovladaci prvek
if (this.pocitadlo == 0) this.mapa.addControl(this.ovladac);
// podruhe zmizi
if (this.pocitadlo == 1) this.mapa.removeControl(this.ovladac);
// potreti se opet objevi a zrusi se sledovani kliknuti
if (this.pocitadlo == 2){
this.mapa.addControl(this.ovladac);
google.maps.Event.removeListener(sledovac);
}
// pocitadlo kliku se zvysi o 1
this.pocitadlo++;
});
}

else document.write("Mapa neni funkcni!");
}

// spusteni
function spust(){
var gm = new GoogleMAPA();
}
</script>
</head>

<body onload="spust()">
<div id="mapa" style="width: 500px; height: 500px"></div>
</body>

</html>



Funckční kód naleznete zde.

Nastavení pozice ovládacího prvku
Ovládací prvky lze nastavit, kde na mapě budou.
Možnosti umístění jsou:
  • G_ANCHOR_TOP_RIGHT – vpravo nahoře
  • G_ANCHOR_TOP_LEFT – vlevo nahoře
  • G_ANCHOR_BOTTOM_RIGHT – vpravo dole
  • G_ANCHOR_BOTTOM_LEFT –vlevo dole
Pro udání pozice je potřeba vytvořit objekt google.maps.controlposition(PARAMETRY) a ten poslat
jako parametr při vytváření ovládacího prvku:
var pozice = new google.maps.ControlPosition(G_ANCHOR_TOP_RIGHT, new GSize(5,5));
mapa.addControl(new GSmallMapControl(), pozice);

Volitelný parametr google.maps.Size(P1,P2) umožňuje odsunout ovládací prvek od okraje mapy o P1 resp. P2 pixelů. Viz. modifikovaný příklad z dřívějška.

Overlays
Google Maps umožňují na mapu vložit několik prvků, které se zobrazují nezávisle
na úrovni přiblížení. Jedním z druhů overlay je i informační okénko popsané výše, zde zmíníme ještě značku (marker).

Na mapu lze umístit značku (marker). Značku lze snadno vytvořit pomocí metody
Marker(POZICE_LatLng); a umístit pomocí addOverlay(CO);:
mapa.addOverlay(new google.maps.Marker(new GLatLng(37.4419, 22.1419)));

Značky jsou navrženy jako interaktivní a je možné sledovat jejich události, viz. příklad:

function GoogleMAPA() {
if (google.maps.BrowserIsCompatible()) {
var mapa = new google.maps.Map2(document.getElementById("mapa"));
mapa.setCenter(new google.maps.LatLng(49.79545,15.732422),7);
// pridani znacky
mapa.addOverlay(new google.maps.Marker(new google.maps.LatLng(37.4419,
22.1419)));
// vytvoreni dalsi znacky s moznosti pretahovani
var znacka = new google.maps.Marker(new google.maps.LatLng(37.4419,
22.1000), {draggable: true});
// udalost pri zacatku pretahovani
google.maps.Event.addListener(znacka, "dragstart", function() {
mapa.closeInfoWindow();
});
// udalost pri ukonceni pretahovani
google.maps.Event.addListener(znacka, "dragend", function() {
znacka.openInfoWindowHtml("Tuto znacku je mozne pretahovat...");
});
// vykresleni znacky
mapa.addOverlay(znacka);
// oznaceni pretahovatelne znacky
znacka.openInfoWindowHtml("Tuto znacku je mozne pretahovat...");
}
else document.write("Mapa neni funkcni!");
}
google.setOnLoadCallback(GoogleMAPA);
 

Funkční ukázka kódu je zde.
 
Závěrem
Ačkoliv v tomto článku nejsou pospány všechny možnosti Google Maps API, výše
naleznete vše potřebné pro umístění mapy na svou stránku.
Pokud Vás téma zaujalo, neváhejte navštívit naši obecnou či vývojářskou diskuzní skupinu nebo stránky v odkazech níže. 

Odkazy
Domovská stránka Google Maps: maps.google.com
Domovská stránka Google Maps API: code.google.com/apis/maps
Dokumentace Google Maps API: code.google.com/apis/maps/documentation
Reference: code.google.com/apis/maps/documentation/reference.html

Zdroj: code.google.com

4 komentáře:

Clickmedia webdesign řekl(a)...

Výborný článek. Díky.

Anonymní řekl(a)...

Díky naprosto vyčerpávající článek, který přesně popisuje co jsem potřeboval a to vložit mapu na stránku a aktivovat základní prvky, snad jen pro úplnost je dobré pro info okno volat namísto funkce openInfoWindow() funci openInfoWindowHtml(), která dokáže prezentovat HTML formátování.

Anonymní řekl(a)...

Diky

Anonymní řekl(a)...

Vím, že je to starší článek (a tedy informace byli ze starších podmínek), ale yní API nemusí být přístupné všem účastníkům (podmínky z roku 2015). Může být i pod přihlášením, ALE za přihlášení nesmí být požadován poplatek.