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 z poziomu 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 Street View

Możesz połączyć kafelki obrazów zrobionych z poziomu ulicy, aby uzyskać realistyczny efekt panoramiczny. Możesz też wysłać zapytanie o maksymalnie 100 identyfikatorów panoram dla zestawu lokalizacji (np. trasy) i uzyskać bardziej szczegółowe metadane dotyczące pozycji kamery.

Do połączenia kafelków Street View wymagana jest przeglądarka. Przykładem może być niestandardowa przeglądarka panoram Street View.

Wskazówka: więcej informacji znajdziesz w artykułach 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. Uzyskaj token sesji. Ustaw wartość mapType na streetview.

2. Użyj tokena sesji, aby uzyskać identyfikator panoramy (panoId) co najmniej 1 położenia geograficznego.

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: przy każdej panoramie Street View musisz wyświetlać 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 możesz 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 zbiorcze wyszukiwanie maksymalnie 100 lokalizacji. Zwraca identyfikatory panoram dla wszystkich lokalizacji ze zdjęciami.
https://tile.googleapis.com/v1/streetview/thumbnail	Zwraca obraz JPEG miniatury sceny Street View. 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. Szczegóły obejmują powiązany adres i linki do sąsiednich panoram.

Wyszukiwanie identyfikatorów panoram Street View

Identyfikator panoramy dla co najmniej jednego położenia geograficznego możesz znaleźć, przekazując 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ładowym kodzie 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 podać 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 ich 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 w żądaniu. Jeśli interfejs Map Tiles API nie znajdzie żadnych panoram dla żądanych lokalizacji, w tej lokalizacji w tablicy zostanie zwrócony pusty ciąg znaków. Przykładowy kod JSON znajdziesz poniżej.

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

Za pomocą panoIds możesz:

• Żądanie metadanych Street View
• Żądanie miniatur Street View
• Żądanie kafelków Street View

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

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

• Jeśli jednak przekażesz parametry lat i lng, interfejs Map Tiles API zwróci metadane 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"

Identyfikatory panoram są tymczasowe, dlatego zalecamy przekazywanie zestawu współrzędnych i wartości radius w początkowym żądaniu metadanych Street View. Przykład znajdziesz w poniższym 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 identyfikatora panoId zdjęcia Street View

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

Odpowiedź dotycząca metadanych

Poniższy kod JSON jest przykładem 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. Nie należy zakładać, że identyfikatory panoram będą 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ą się różnić od współrzędnych przekazanych w żądaniu, ponieważ lokalizacja jest przyciągana do najbliższej panoramy.

imageHeight, imageWidth

Wymiary połączonego obrazu panoramicznego.

tileHeight, tileWidth

Wymiary pojedynczego kafelka panoramy.

heading

Kierunek kompasu 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 z równikiem panoramy.

roll

Obrót w prawo wokół linii wzroku, który został zastosowany do panoramy, aby wypoziomować horyzont. Zwracane wartości mieszczą się w zakresie [0, 360].

imageryType

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

date

Data zrobienia zdjęcia. Nie wszystkie obrazy zawierają dane o dacie. Jeśli jednak jest dostępna, 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świetlać jako informacje o autorze wraz ze zdjęciem Street View.

reportProblemLink

Hiperlink, którego użytkownicy mogą użyć do zgłaszania problemów z tym kafelkiem Street View. Hiperlink musi być wyświetlany w prawym dolnym rogu obrazu i zawierać tekst linku, np. „Zgłoś problem z tym obrazem”.

addressComponent

Uporządkowany kod geograficzny 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, które zawierają link do tej panoramy. Zawiera też nagłówek, w którym znajduje się link. Jeśli na przykład kierunek wynosi 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 ich używać przez więcej niż jedną 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. Żądanie miniatury możesz wysłać, wysyłając żą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 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"

Zobacz ten przykładowy kod, 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 wyświetlić. Wartości identyfikatora panoramy możesz uzyskać z punktu końcowego panoIds lub 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, od 16 do 250 pikseli. Jeśli nie określisz wysokości, domyślnie zostanie ustawiona maksymalna dozwolona wartość, czyli 250 pikseli. Jeśli podasz wartość spoza zakresu, miniatura przeskoczy 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 ustawiona maksymalna dozwolona wartość, czyli 600 pikseli. Jeśli podasz wartość spoza zakresu, miniatura przeskoczy 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ść domyślna to 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, z maksymalną wartością 120. W przypadku widocznego obszaru o stałym rozmiarze, np. zdjęcia Street View o określonym rozmiarze, pole widzenia reprezentuje powiększenie, gdzie mniejsze wartości oznaczają większe powiększenie. Wartością domyślną jest 90.

Kafelki zdjęć Street View

Gdy masz już panoId, możesz poprosić o kafelek obrazu Street View. Żądania fragmentów mapy to żądania GET HTTPS. Przyjrzyj 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ładowym kodzie z to poziom powiększenia, a x i y to współrzędne mapy kafelka Street View, który chcesz wyświetlić. 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	7 °C
4	22,5°
5	11,25°

Uwaga: zdjęcia Street View pochodzą z 2 źródeł: od Google (niepubliczne zdjęcia kontrolowane przez dewelopera) i od użytkowników (treści generowane przez użytkowników, czyli UGC). Pamiętaj, że nie można używać 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.

Przy 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ł pustą przestrzeń w wymiarze Y:

Na poziomie powiększenia 5 używana jest panorama w pełnym rozmiarze, która jest podzielona 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.

Informacje o prawach autorskich musisz wyświetlać przy każdej panoramie Street View. 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 możesz odwołać się do pola copyright w odpowiedzi. Więcej informacji znajdziesz w artykule Atrybucje danych.