Żądanie i odpowiedź w 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. Funkcje różnią się w zależności od regionu. Więcej informacji

Żądanie obrazu Street View to adres URL HTTP w tym formacie:

https://maps.googleapis.com/maps/api/streetview?parameters

Obraz jest określany za pomocą parametrów żądania. Zgodnie ze standardem adresów URL wszystkie parametry są oddzielone znakiem ampersand (&). Dozwolone parametry i ich możliwe wartości znajdziesz poniżej.

Wymagane parametry

Wykonaj jedną z tych czynności:

• location może być ciągiem tekstowym (np. Chagrin Falls, OH) lub parą współrzędnych szerokości i długości geograficznej (40.457375,-80.009353) i powinien być zakodowany w adresie URL. Dlatego przed wysłaniem żądania przekonwertuj adresy takie jak „City Hall, New York, NY” na „City+Hall,New+York,NY”. Street View Static API przyciąga do zdjęcia panoramicznego najbliższego lokalizacji. Gdy podasz ciąg tekstowy adresu, interfejs API może użyć innej lokalizacji kamery, aby lepiej wyświetlić określoną lokalizację. Gdy podasz szerokość i długość geograficzną, interfejs API wyszuka w promieniu 50 metrów zdjęcie najbliższe tej lokalizacji. Zdjęcia Street View są okresowo odświeżane i mogą być robione z nieco innych pozycji, dlatego po aktualizacji zdjęć location może zostać przyciągnięty do innej panoramy.

Lub:

• pano to identyfikator konkretnej panoramy. Identyfikatory panoram mogą się zmieniać, więc nie zapisuj ich na stałe. Zamiast tego zapisz adres lokalizacji lub współrzędne szerokości i długości geograficznej, aby móc odświeżyć identyfikator panoramy. Więcej informacji znajdziesz w sekcji Odświeżanie usuniętych identyfikatorów panoram.

oraz:

• size określa rozmiar wyjściowy obrazu w pikselach. Rozmiar jest określany jako {width}x{height} – na przykład size=600x400 zwraca obraz o szerokości 600 pikseli i wysokości 400 pikseli.
• key umożliwia monitorowanie wykorzystania interfejsu API aplikacji w konsoli Google Cloud i zapewnia, że w razie potrzeby Google może skontaktować się z Tobą w sprawie aplikacji. Więcej informacji znajdziesz w artykule Uzyskiwanie klucza i podpisu.

Odświeżanie usuniętych identyfikatorów panoram

Jeśli spróbujesz pobrać identyfikator panoramy i otrzymasz wartość ZERO_RESULTS lub nie otrzymasz żadnej wartości, oznacza to, że identyfikator panoramy został usunięty i należy go odświeżyć.

1. Zapisz adres lokalizacji lub współrzędne geograficzne, których użyto do uzyskania identyfikatora panoramy, aby móc go odświeżyć w razie potrzeby.

2. Jeśli wykryjesz, że identyfikator panoramy uległ zmianie, użyj pierwotnego adresu lokalizacji lub współrzędnych geograficznych, aby ponownie wyszukać najbliższe panoramy dla tej lokalizacji i uzyskać nowy identyfikator panoramy.

Uwaga: zdjęcia Street View są okresowo odświeżane i za każdym razem mogą być robione z nieco innych pozycji, dlatego dany identyfikator panoramy może zostać przypisany do innej panoramy, gdy zdjęcia lub identyfikator panoramy zostaną zaktualizowane.

Parametry opcjonalne

• signature (zalecany) to podpis cyfrowy używany do sprawdzania, czy każda witryna generująca żądania za pomocą Twojego klucza interfejsu API ma do tego uprawnienia. Żądania, które nie zawierają podpisu cyfrowego, mogą się nie powieść. Więcej informacji znajdziesz w artykule Uzyskiwanie klucza i podpisu.

  Uwaga: w przypadku byłych klientów abonamentu Google Maps Platform Premium podpis cyfrowy jest wymagany. Dowiedz się więcej o parametrach uwierzytelniania dla klientów korzystających z abonamentu Premium.

• heading wskazuje kierunek kompasu kamery. Akceptowane wartości mieszczą się w zakresie od 0 do 360 (obie wartości oznaczają północ, 90 – wschód, a 180 – południe). Jeśli nie określisz kierunku, zostanie obliczona wartość, która skieruje kamerę w stronę określonego elementu location z punktu, w którym zrobiono najbliższe zdjęcie.
• fov (domyślnie 90) określa poziome pole widzenia obrazu wyrażone w stopniach, przy czym maksymalna dozwolona wartość to 120. W przypadku widocznego obszaru o stałym rozmiarze, np. zdjęcia Street View o określonym rozmiarze, pole widzenia zasadniczo reprezentuje powiększenie, przy czym mniejsze liczby oznaczają większy poziom powiększenia.

  
  
  (lewe: fov=120; prawe: fov=20)

• pitch (wartość domyślna to 0) określa kąt nachylenia kamery w górę lub w dół względem pojazdu Street View. Często, ale nie zawsze, jest to płaska linia pozioma. Wartości dodatnie oznaczają kąt kamery w górę (90 stopni oznacza skierowanie prosto w górę), a wartości ujemne – kąt kamery w dół (-90 stopni oznacza skierowanie prosto w dół).
• radius (domyślnie 50) ustawia promień (w metrach), w którym ma być wyszukiwana panorama, wyśrodkowany na podanej szerokości i długości geograficznej. Prawidłowe wartości to nieujemne liczby całkowite.
• return_error_code wskazuje, czy interfejs API powinien zwracać kod błędu, gdy nie zostanie znaleziony żaden obraz (404 NOT FOUND) lub w odpowiedzi na nieprawidłowe żądanie (400 BAD REQUEST). Prawidłowe wartości to true i false. Jeśli ustawisz wartość true, zamiast ogólnego szarego obrazu pojawi się komunikat o błędzie. Dzięki temu nie trzeba wykonywać osobnego wywołania, aby sprawdzić dostępność obrazu.
• source (domyślnie default) ogranicza wyszukiwanie w Street View do wybranych źródeł. Prawidłowe wartości to:
  • default używa domyślnych źródeł Street View; wyszukiwanie nie jest ograniczone do konkretnych źródeł.
  • outdoor ogranicza wyszukiwanie do kolekcji zewnętrznych. Kolekcje zdjęć z wnętrz nie są uwzględniane w wynikach wyszukiwania. Pamiętaj, że dla określonej lokalizacji mogą nie istnieć panoramy zewnętrzne. Pamiętaj też, że wyszukiwanie zwraca tylko panoramy, w przypadku których można określić, czy są one wewnątrz czy na zewnątrz. Na przykład zdjęcia sferyczne nie są zwracane, ponieważ nie wiadomo, czy zostały zrobione w pomieszczeniu czy na zewnątrz.

To jest przykładowe żądanie.

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=46.414382,10.013988&heading=151.78&pitch=-0.76&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Brak dostępnych zdjęć

W przypadku lokalizacji, w których zdjęcia Street View są niedostępne, interfejs Street View Static API zwraca szary obraz ogólny z tekstem „Przepraszamy, nie mamy tu żadnych zdjęć”, jak w tym przykładzie:

Ilustracja: ogólny obraz wyświetlany, gdy nie są dostępne żadne zdjęcia dla określonej lokalizacji.

Pokaż tylko prawidłowe obrazy

Aby uniknąć wyświetlania obrazu ogólnego i mieć pewność, że na stronie internetowej będą wyświetlane tylko prawidłowe obrazy Street View Static API, postępuj zgodnie z tymi sugestiami:

• Ustaw parametr return_error_code na true. Jeśli dla określonej lokalizacji nie jest dostępny żaden obraz, interfejs Street View Static API zwraca błąd 404 (NIE ZNALEZIONO) zamiast ogólnego szarego obrazu.
• Przed wysłaniem żądania poproś o metadane zdjęć Street View, aby sprawdzić, czy dla określonej lokalizacji są dostępne zdjęcia.