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

Token sesji to fragment danych (UUID) używany w wywołaniach REST do identyfikowania sesji, czyli serii powiązanych wiadomości. Musisz podawać token sesji we wszystkich żądaniach kafelków 2D i zdjęć Street View. Uwzględniasz go jako wartość parametru session dołączanego 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 na kontach wielu klientów. Token sesji jest obecnie ważny przez 2 tygodnie od momentu wygenerowania, ale może się to zmienić. Czas ważności tokena sesji możesz w każdej chwili sprawdzić w polu expiry w wiadomości z odpowiedzią.

Żądanie tokena sesji

Aby poprosić o token sesji, wyślij żądanie HTTPS POST do punktu końcowego createSession, jak pokazano w tym przykładzie. Musisz wysłać żądanie 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 malowane fragmenty map Map 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 w artykule Karty 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 do zwrócenia. Prawidłowe wartości to jpeg lub png. Pliki JPEG nie obsługują przezroczystości, dlatego nie są zalecane w przypadku kafelków z nakładkami. Jeśli nie podasz wartości imageFormat, najlepszy format kafelka zostanie wybrany automatycznie.
scale

Zwiększa rozmiar elementów mapy (np. etykiet dróg), zachowując rozmiar kafelka i zasięg domyślnego kafelka. 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: zwiększa rozmiar etykiety i usuwa drobne etykiety cech.
  • scaleFactor4x: rozmiar etykiety zwiększa się czterokrotnie i usuwa drobne etykiety cech.

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

Współczynnik skali 1x Współczynnik skali 2x
Mapa z współczynnikiem skalowania 1x Mapa pokazująca współczynnik skalowania 2x
highDpi
Określa, czy mają być zwracane płytki o wysokiej rozdzielczości. Jeśli współczynnik skalowania zostanie zwiększony, rozmiar kafelka zostanie zwiększony za pomocą funkcji highDpi. Zwykle zwiększenie współczynnika skalowania powoduje powiększenie powstałej płytki do rozmiaru obrazu, co obniża jakość. Dzięki funkcji highDpi rozmiar wynikowy również się zwiększa, co pozwala zachować 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). Obszar pokrycia 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 w skali 1 x.
Współczynnik skalowania 1x Współczynnik skalowania 2x High DPI
Mapa wyświetlana w standardowej rozdzielczości Mapa wyświetlana w 2-krotnej rozdzielczości wysokiej DPI
layerTypes

Tablica wartości, która określa typy warstw dodane do mapy. Prawidłowe wartości:

layerRoadmap
Wymagane, jeśli jako typ mapy wybierzesz terrain. Można ją też opcjonalnie nałożyć na mapę typu satellite. Nie ma wpływu na fragmenty mapy.
layerStreetview
Ulice i lokalizacje obsługujące Street View są oznaczone na mapie niebieskim konturem.
layerTraffic
Pokazuje aktualne warunki na drogach.
styles

Tablica obiektów w stylu JSON, które określają wygląd i poziom szczegółowości obiektów mapy, takich jak drogi, parki i tereny 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ę stylu znajdziesz w dokumentacji stylu.

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
Nakładka ustawiona jako fałsz Nakładka ma wartość 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" }
      ]
    }
  ]
}

W tym przykładzie można zobaczyć nakładkę, która nadaje się do łączenia ze zdjęciami satelitarnymi. Przykład zawiera zarówno plan, jak i nakładkę Street View. 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ących dodatkowe opcje do zastosowania. Obsługiwane opcje:

  • MCYJ5E517XR2JC – zaakceptuj nowy styl mapy. W okresie akceptacji żądania będą miały istniejący styl, chyba że określisz tę wartość.

Odpowiedź tokena sesji

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

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

Poniższa lista zawiera definicje pól w treści odpowiedzi.

session
Wartość tokena 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 utworzenia, ale ta zasada może 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.