Kafelki Street View

Kafelki 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 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 Street View

Możesz złączyć fragmenty zdjęć wykonane z poziomu ulicy, aby uzyskać rzeczywisty efekt panoramiczny. Możesz też wysłać zapytanie o maksymalnie 100 identyfikatorów panoram w określonych lokalizacjach (np. trasy) i uzyskać bardziej szczegółowe metadane dotyczące pozycji kamery.

Do złączenia kafelków Street View wymagany jest widz. np. niestandardowej panoramy Street View.

Wskazówka: więcej informacji znajdziesz w artykułach dotyczących Street View Static API i Usług Street View.

Po uzyskaniu klucza interfejsu API możesz uzyskać dostęp do zdjęć Street View, wykonując poniższe czynności.

1. Uzyskaj token sesji. Pamiętaj, aby ustawić wartość mapType na streetview.

2. Użyj tokena sesji, aby uzyskać identyfikator panoramy (panoId) dla co najmniej jednej lokalizacji geograficznej.

3. Użyj identyfikatorów panoram z odpowiedzi wyszukiwania panoramy, aby uzyskać:

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

   2. Miniatury Street View.

   3. Kafelki Street View.

Uwaga: przy każdej panoramy Street View musisz umieścić informacje o prawach autorskich. Ciąg znaków, który ma być wyświetlany, może różnić się w zależności od panoramy. Aby uzyskać informacje o prawach autorskich, musisz poprosić o metadane Street View. Możesz się wtedy skorzystać z pola copyright w odpowiedzi.

Metody Street View

Dostęp do zdjęć i metadanych Street View możesz uzyskać, wywołując jedną z tych 4 metod.

Metoda	Opis
https://tile.googleapis.com/v1/streetview/tiles	Zwraca poszczególne kafelki Street View. Kafelki Street View można pobierać na 6 poziomach powiększenia: od 512 do 13 312 pikseli.
https://tile.googleapis.com/v1/streetview/panoIds	Umożliwia zbiorcze wyszukiwanie maksymalnie 100 lokalizacji. Zwraca identyfikatory panoram dla wszystkich lokalizacji ze zdjęciami.
https://tile.googleapis.com/v1/streetview/thumbnail	Zwraca miniaturę obrazu JPEG sceny Street View. Pozwalają podać 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	Zawiera szczegółowe informacje o określonej panoramie. Szczegóły obejmują powiązany adres i linki do sąsiednich panoram.

Wyszukiwanie PanoIds Street View

Identyfikator panoramy co najmniej jednej lokalizacji geograficznej możesz znaleźć, przesyłając jej współrzędne (lat, lng) do metody panoIds. Treść żądania to obiekt JSON zawierający tablicę locations i opcjonalnie radius, jak pokazano w poniższym 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żesz 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ę w najbliższej lokalizacji, a następnie zwraca identyfikatory panoram. Pomyślne żądanie panoIds zwraca obiekt JSON zawierający tablicę panoIds. Tablica zawiera listę identyfikatorów Panoram w kolejności, w jakiej były żądane. Jeśli interfejs Map Tiles API nie znajdzie żadnych panoram dla żądanych lokalizacji, w danej lokalizacji w tablicy zostanie zwrócony pusty ciąg znaków. Przykład znajdziesz poniżej.

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

panoIds umożliwia:

• Przesyłanie prośby o metadane Street View
• Wysyłanie prośby o miniaturę Street View
• Poproś o kafelki Street View

Uwaga: identyfikatory panoram są przejściowe. To znaczy, że nie są ważne. Ogólnie nie zakładaj, że identyfikatory panoram nie są ważne dłużej niż przez jedną sesję użytkownika.

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 dwa sposoby:

• Jeśli przekażesz obiekt pano_id, interfejs Map Tiles API zwróci metadane tej panoramy.

• Jeśli jednak przekażesz wartości lat i lng, 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ą przejściowe, więc zalecamy, by w początkowym żądaniu metadanych Street View przekazać zestaw współrzędnych oraz 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"

Przekazywanie panoramy 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 zawiera przykład typowej odpowiedzi na żądanie 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 oznaczaj, ż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. Wartości te mogą różnić się od współrzędnych przekazywanych w żądaniu, bo lokalizacja przyciąga do najbliższej panoramy.

imageHeight, imageWidth

Wymiary połączonego zdjęcia panoramicznego.

tileHeight, tileWidth

Wymiary pojedynczego kafelka panoramy.

heading

Kierunek kompasu mierzony w stopniach, w prawo, z północy. Nagłówki są zwracane w zakresie [0,360], gdzie 0 oznacza 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 wokół linii wzroku zastosowanej do panoramy w celu wyrównania horyzontu. Wyświetlane 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 zawierają datę. Jeśli jednak jest ono dostępne, zawiera kombinację roku (RRRR) i miesiąca (MM). Na przykład: 5.02.2023 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 umożliwiające użytkownikom zgłaszanie problemów z tym kafelkiem Street View. Musisz wyświetlić ten hiperlink w prawym dolnym rogu obrazu i musi on zawierać tekst typu „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, w którym znaleziono link. Jeśli np. kierunek wynosi 180°, połączona panorama jest wyświetlana 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 dłużej niż przez jedną sesję użytkownika.

Miniatury Street View

Możesz zamówić zdjęcia Street View w formacie thumbnail. Miniatury to obrazy bez kafelków o określonym przez użytkownika rozmiarze, nagłówku, tonacji i polu widzenia. Miniatury mają niższą rozdzielczość niż kafelki oraz są mniejsze. Wysyłasz żądanie miniatury, wysyłając żądanie GET do punktu końcowego thumbnail, jak pokazano na poniższym prototypzie 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żmy przykład kodu, który umożliwia pobranie miniatury zdjęć Street View wykonanych 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 wybranej miniatury. Identyfikator panoramy możesz uzyskać z punktu końcowego panoIds lub z punktu końcowego metadata – oba te przyjmują 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ść, czyli 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 do 90 (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 do 360 (włącznie). Wartość domyślna to 0.

fov

Określa poziome pole widzenia wyrażone w stopniach, a maksymalna wartość to 120. W przypadku widocznego obszaru o stałym rozmiarze, jak w przypadku zdjęcia Street View o określonym rozmiarze, pole widzenia odpowiada powiększenie, a mniejsze wartości oznaczają większy poziom powiększenia. Wartością domyślną jest 90.

Kafelki obrazów Street View

Gdy masz 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ładowym kodzie z to poziom powiększenia, a x i y to współrzędne kafelka wybranego kafelka Street View. Poziomy powiększenia w panoramach Street View muszą mieścić się w zakresie [0,5], przy czym 0 oznacza najszersze pole widzenia.

Poziom powiększenia	Przybliżone pole widzenia
0	360°
1	180°
2	90°
3	45°
4	22.5°
5	11.25°

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

Odpowiedzi na temat kafelków Street View

Pomyślne żądanie kafelka Street View zwraca zdjęcie w formacie i rozmiarze określonych w odpowiedzi createSession.

Przy powiększeniu zerowym rozmiar całej panoramy zmienia się w kafelek wymiarów 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 używana jest pełnowymiarowa panorama, która jest dzielona na kafelki.

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

informacji o prawach autorskich

Przy każdej panoramy Street View musisz umieścić informacje o prawach autorskich. Ciąg znaków do wyświetlenia 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 skorzystać z pola copyright w odpowiedzi. Więcej informacji znajdziesz w artykule Atrybucja danych.