Google Maps API

Wielu z Was pewnie nieraz widziało na przeróżnych stronach zamieszczone mapki Google'a jako interaktywne wstawki. Ba, nawet pokazujące miejsce, o którym akurat strona traktuje. Umieszczenie takiej mapki na stronie wcale nie jest trudne, a wręcz banalnie proste - wszystko dzięki rozbudowanemu API udostępnionemu przez Google. Google Maps API począwszy od wersji 2 dostępne jest za pośrednictwem standardowego interfejsu JavaScript udostępnianego przez Google. Obecnie w wersji testowej jest już trzecia wersja API do map, jednak ja opiszę tutaj obecnie dostępną jako stabilną wersję drugą, zresztą nie sądzę, aby w podstawowych wywołaniach zaszły diametralne zmiany. Zanim jednak zaczniemy pracę musimy wygenerować sobie klucz dostępu. W tym cely musimy się udać na stronę rejestracji i podać URL strony, na której chcemy używać map. Tutaj od razu uwaga - wpisujemy taki adres, po jakim będą na stronę wchodzić użytkownicy. Google nie sprawdza IP, hosta, ani niczego innego związanego z połączeniem - jedynie URL jaki został wpisany w przeglądarce. Oznacza to, że jeśli mamy skrypt dostępny pod kilkoma domenami, to musimy wstawiać odpowiednie klucze dla każdej domeny. Z drugiej strony, nawet jeśli pracujemy na tymczasowej domenie, albo wręcz w testowym środowisku, nie będzie potem potrzeby zmiany klucza. Mając klucz możemy przejść do kwestii technicznych. Opiszę tutaj jedynie podstawy korzystania z Google Maps API, szczegółową dokumentację znajdziecie tutaj.

Sposobów na rozpoczęcie pracy z mapami jest kilka, ale ja opiszę ten najbardziej uniwersalny. Pierwszy krok to dodanie do naszej strony odnośnika do kodu JavaScript udostępnianego przez Google - tutaj właśnie podajemy nasz klucz API (jak nie trudno zauważyć, klucz nie jest czymś tajnym, jest on widoczny w kodzie wprost):

<script type="text/javascript" src="http://www.google.com/jsapi?key=KLUCZ"></script>

Wstawianie mapy

Teraz na naszej stronie możemy już używać map Google. Zanim zaczniemy zabawę z kodem samego skryptu, musimy sobie gdzieś na stronie zrobić miejsce na mapkę. Zazwyczaj wystarcza prosty <div>:

<div id="GoogleMap" style="width: 400px; height: 400px;"></div>

Pierwszym krokiem w naszym skrypcie będzie załadowanie samego API map - skrypt, który dołączyliśmy do naszej strony to bramka ogólnego przeznaczenia, przez którą mamy dostęp do wszystkich usług Google. W przypadku kodu JavaScript nie będę się posługiwał konwencją żadnego frameworka, ale nie powinno być tutaj problemu z przystosowaniem kodu do jakiegokolwiek z popularnych bibliotek. Praktycznie rzecz biorąc wystarczy podpiąć funkcję, którą ja podepnę pod zdarzenie onload okna, pod obsługę zdarzeń w używanym przez siebie frameworku:

window.onload = function()
{
    google.load("maps", "2", {
        language: "pl",
        other_params: "sensor=false",
        callback: initGoogleMaps
    } );
};

Tak mniej więcej wygląda podstawowa konfiguracja skryptu do obsługi map. Pierwsze dwa argumenty do funkcji google.load() to nazwa modułu, jaki chcemy załadować, oraz jego wersja. Trzeci argument to dodatkowe opcje. W naszym przypadku ustawiamy język na polski, oraz wskazujemy funkcję (zaraz ją zdefiniujemy) initGoogleMaps, która zostanie wywołana automatycznie po załadowaniu modułu map. Oprócz tego przekazujemy także dodatkowy parametr sensor - przyjmuje on wartość boolowską, a jego zdefiniowanie jest konieczne. Oznajmia on czy nasze urządzenie korzysta z namierzania pozycji (na przykład GPS w urządzeniach klasy handheld).

Centrowanie na wskazany adres

W funkcji initGoogleMaps moglibyśmy praktycznie już zakończyć nasz skrypt w prosty sposób wskazując nasz <div> jako miejsce wyświetlenia mapy. Jednak zanim to zrobimy wzbogacimy nieco tę podstawową funkcjonalność o centrowanie mapy w zadanym przez nas punkcie. Tutaj pojawia się mały problem - wszelkie współrzędne w API map są przekazywane jako szerokość i długość geograficzna. Oczywiście rzadko kiedy będziemy się bezpośrednio posługiwać takimi współrzędnymi, najwygodniejszą formą jest po prostu poszukiwanie według adresu. Na szczęście w końcu to Google, więc z wyszukiwaniem czegokolwiek nie ma problemu. Do wyszukiwania współrzędnych na podstawie adresu klasa GClientGeocoder i to jej właśnie użyjemy w naszej funkcji inicjującej:

function initGoogleMaps()
{
    var geo = new GClientGeocoder();
    geo.getLatLng("Staromłyńska 20c, 70-561 Szczecin, zachodniopomorskie, Polska", centerMap);
}

Jak widać adres przyjmowany jest w bardzo przystępnej formie. Powyższy kod jednak nie utworzy nam jeszcze mapy. Tym razem znowu odsyłamy kod gdzie indziej, gdyż musimy z kolei poczekać, aż adres zostanie przetworzony na współrzędne. Kiedy nasza instancja GClientGeocoder skończy pracę wywoła funkcję centerMap (którą sobie zaraz zdefiniujemy), przekazując do niej jako argument punkt w postaci obiektu klasy GLatLng. I w tej funkcji zamieścimy właściwy kod:

function centerMap(point)
{
    /*
    to najważniejsza linijka w kodzie
    praktycznie ta jedna linijka tworzy cały mechanizm na stronie
    jako argument do function google.maps.Map2() przekazujemy element strony,
    który będzie przechowywał mapkę
    */
    var map = new google.maps.Map2( document.getElementById("GoogleMap") );
    
    // sprawdzamy, czy Google odnalazło nasz adres
    if(point)
    {
        // centrujemy naszą mapkę na wskazanym punkcie z określonym przybliżeniem
        map.setCenter(point, 13);
        // przydatny drobiazg - możliwość kontroli zoomu rolką
        map.enableScrollWheelZoom();
        // standardowe kontrolki
        map.addControl( new GLargeMapControl() );
    }
}

Przykład

To wszystko oczywiście tylko pobieżny przykład, ale jak widać wystarcza do działania, a dzięki swojej prostocie nie będzie trudno go rozbudować o taką funkcjonalność, jaka będzie potrzebna. Polecam chociażby zainteresowanie się klasą GMarker, dzięki której możemy wstawiać na naszą mapkę informacje o zaznaczonych punktach.