Kafelki Street View

Przykład Street ViewKafle Street View są podobne do kafelków 2D, ale zawierają panoramiczne zdjęcia wykonane na poziomie ulicy. Korzystając ze Street View, możesz odkrywać zabytki z całego świata, podziwiać cuda natury, a także „wchodzić” do muzeów, obiektów sportowych, restauracji czy małych firm. Ten punkt końcowy interfejsu API zapewnia dostęp do:

  • Kafelki Street View w Mapach Google
  • Metadane Street View
  • Miniatury zdjęć Street View

Możesz połączyć ze sobą kafelki zdjęć zrobionych z poziomu ulicy, aby uzyskać efekt prawdziwej panoramy. Możesz też wysłać zapytanie o do 100 identyfikatorów panoramy dla zbioru lokalizacji (np. trasy) i uzyskać bardziej szczegółowe metadane dotyczące pozycji aparatu.

Do zszywania kafelków Street View wymagany jest odtwarzacz. Na przykład w ramach Street View możesz wyświetlać niestandardowe panoramy.

Gdy masz klucz interfejsu API, możesz uzyskać dostęp do zdjęć Street View, wykonując te czynności.

  1. Uzyskaj token sesji. Upewnij się, że wartość mapType jest ustawiona na streetview.

  2. Użyj tokenu sesji, aby uzyskać identyfikator panoramy (panoId) co najmniej 1 lokalizacji geograficznej.

  3. Użyj identyfikatorów panoramy z odpowiedzi na zapytanie o panoId, aby uzyskać:

    1. Metadane Street View. Metadane Street View możesz też uzyskać, podając zestaw współrzędnych i promień.

    2. Miniatury Street View.

    3. Kafle Street View.

Metody Street View

Dostęp do zdjęć i metadanych Street View możesz uzyskać na 1 z tych 4 sposobów.

Metoda Opis
https://tile.googleapis.com/v1/streetview/tiles Zwraca poszczególne kafelki Street View. Płytki Street View możesz pobrać w 6 poziomach powiększenia: od 512 pikseli do 13 312 pikseli.
https://tile.googleapis.com/v1/streetview/panoIds umożliwia wyszukiwanie zbiorcze maksymalnie 100 lokalizacji; Zwraca identyfikatory panoram dla wszystkich lokalizacji z obrazami.
https://tile.googleapis.com/v1/streetview/thumbnail Zwraca miniaturę w formacie JPEG sceny Street View. Umożliwia określenie kierunku, nachylenia, wymiarów i pola widzenia. Minimalne wymiary to 16 x 16 pikseli. Maksymalne wymiary to 250 x 600 pikseli.
https://tile.googleapis.com/v1/streetview/metadata Zawiera szczegółowe informacje o wybranej panoramie. Szczegóły obejmują powiązany adres i linki do sąsiadujących panoram.

Identyfikator panoramy jednej lub większej liczby lokalizacji geograficznych możesz znaleźć, przekazując ich współrzędne (lat, lng) metodzie panoIds. Treść żądania to obiekt JSON zawierający tablicę locations i opcjonalnie radius, jak pokazano w tym przykładzie kodu JSON.

curl -X POST -d '{
  "locations": [
    {"lat": -33.883837, "lng": 151.209307},
    {"lat": -33.883700, "lng": 151.210307},
    {"lat": 0, "lng": 0}
  ],
  "radius": 50
}' \
-H 'Content-Type: application/json' \
"https://tile.googleapis.com/v1/streetview/panoIds?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY"
locations
Tablica locations musi zawierać co najmniej 1 zbiór wartości współrzędnych, ale możesz dodać więcej – maksymalnie 100.
radius
Wartość radius (wyrażona w metrach) określa promień koła wokół danej lokalizacji, w którym mają być wyszukiwane panoramy. Wartością domyślną jest 50 metrów.

Odpowiedź PanoId

Interfejs Map Tiles API próbuje znaleźć panoramę najbliższą danej lokalizacji, a potem zwraca jej identyfikatory. Pomyślne żądanie panoIds zwraca obiekt JSON zawierający tablicę panoIds. Tablica zawiera listę identyfikatorów panoram w kolejności, w jakiej zostały przesłane. Jeśli interfejs Map Tiles API nie znajdzie panoram dla żądanych lokalizacji, zwróci pusty ciąg znaków w tej lokalizacji w tablicy. Przykładowy kod JSON znajdziesz poniżej.

{
  "panoIds": [
    "ACfH-n2HcBvRry_3oc9grw",
    "f5DJZatBAAAXHlooS2wKbw",
    ""
  ]
}

Elementu panoIds możesz używać do:

Metadane Street View

Żądania metadanych Street View umożliwiają pobieranie informacji o panoramach. Żądanie metadanych StreetView to żądanie GET HTTPS. Informacje o panoramach możesz pobrać na 2 sposoby:

  • Jeśli podasz parametr pano_id, Map Tiles API zwróci metadane danej panoramy.

  • Jeśli jednak podasz wartości lat i lng, interfejs Map Tiles API zwróci metadane najbliższej panoramy w określonym promieniu wyszukiwania.

Przekazywanie zbioru współrzędnych i promieniach

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=lat&lng=lng&radius=meters"

Identyfikatory panoram są przejściowe, dlatego w pierwotnym żądaniu metadanych Street View zalecamy przekazanie zestawu współrzędnych i wartości radius. Przykładowy fragment kodu znajdziesz poniżej.

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=47.62066&lng=-122.34923&radius=50"

Przekazywanie identyfikatora panoId obrazu Street View

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId"

Odpowiedź metadanych

Poniżej znajdziesz przykładowy kod JSON, który jest typową odpowiedzią z metadanymi.

{
 "panoId": "rZ9KeTyhA11i0VppYNzsSg",
 "lat": 37.420864219339165,
 "lng": -122.08446528377291,
 "imageHeight": 6656,
 "imageWidth": 13312,
 "tileHeight": 512,
 "tileWidth": 512,
 "heading": 94.35,
 "tilt": 88.39652,
 "roll": 1.7181772,
 "imageryType": "outdoor",
 "date": "2023-01",
 "copyright": "© 2023 Google",
 "reportProblemLink": "https://cbks0.googleapis.com/cbk?output=report&panoid=rZ9KeTyhA11i0VppYNzsSg&cb_client=api&cbp=1,0,,0,0&hl=en-US&gl=us",
 "addressComponents": [
  {
   "longName": "United States",
   "shortName": "United States",
   "types": [
    "country"
   ]
  },
  {
   "longName": "Mountain View, California",
   "shortName": "Mountain View, California",
   "types": [
    "locality"
   ]
  },
  {
   "longName": "Charleston Rd",
   "shortName": "Charleston Rd",
   "types": [
    "route"
   ]
  },
  {
   "longName": "1635",
   "shortName": "1635",
   "types": [
    "street_number"
   ]
  }
 ],
 "links": [
  {
   "panoId": "Yw4pqzA4FEq1qs-BwZSvSQ",
   "heading": 274.47998046875,
   "text": "Charleston Rd"
  },
  {
   "panoId": "1cODYwFRw1aZ45IignDIMw",
   "heading": 94.47999572753906,
   "text": "Charleston Rd"
  }
 ]
}

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

panoId
Unikalny identyfikator tej panoramy. Nie należy zakładać, że identyfikatory Panorama są ważne dłużej niż przez jedną sesję użytkownika.
lat, lng
Współrzędne (szerokość i długość geograficzna) panoramy. Te wartości mogą różnić się od współrzędnych przekazanych w żądaniu, ponieważ lokalizacja dopasowuje się do najbliższej panoramy.
imageHeight, imageWidth
Wymiary zszytej panoramy.
tileHeight, tileWidth
Wymiary pojedynczej płytki panoramy.
heading
Kierunek na kompasie mierzony w stopniach w zgodnym z zegarzem kierunku od północy. Kierunki są zwracane w zakresie [0,360], przy czym 0 reprezentuje kierunek na północ.
tilt
Nachylenie panoramy mierzone w stopniach od południowego bieguna panoramy do horyzontu. Zwracane wartości mieszczą się w zakresie [0, 180]. Wartość 90 stopni wskazuje, że horyzont jest już wyrównany z równikiem panoramy.
roll
Obrócenie w prawo wokół linii wzroku zastosowanej do panoramy w celu wypoziomowania horyzontu. Zwracane wartości mieszczą się w zakresie [0, 360].
imageryType
Wskazuje typ obrazu. Prawidłowe wartości to indoor i outdoor.
date
Data wykonania zdjęcia. Nie wszystkie obrazy mają informacje o dacie. Gdy jest dostępne, to pole zawiera kombinację roku (RRRR) i miesiąca (MM). Przykład: 2023-05 lub 2024.
copyright
Tekst dotyczący praw autorskich, który musisz wyświetlić jako informacje o źródle wraz ze zdjęciem Street View.
reportProblemLink
Hiperlink, który użytkownicy mogą wykorzystać do zgłaszania problemów z tą lokalizacją w Street View. Hiperlink musi być widoczny w prawym dolnym rogu zdjęcia i musi zawierać tekst linku, np. „Zgłoś problem z tym zdjęciem”.
addressComponent
Dane uporządkowane Geocode zawierające szczegóły adresu panoramy. Więcej informacji znajdziesz w dokumentacji interfejsu Geocoding API dotyczącej żądań i odpowiedzi geokodowania.
links
Lista identyfikatorów panoram, które są połączone z tą panoramą. Zawiera też nagłówek, w którym znajduje się link. Jeśli na przykład kierunek to 180°, połączona panorama znajduje się na południe od bieżącej panoramy. Pamiętaj, że ze względu na przemijający charakter identyfikatorów panoramy nie należy ich używać do dłuższego niż jedna sesja użytkownika.

Miniatury zdjęć Street View

Możesz poprosić o zdjęcia Street View w formacie thumbnail. Miniatury to niepłytkowe obrazy o zdefiniowanym przez użytkownika rozmiarze, kierowaniu, wysokości i polu widzenia. Miniatury mają niższą rozdzielczość niż kafelki i mniejszy rozmiar pliku. Aby poprosić o miniaturę, wyślij żądanie GET do punktu końcowego thumbnail, jak pokazano w tym pliku prototypu kodu.

curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId&height=FROM_16_TO_250&width=FROM_16_TO_600&pitch=FROM-90_TO_90&yaw=FROM-360_TO_360&fov=FROM_30_TO_120"

Rozważ poniższy przykład kodu, który pobiera miniaturę obrazu Street View zrobionego w Whistler w Kanadach.

curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=Zzl28rqGJgaL2IdkUleP8A&height=200&width=200&pitch=0&yaw=250&fov=80" --output /tmp/example_thumbnail.png

Miniatura zdjęcia Street View z Whistler w Kanadzie

Wymagane parametry

panoId
Unikalny identyfikator wybranej miniatury. Wartości identyfikatorów panoram można uzyskać z punktu końcowego panoIds lub z punktu końcowego metadata. Oba te punkty końcowe akceptują współrzędne geograficzne i zwracają odpowiednią wartość panoId.
session
prawidłowy token sesji,
key
Twój klucz interfejsu API.

Parametry opcjonalne

height
Określa wysokość miniatury w pikselach (od 16 do 250 pikseli). Jeśli nie określisz wysokości, zostanie użyta maksymalna dozwolona wartość 250 pikseli. Jeśli podasz wartość spoza zakresu, miniatura przybierze najbliższą prawidłową wartość.
width
Określa szerokość miniatury w pikselach (od 16 do 600 pikseli). Jeśli nie podasz szerokości, zostanie ona ustawiona domyślnie na maksymalną dozwoloną wartość 600 pikseli. Jeśli podasz wartość poza zakresem, miniatura przejdzie do najbliższej prawidłowej wartości.
pitch
Określa kąt kamery wzdłuż osi pionowej. Prawidłowe wartości należą do przedziału od -90 do 90 (obustronnie domkniętego). Wartością domyślną jest 0.
yaw
Określa kierunek kamery wzdłuż osi poziomej. Prawidłowe wartości należą do przedziału od -360 do 360 (obustronnie domkniętego). Wartością domyślną jest 0.
fov
Określa poziome pole widzenia wyrażone w stopniach. Maksymalna wartość to 120. W przypadku widocznego obszaru o stałym rozmiarze, np. obrazu Street View o ustawionym rozmiarze, pole widzenia odpowiada powiększaniu. Mniejsze wartości oznaczają większy stopień powiększenia. Wartością domyślną jest 90.

Kafelki zdjęć Street View

Gdy masz panoId, możesz poprosić o pobranie kafelka obrazu Street View. Żądania dotyczące kafelków to żądania GET HTTPS. Rozważ ten przykład.

curl "https://tile.googleapis.com/v1/streetview/tiles/z/x/y?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId"

W tym przykładzie kodu z to poziom powiększenia, a x i y to koordynaty kafelka wybranego kafelka Street View. Poziomy powiększenia w panoramach Street View muszą mieścić się w zakresie [0,5], przy czym 0 reprezentuje najszersze pole widzenia.

Poziom powiększenia Przybliżone pole widzenia
0 360°
1 180°
2 90°
3 7°
4 22,5°
5 11,25°

Odpowiedzi na pytania dotyczące kafelków Street View

Udane żądanie pliku kafelkowego Street View zwraca obraz w formacie i rozmiarze określonym w odpowiedzi createSession.

Wynik żądania dotyczącego kafelka

Na poziomie powiększenia 0 cała panorama jest zmieniana w płytkę o wymiarach tileWidth × tileHeight. Ponieważ panoramy są większe w wymiarze x, kafelek będzie zawierać pustą przestrzeń w wymiarze y:

Poziom powiększenia 0

Na poziomie powiększenia 5 używana jest panorama w pełnej wielkości podzielona na kafelki.

Informacje o prawach autorskich musisz wyświetlać w przypadku każdej panoramy Street View. Wyświetlany ciąg tekstowy może się różnić w zależności od panoramy. Aby uzyskać informacje o prawach autorskich, musisz poprosić o metadane Street View, a następnie sprawdzić pole copyright w odpowiedzi. Więcej informacji znajdziesz w artykule Atrybucja danych.