Płytki Street View są podobne do kafelków 2D z tą różnicą, że zawierają panoramiczne zdjęcia zrobione na poziomie ulicy. Dzięki Street View możesz odkrywać zabytki z całego świata, podziwiać cuda natury, a także wejść do wnętrza 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 Street View
Możesz połączyć kafelki zrobione z poziomu ulicy, aby stworzyć efekt panoramiczny. Możesz przesłać zapytania obejmujące do 100 identyfikatorów panoram w odniesieniu do zbioru lokalizacji (np. trasy) i uzyskać bardziej szczegółowe metadane dotyczące pozycji kamery.
Do połączenia kafelków Street View potrzebny jest widz. np. w ramach niestandardowej przeglądarki panoram w Street View.
Po uzyskaniu klucza interfejsu API możesz uzyskać dostęp do zdjęć Street View, wykonując poniższe czynności.
Uzyskaj token sesji. Pamiętaj, aby ustawić wartość
mapType
nastreetview
.Za pomocą tokena sesji uzyskaj identyfikator panoramy (panoId) dla co najmniej jednej lokalizacji geograficznej.
Użyj identyfikatorów panoram z odpowiedzi wyszukiwania panoram, aby uzyskać:
Metadane Street View. Metadane Street View możesz też uzyskać, przekazując zestaw współrzędnych i promień.
Metody Street View
Aby uzyskać dostęp do zdjęć i metadanych Street View, wywołaj jedną z tych 4 metod.
Metoda | Opis |
---|---|
https://tile.googleapis.com/v1/streetview/tiles |
Zwraca poszczególne kafelki Street View. Kafelki Street View możesz pobierać na 6 poziomach powiększenia: od 512 do 13 312 pikseli. |
https://tile.googleapis.com/v1/streetview/panoIds |
Umożliwia zbiorcze wyszukiwanie nawet 100 lokalizacji. Zwraca identyfikatory panoram dla wszystkich lokalizacji ze zdjęciami. |
https://tile.googleapis.com/v1/streetview/thumbnail |
Zwraca miniaturę JPEG sceny Street View. Pozwala określić nagłówek, tonację, wymiary i pole widzenia. Minimalne wymiary to 16 x 16 pikseli. Maksymalne wymiary to 250 x 600 pikseli. |
https://tile.googleapis.com/v1/streetview/metadata |
Podaje szczegółowe informacje o określonej panoramie. Szczegóły obejmują powiązany adres i linki do sąsiednich panoram. |
Wyszukiwanie identyfikatorów panoramicznych Street View
Możesz znaleźć identyfikator panoramy jednej lub kilku lokalizacji geograficznych, przesyłając ich współrzędne (lat
, lng
) do metody panoIds
. Treść żądania to obiekt JSON zawierający tablicę locations
i opcjonalnie radius
, jak 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 jeden zestaw wartości współrzędnych, ale można dodać ich więcej – maksymalnie 100. radius
- Wartość
radius
(mierzona w metrach) określa promień okręgu wokół danej lokalizacji, w którym wyszukiwane są panoramy. Wartość domyślna to 50 metrów.
Odpowiedź PanoId
Interfejs Map Tiles API próbuje znaleźć panoramę znajdującą się najbliżej każdej lokalizacji, a potem zwraca ich identyfikatory panoram. Udane żądanie panoIds
zwraca obiekt JSON zawierający tablicę panoIds
. Tablica zawiera listę identyfikatorów Panorama w kolejności, w jakiej zostały one żądane. Jeśli interfejs Map Tiles API nie znajdzie żadnych widoków panoramicznych dla żądanych lokalizacji, w tej lokalizacji w tablicy zwracany jest pusty ciąg znaków. Oto przykład tego kodu JSON.
{
"panoIds": [
"ACfH-n2HcBvRry_3oc9grw",
"f5DJZatBAAAXHlooS2wKbw",
""
]
}
panoIds
umożliwia:
- Przesyłanie prośby o metadane Street View
- Przesyłanie próśb o miniaturę Street View
- Zamów kafelki 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żna pobrać na jeden z dwóch sposobów:
Jeśli przekażesz obiekt
pano_id
, interfejs Map Tiles API zwróci metadane tej Panoramy.Jeśli jednak podasz
lat
ilng
, interfejs Map Tiles API zwróci metadane najbliższej panoramy w danym promieniu wyszukiwania.
Przekaż zestaw współrzędnych i promień
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ą tymczasowe, dlatego zalecamy, by w pierwszym żądaniu metadanych Street View przekazać zestaw współrzędnych i wartość radius
.
Oto przykładowy fragment kodu, który 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"
Przekaż PanoId zdjęcia Street View
curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN &key=YOUR_API_KEY &panoId=panoId"
Odpowiedź z metadanymi
Poniższy kod JSON to przykład typowej 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"
}
]
}
Poniższa lista zawiera definicje pól w treści odpowiedzi.
panoId
- Unikalny identyfikator tej panoramy. Identyfikatory panoram nie powinny być ważne przez okres dłuższy niż 1 sesja użytkownika.
lat
,lng
- Współrzędne (szerokość i długość geograficzna) panoramy. Wartości te mogą różnić się od współrzędnych przekazywanych w żądaniu, ponieważ lokalizacja przyciąga się do najbliższej panoramy.
imageHeight
,imageWidth
- Wymiary złączonego zdjęcia panoramicznego.
tileHeight
,tileWidth
- Wymiary pojedynczego kafelka panoramy.
heading
- Kierunek na kompasie, mierzony w stopniach, w prawo, od północy. Nagłówki są zwracane w zakresie [0,360], gdzie 0 wskazuje kierunek północny.
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 na równiku panoramy.
roll
- Obrót w prawo dookoła linii wzroku zastosowany do panoramy w celu wyrównania horyzontu. Zwracane wartości mieszczą się w zakresie [0–360].
imageryType
- Wskazuje typ obrazu. Prawidłowe wartości to
indoor
ioutdoor
. date
- Data wykonania zdjęcia. Nie wszystkie obrazy zawierają datę. Jeśli jednak jest dostępne, zawiera kombinację roku (RRRR) i miesiąca (MM). (np. 2023-05 lub 2024).
copyright
- Tekst dotyczący praw autorskich, który musisz umieścić jako informację o autorze wraz ze zdjęciem Street View.
reportProblemLink
- Hiperłącze, które użytkownicy mogą używać do zgłaszania problemów z tym kafelkiem Street View. Musisz wyświetlić ten hiperlink w prawym dolnym rogu obrazu i musi on zawierać tekst linku, np. „Zgłoś problem z tym zdjęciem”.
addressComponent
- Uporządkowany geokod zawierający szczegółowe informacje o adresie panoramy. Więcej informacji znajdziesz w sekcji Żądania i odpowiedzi geokodowania w dokumentacji interfejsu Geocoding API.
links
- Lista identyfikatorów panoram powiązanych z tą panoramą. Zawiera też nagłówek, pod którym znaleziono link. Jeśli np. nagłówek ma 180°, połączona panorama będzie kierowana na południe od bieżącej panoramy. Pamiętaj, że ze względu na przejściowy charakter identyfikatorów panoram nie należy używać ich w więcej niż jednej sesji użytkownika.
Miniatury Street View
Możesz zamówić zdjęcia Street View w formacie thumbnail
. Miniatury to takie, które mają zdefiniowany przez użytkownika rozmiar, nagłówek, ton i pole widzenia.
Miniatury mają niższą rozdzielczość niż kafelki i mniejszy rozmiar pliku. Żądanie miniatury wysyłasz do punktu końcowego thumbnail
, wysyłając żądanie GET, jak pokazano na poniższym prototypie 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"
Poniższy przykładowy kod umożliwia pobranie miniatury zdjęć Street View zrobionych w Whistler w Kanadzie.
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 miniatury, której chcesz użyć. Identyfikator panoramy możesz uzyskać z punktu końcowego
panoIds
lub z punktu końcowegometadata
. Oba te punkty 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, domyślnie zostanie użyta maksymalna dozwolona wartość, która wynosi 250 pikseli. Jeśli podasz wartość spoza zakresu, miniatura przyciągnie się do najbliższej prawidłowej wartości.
width
- Określa szerokość miniatury w pikselach: od 16 do 600 pikseli. Jeśli nie określisz szerokości, domyślnie zostanie użyta maksymalna dozwolona wartość, która wynosi 600 pikseli. Jeśli podasz wartość spoza zakresu, miniatura przyciągnie się do najbliższej prawidłowej wartości.
pitch
- Określa kąt kamery wzdłuż osi pionowej. Prawidłowe wartości mieszczą się w zakresie od
-90
do90
(włącznie). Wartością domyślną jest 0. yaw
- Określa kierunek kamery wzdłuż osi poziomej. Prawidłowe wartości mieszczą się w zakresie od
-360
do360
(włącznie). Wartość domyślna to 0. fov
- Określa poziome pole widzenia wyrażone w stopniach, o maksymalnej wartości 120. W przypadku widocznego obszaru o stałym rozmiarze, jak w przypadku zdjęcia Street View o określonym rozmiarze, pole widzenia odpowiada powiększeniem, a mniejsze wartości oznaczają większy poziom powiększenia. Wartość domyślna to 90.
Fragmenty zdjęć Street View
Gdy masz już panoId
, możesz poprosić o kafelek zdjęcia Street View. Żądania kafelka to żądania HTTPS GET. Przeanalizuj 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 współrzędne fragmentu obrazu Street View, którego potrzebujesz. Poziom powiększenia w panoramach Street View musi
mieć zakres [0,5], gdzie 0 oznacza 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 dotyczące kafelków Street View
Pomyślne żądanie kafelka Street View zwraca zdjęcie w formacie i rozmiarze podanym w odpowiedzi createSession
.
Przy zerowym poziomie powiększenia cała panorama zmienia się w kafelek o wymiarach tileWidth
na tileHeight
. Ponieważ panoramy są większe w wymiarze x,
kafelek będzie zawierał puste miejsce w wymiarze Y:
Przy powiększeniu piątym wyświetlana jest pełnowymiarowa panorama, która jest dzielona na kafelki.
informacji o prawach autorskich
Z każdą panoramą Street View musisz umieścić informacje o prawach autorskich. Ciąg znaków do wyświetlenia może się różnić w przypadku poszczególnych panoram. Aby uzyskać informacje o prawach autorskich, musisz poprosić o metadane Street View, a następnie skorzystać z pola copyright
odpowiedzi. Więcej informacji znajdziesz w artykule Atrybucja danych.