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 połączyć ze sobą kafelki zdjęć zrobionych z poziomu ulicy, aby uzyskać efekt prawdziwej panoramy. Możesz też wysłać zapytanie o maksymalnie 100 identyfikatorów panoram dla zestawu lokalizacji (np. trasy) i uzyskać szczegółowe metadane dotyczące pozycji aparatu.

Do zszywania kafelków Street View wymagany jest odtwarzacz. Może to być na przykład niestandardowa przeglądarka panoram 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 panoram z odpowiedzi wyszukiwania 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. Kafelki Street View

Metody Street View

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

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 może znaleźć żadnych panoram dla żądanych lokalizacji, zwraca 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
• Wysyłanie żądania miniatur Street View
• Zamawianie kafelków Street View

Metadane Street View

Żądania metadanych Street View pobierają informacje o panoramach. Żądanie metadanych Street View to żądanie HTTPS GET. 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 przekażesz 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ższy kod JSON zawiera przykład typowej odpowiedzi metadanych.

{
 "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"
  }
 ]
}

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

panoId

Unikalny identyfikator tej panoramy. Nie należy zakładać, że identyfikatory panoram 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 oznacza, że horyzont jest już wyrównany do równika panoramy.

roll

Obrócenie w prawo wokół linii wzroku, które zostało zastosowane 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ą z nią połączone. który 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 przejściowy charakter identyfikatorów panoram nie należy polegać na nich tylko przez jedną sesję użytkownika.

Miniatury Street View

Możesz poprosić o zdjęcia Street View w formacie thumbnail. Miniatury to obrazy o określonym przez użytkownika rozmiarze, nagłówku, tonie 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

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 podasz 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ść spoza zakresu, miniatura przyciągnie ją 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 zakresu od -360 do 360 (włącznie). Wartość domyślna to s 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 już będziesz mieć panoId, możesz poprosić o kafelek ze zdjęciem Street View. Żądania dotyczące kafelków to żądania GET HTTPS. Przyjrzyjmy się temu przykładowi.

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.

Odpowiedzi dotyczące kafelków Street View

Jeśli żądanie pliku kafelkowego Street View zostanie zrealizowane, zwróci ono obraz w formacie i rozmiarze określonym w odpowiedzi na 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ć puste miejsce w wymiarze y:

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

Prawa autorskie

Informacje o prawach autorskich musisz wyświetlać w przypadku każdej panoramy Street View. Ciąg znaków do wyświetlenia może być różny w zależności od panoram. 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.