Kafelki Street View

Kafle 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 zszywać 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.

Wskazówka: więcej informacji znajdziesz w interfejsie Street View Static API i usłudze Street View.

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.

Uwaga: musisz wyświetlać informacje o prawach autorskich w przypadku każdej panoramy Street View. Wyświetlany ciąg znaków może się różnić w przypadku różnych panoram. Aby uzyskać informacje o prawach autorskich, musisz poprosić o metadane Street View, a następnie sprawdzić pole copyright w odpowiedzi.

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.

wyszukiwanie identyfikatorów panoram Street View (panoIds)

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:

• Prośba o metadane Street View
• Prośba o miniatury Street View
• Prośba o kafelki Street View

Uwaga: identyfikatory panoramy są tymczasowe. Oznacza to, że nie są one trwałe. Zwykle nie należy zakładać, że identyfikatory Panorama są ważne dłużej niż przez jedną sesję użytkownika.

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, interfejs 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], gdzie 0 to 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 oznacza, ż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). Na 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.

Uwaga: wartości pól w nawiasach kwadratowych w tym przykładzie pokazują zakresy. Na przykład height może mieć od 16 do 250 pikseli.

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

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ść poza zakresem, miniatura przywrze do najbliższej prawidłowej wartości.

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 stałym 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°

Uwaga: zdjęcia Street View pochodzą z 2 źródeł: Google (niepubliczne zdjęcia kontrolowane przez deweloperów) oraz publiczne (treści użytkowników). Pamiętaj, że nie można używać tylko jednego źródła zdjęć Street View. Dowiedz się więcej o polityce prywatności dotyczącej zdjęć w Street View.

Odpowiedzi dotyczące kafelków Street View

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

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:

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

Wskazówka: maksymalne wartości x i y możesz obliczyć, dzieląc wartości imageHeight i imageWidth przez wartości tileHeight i tileWidth.

Prawa autorskie

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.