Używanie tokenów sesji z interfejsem Map Tiles API

Token sesji to element danych (identyfikator UUID), który jest używany w wywołaniach REST do identyfikowania sesji, czyli serii powiązanych wymian wiadomości. W przypadku żądań dotyczących obrazów 2D i zdjęć Street View musisz dołączyć token sesji. Dołączasz go jako wartość parametru session dołączonego do wszystkich adresów URL żądań.

W interfejsie Map Tiles API token sesji reprezentuje zdefiniowany zestaw opcji wyświetlania. Oznacza to, że nie musisz przekazywać zestawu opcji wyświetlania z każdą prośbą o płytkę. Możesz używać tego samego tokena sesji w różnych klientach. Token sesji jest obecnie ważny przez 2 tygodnie od momentu jego wygenerowania, ale może się to zmienić. Czas wygaśnięcia tokena sesji możesz sprawdzić w polu expiry w wiadomości z odpowiedzią.

Uwaga: aby pobrać płytki 2D i płytki Street View, musisz użyć tokenów sesji, ale nie w przypadku płytek 3D.

Żądanie tokena sesji

Aby poprosić o token sesji, wyślij żądanie HTTPS POST do punktu końcowego createSession, jak pokazano w tym przykładzie. Żądanie musisz wysłać z nagłówkiem Content-Type: application/json.

curl -X POST -d '{
  "mapType": "streetview",
  "language": "en-US",
  "region": "US"
}' \
-H 'Content-Type: application/json' \
"https://tile.googleapis.com/v1/createSession?key=YOUR_API_KEY"

Pola wymagane

mapType

Typ mapy podstawowej. Ta wartość może być jedną z tych:

roadmap

Standardowe elementy mapy w Mapach Google.

satellite

Zdjęcia satelitarne.

terrain

Zdjęcia terenu. Jeśli wybierzesz terrain jako typ mapy, musisz też uwzględnić typ warstwy layerRoadmap (opisany w sekcji Opcjonalne pola).

streetview

panoramy Street View. Więcej informacji znajdziesz na stronie Fragmenty Street View.

language

Tag języka IETF określający język używany do wyświetlania informacji na kafelkach. Na przykład en-US określa język angielski używany w Polsce.

region

Identyfikator regionu (2 duże litery) w Common Locale Data Repository, który reprezentuje fizyczną lokalizację użytkownika. Na przykład: US.

Pola opcjonalne

imageFormat

Określa format pliku, który ma zostać zwrócony. Prawidłowe wartości to jpeg lub png. Pliki JPEG nie obsługują przezroczystości, dlatego nie zalecamy ich używania do tworzenia kafelków nakładki. Jeśli nie podasz wartości imageFormat, najlepszy format kafelka zostanie wybrany automatycznie.

scale

Powiększa rozmiar elementów mapy (np. etykiet dróg), zachowując rozmiar i obszar pokrycia domyślnej płytki. Zwiększenie skali zmniejsza też liczbę etykiet na mapie, co zmniejsza jej zaśmiecanie. Te wartości są prawidłowe: scale:

• scaleFactor1x: wartość domyślna.
• scaleFactor2x: podwaja rozmiar etykiety i usuwa etykiety funkcji drugorzędnych.
• scaleFactor4x: czterokrotnie zwiększa rozmiar etykiety i usuwa etykiety funkcji drugorzędnych.

Poniższe przykłady pokazują efekt skalowania elementów mapy.

Współczynnik skali 1x	Współczynnik skalowania 2x

highDpi

Określa, czy mają być zwracane płytki o wysokiej rozdzielczości. Jeśli współczynnik skalowania jest zwiększony, do zwiększenia rozmiaru płytki służy element highDpi. Zwykle zwiększenie współczynnika skalowania powoduje powiększenie powstałej płytki do rozmiaru obrazu, co obniża jakość. W przypadku highDpi rozmiar wynikowy jest również zwiększany, zachowując jakość. DPI to skrót od „Dots per Inch” (punkty na cal), a wysoka rozdzielczość DPI oznacza, że kafelek jest renderowany z większą liczbą punktów na cal niż zwykle. Jeśli true, liczba pikseli w każdym z wymiarów x i y jest mnożona przez współczynnik skalowania (czyli 2 x lub 4 x). Zasięg kafelka pozostaje bez zmian. Ten parametr działa tylko z wartościami scale równymi 2x lub 4x. Nie ma to wpływu na kafelki skali 1x.

Współczynnik skalowania 1x	Współczynnik skalowania 2x High DPI

layerTypes

Tablica wartości określająca typy warstw dodanych do mapy. Prawidłowe wartości:

layerRoadmap

Wymagane, jeśli jako typ mapy wybierzesz terrain. Opcjonalnie można je nałożyć na mapę typu satellite. Nie ma wpływu na fragmenty mapy.

layerStreetview

Pokazuje ulice i lokalizacje dostępne w Street View za pomocą niebieskich obrysów na mapie.

layerTraffic

Pokazuje aktualne warunki na drogach.

styles

Tablica obiektów stylu JSON, które określają wygląd i poziom szczegółowości elementów mapy, takich jak drogi, parki i obszary zabudowane. Stylowanie służy do dostosowywania standardowej mapy bazowej Google. Parametr styles jest prawidłowy tylko wtedy, gdy typ mapy to roadmap. Pełną składnię stylów znajdziesz w dokumentacji dotyczącej stylów.

overlay

Wartość logiczna określająca, czy layerTypes ma być renderowany jako osobna nakładka, czy połączony z obrazem podstawowym. Gdy true, mapa podstawowa nie jest wyświetlana. Jeśli nie zdefiniujesz właściwości layerTypes, ta wartość zostanie zignorowana.

Na przykład żądanie typu mapy satellite z warstwą layerRoadmap i wartością overlay ustawioną na false powoduje, że kafelki będą odpowiadać typowi mapy hybrid używanemu w Maps JavaScript API (zdjęcie po lewej). Te same mapy i typy warstw z wartością overlay równą true powodują, że kafelek jest przezroczysty z nałożoną mapą, która jest odpowiednio stylizowana do nakładania na zdjęcia satelitarne (zdjęcie po prawej stronie).

overlay: false	overlay: prawda

Poniższy kod JSON to przykład typowej treści żądania, która zawiera pola wymagane i opcjonalne.

{
  "mapType": "satellite",
  "language": "en-US",
  "region": "us",
  "layerTypes": [ "layerRoadmap", "layerStreetview" ],
  "overlay":  true,
  "scale": "scaleFactor1x",
  "styles": [
    {
      "stylers": [
        { "hue": "#00ffe6" },
        { "saturation": -20 }
      ]
    },{
      "featureType": "road",
      "elementType": "geometry",
      "stylers": [
        { "lightness": 100 },
        { "visibility": "simplified" }
      ]
    }
  ]
}

Ten przykład pokazuje nakładkę, która nadaje się do połączenia z obrazem satelitarnym. Przykład zawiera zarówno mapę drogową, jak i nakładkę widoku ulicy. Wygenerowana mapa zawiera nazwy i dane w języku angielskim, ponieważ jest to język używany w Stanach Zjednoczonych.

apiOptions: tablica wartości określająca dodatkowe opcje do zastosowania. Obsługiwane opcje:

• MCYJ5E517XR2JC – włącz nowy styl mapy. W okresie akceptacji żądania będą miały dotychczasowy styl, chyba że ta wartość zostanie określona.

Odpowiedź tokena sesji

Poniżej znajduje się przykładowy kod JSON odpowiedzi.

{
  "session": "IgAAAHGU9jnAU4KOAfwY3Bcd6eH_WxQsyocSBAdUnAr9pnvTTNXtF9c_27RBo94ytEXTDg",
  "expiry": "1361828036",
  "tileWidth": 256,
  "tileHeight": 256,
  "imageFormat": "png"
}

Na liście poniżej znajdziesz definicje pól w ciele odpowiedzi.

session

Wartość tokenu sesji, którą musisz uwzględnić we wszystkich żądaniach interfejsu Map Tiles API.

expiry

Ciąg zawierający czas (w sekundach od początku epoki), w którym token wygasa. Token sesji jest ważny przez 2 tygodnie od momentu jego utworzenia, ale te zasady mogą ulec zmianie bez powiadomienia.

tileWidth

Szerokość kafelków w pikselach.

tileHeight

Wysokość kafelków mierzona w pikselach.

imageFormat

Format obrazu, który może być png lub jpeg.