Kafelki Street View

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Jeśli Twój adres rozliczeniowy znajduje się w Europejskim Obszarze Gospodarczym, od 8 lipca 2025 r. do korzystania z usług będą miały zastosowanie Warunki korzystania z usługi Google Maps Platform w EOG . Więcej informacji. Ponadto niektóre treści z interfejsu Map Tiles API nie będą już zwracane. Więcej informacji.

Kafelki Street View są podobne do kafelków 2D ale zawierają zdjęcia panoramiczne zrobione 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 API zapewnia dostęp do:

• kafelków Street View w Mapach Google,
• metadanych Street View,
• miniatur Street View.

Możesz łączyć kafelki obrazów zrobionych na poziomie ulicy, aby uzyskać panoramiczny efekt rzeczywistości. Możesz też wysyłać zapytania o maksymalnie 100 identyfikatorów panoram dla zestawu lokalizacji (np. trasy) i uzyskiwać bardziej szczegółowe metadane o pozycji kamery.

Do łączenia kafelków Street View potrzebna jest przeglądarka. Na przykład niestandardowa przeglądarka panoram Street View.

Wskazówka:więcej informacji znajdziesz w dokumentacji Street View Static API i Street View Service.

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

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

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

3. Użyj identyfikatorów panoram z odpowiedzi na wyszukiwanie panoId, aby uzyskać:

   1. metadane Street View. Możesz też uzyskać metadane Street View, przekazując zestaw współrzędnych i promień.

   2. miniatury Street View.

   3. kafelki Street View.

Uwaga: z każdą panoramą Street View musisz wyświetlać informacje o prawach autorskich. Wyświetlany ciąg znaków 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 odwołać się do 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żesz pobierać na 6 poziomach powiększenia: od 512 pikseli do 13 312 pikseli.
https://tile.googleapis.com/v1/streetview/panoIds	Umożliwia wyszukiwanie zbiorcze w maksymalnie 100 lokalizacjach. Zwraca identyfikatory panoram dla wszystkich lokalizacji ze zdjęciami.
https://tile.googleapis.com/v1/streetview/thumbnail	Zwraca miniaturę sceny Street View w formacie JPEG. Umożliwia podanie 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 określonej panoramie. Informacje obejmują powiązany adres i linki do sąsiednich panoram.

Wyszukiwanie panoIds w Street View

Identyfikator panoramy co najmniej 1 lokalizacji geograficznej możesz znaleźć, by przekazać jej współrzędne (lat, lng) do metody panoIds. Treść żądania to obiekt JSON, który zawiera 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 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 mają być wyszukiwane panoramy. Wartość domyślna to 50 metrów.

Odpowiedź PanoId

Interfejs Map Tiles API próbuje znaleźć panoramę najbliższą każdej lokalizacji, a następnie zwraca jej identyfikatory. Pomyślne żądanie panoIds zwraca obiekt JSON, który zawiera tablicę panoIds. Tablica zawiera listę identyfikatorów panoram w kolejności, w jakiej zostały one wysłane. Jeśli interfejs Map Tiles API nie może znaleźć żadnych panoram dla żądanych lokalizacji, w tablicy w tej lokalizacji zwracany jest pusty ciąg znaków. Przykład znajdziesz w tym kodzie JSON.

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

Za pomocą panoIds możesz:

• poprosić o metadane Street View,
• poprosić o miniatury Street View,
• poprosić o kafelki Street View.

Uwaga: identyfikatory panoram są tymczasowe. Oznacza to, że nie są ważne zbyt długo. Zasadniczo nie należy zakładać, że identyfikatory panoram będą ważne dłużej niż przez 1 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żesz pobierać na 2 sposoby:

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

• Jeśli jednak przekażesz lat i lng, interfejs Map Tiles API zwróci metadane dla najbliższej panoramy w danym promieniu wyszukiwania.

Przekazywanie zestawu współrzędnych i promienia

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

Ponieważ identyfikatory panoram są tymczasowe, zalecamy, aby w początkowym żądaniu metadanych Street View przekazać zestaw współrzędnych i wartość radius. Przykład znajdziesz w tym fragmencie kodu.

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 panoId zdjęcia Street View

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

Odpowiedź metadanych

Ten kod JSON jest przykładem 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"
  }
 ]
}

Ta lista zawiera definicje pól w treści odpowiedzi.

panoId

Unikalny identyfikator tej panoramy. Nie należy zakładać, że identyfikatory panoram będą ważne dłużej niż przez 1 sesję użytkownika.

lat, lng

Współrzędne (szerokość i długość geograficzna) panoramy. Te wartości mogą się różnić od współrzędnych przekazanych w żądaniu, ponieważ lokalizacja przyciąga do najbliższej panoramy.

imageHeight, imageWidth

Wymiary połączonego obrazu panoramicznego.

tileHeight, tileWidth

Wymiary pojedynczego kafelka panoramy.

heading

Kierunek na kompasie mierzony w stopniach zgodnie z ruchem wskazówek zegara od północy. Kierunki są zwracane w zakresie [0,360], gdzie 0 oznacza północ.

tilt

Nachylenie panoramy mierzone w stopniach od bieguna południowego 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 zgodnie z ruchem wskazówek zegara wokół linii wzroku, który został zastosowany do panoramy, aby wyrównać horyzont. Zwracane wartości mieszczą się w zakresie [0, 360].

imageryType

Określa typ obrazu. Prawidłowe wartości to indoor i outdoor.

date

Data, kiedy zdjęcie zostało zrobione. Nie wszystkie obrazy mają dane o dacie. Jeśli są dostępne, to pole zawiera połączenie roku (RRRR) i miesiąca (MM). Na przykład: 2023-05 lub 2024.

copyright

Tekst o prawach autorskich, który musisz wyświetlać jako atrybucję wraz ze zdjęciem Street View.

reportProblemLink

Hiperlink, którego użytkownicy mogą używać do zgłaszania problemów z tym kafelkiem Street View. Musisz wyświetlać ten hiperlink w prawym dolnym rogu obrazu. Musi on zawierać tekst linku, np. „Zgłoś problem z tym obrazem”.

addressComponent

Ustrukturyzowany kod geograficzny który zawiera szczegółowe informacje o adresie panoramy. Więcej informacji znajdziesz w Żądania i odpowiedzi geokodowania w dokumentacji Geocoding API.

links

Lista identyfikatorów panoram, które są połączone z tą panoramą. Zawiera też kierunek, w którym znaleziono link. Jeśli np. kierunek to 180°, połączona panorama znajduje się na południe od bieżącej panoramy. Pamiętaj, że ze względu na tymczasowy charakter identyfikatorów panoram nie należy na nich polegać dłużej niż przez 1 sesję użytkownika.

Miniatury Street View

Możesz poprosić o zdjęcia Street View w formacie thumbnail. Miniatury to obrazy bez kafelków o rozmiarze, kierunku, nachyleniu i polu widzenia określonych przez użytkownika. Miniatury mają niższą rozdzielczość niż kafelki i mniejszy rozmiar pliku. Aby wysłać prośbę o miniaturę, wyślij żądanie GET do punktu końcowego thumbnail, jak pokazano w tym prototypie kodu.

Uwaga: wartości pól ujęte w nawiasy kwadratowe w tym przykładzie wskazują zakresy. Na przykład height może mieć wartość 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"

Zapoznaj się z tym przykładem kodu, który pobiera miniaturę zdjęcia Street View zrobionego 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órą chcesz uzyskać. Wartości identyfikatora panoramy możesz uzyskać z punktu końcowego panoIdslub z punktu końcowego metadata—oba te punkty końcowe akceptują współrzędne geograficzne i zwracają odpowiedni panoId.

session

Prawidłowy token sesji.

key

Twój klucz interfejsu API.

Parametry opcjonalne

height

Określa wysokość miniatury w pikselach w zakresie od 16 do 250 pikseli. Jeśli nie określisz wysokości, domyślnie zostanie użyta maksymalna dozwolona wartość 250 pikseli. Jeśli podasz wartość spoza zakresu, miniatura przyciąga do najbliższej prawidłowej wartości.

width

Określa szerokość miniatury w pikselach w zakresie od 16 do 600 pikseli. Jeśli nie określisz szerokości, domyślnie zostanie użyta maksymalna dozwolona wartość 600 pikseli. Jeśli podasz wartość spoza zakresu, miniatura przyciąga 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 -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ścią domyślną jest 0.

fov

Określa poziome pole widzenia wyrażone w stopniach, przy czym maksymalna wartość to 120. W przypadku obszaru widocznego o stałym rozmiarze, np. w przypadku zdjęcia Street View o określonym rozmiarze, pole widzenia reprezentuje powiększenie. Mniejsze wartości oznaczają większe powiększenie. Wartością domyślną jest 90.

Kafelki obrazów Street View

Gdy masz już panoId, możesz poprosić o kafelek obrazu Street View. Żądania kafelków to żądania HTTPS GET. Zapoznaj się z tym przykładem.

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 mapy Street View, który chcesz uzyskać. Poziomy powiększenia w panoramach Street View muszą mieścić się w zakresie [0,5], gdzie 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 (zdjęcia niepubliczne kontrolowane przez dewelopera) i od użytkowników (treści użytkowników, czyli treści generowane przez użytkowników). Pamiętaj, że nie ma możliwości używania tylko jednego źródła zdjęć Street View. Dowiedz się więcej o naszej polityce prywatności dotyczącej zdjęć Street View.

Odpowiedzi kafelków Street View

Pomyślne żądanie kafelka Street View zwraca obraz w formacie i rozmiarze określonym w odpowiedzi createSession.

Na poziomie powiększenia 0 cała panorama jest zmieniana na kafelek o wymiarach tileWidth na 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łnym rozmiarze, która jest dzielona na kafelki.

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

x

Informacje o prawach autorskich

Z każdą panoramą Street View musisz wyświetlać informacje o prawach autorskich. Wyświetlany ciąg znaków 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 możesz odwołać się do pola copyright w odpowiedzi. Więcej informacji znajdziesz w artykule Atrybucje danych.