Żą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ą rozdzielone znakiem „&”. 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 geograficznych (40.457375,-80.009353) i powinien być zakodowany w formacie URL. Dlatego przed wysłaniem żądania przekształć adresy takie jak „City Hall, New York, NY” na „City+Hall,New+York,NY”. Street View Static API dopasowuje się do panoramy sfotografowanej najbliżej lokalizacji. Gdy podasz ciąg tekstowy adresu, interfejs API może użyć innej lokalizacji kamery, aby lepiej wyświetlić podaną lokalizację. Gdy podasz współrzędne geograficzne, interfejs API wyszuka w promieniu 50 metrów zdjęcie najbliższe danej lokalizacji. Zdjęcia Street View są okresowo odświeżane, a fotografie mogą być za każdym razem wykonywane z nieco innych pozycji. Dlatego po aktualizacji zdjęć Twój location może przyciągać do innej panoramy.

Lub:

• pano to konkretny identyfikator panoramy. Panoramy mogą z czasem zmieniać identyfikator, więc nie zapisuj go. 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.

Oprócz tego:

• 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 się z Tobą skontaktować w sprawie aplikacji. Więcej informacji znajdziesz w artykule Uzyskiwanie klucza i podpisu.

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

Jeśli podczas próby pobrania identyfikatora panoramy otrzymasz wartość ZERO_RESULTS lub brak wartości, oznacza to, że identyfikator panoramy został usunięty i musisz go odświeżyć.

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

2. Gdy wykryjesz zmianę identyfikatora panoramy, użyj pierwotnej lokalizacji, adresu lub współrzędnych geograficznych, aby ponownie wyszukać najbliższe panoramy w tej lokalizacji i uzyskać nowy identyfikator panoramy.

Uwaga: obrazy Street View są okresowo odświeżane, a zdjęcia mogą być za każdym razem robione z nieco innych pozycji, dlatego dany identyfikator panoramy może po aktualizacji obrazów lub identyfikatora panoramy zostać przypisany do innej panoramy.

Parametry opcjonalne

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

  Uwaga: w przypadku klientów, którzy wcześniej korzystali z planu Premium Google Maps Platform, wymagany jest podpis cyfrowy. Więcej informacji o parametrach uwierzytelniania dla klientów korzystających z abonamentu Premium.

• heading określa na kompasie kierunek, w którym zwrócona jest kamera. Podaj wartość z zakresu od 0 do 360 (obie oznaczają północ, 90 to wschód, a 180 to południe). Jeśli nie określisz kierunku, zostanie obliczona taka wartość, dzięki której kamera znajdzie się w miejscu zrobienia najbliższego zdjęcia, zwrócona w kierunku wybranej lokalizacji location.
• 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 w zasadzie odpowiada powiększeniu. Mniejsze wartości oznaczają większe powiększenie.

  
  
  (Lewy: fov=120; Prawy: fov=20)

• pitch (domyślnie 0) określa kąt obrotu kamery w górę lub w dół względem standardowego ustawienia pojazdu Street View. Ustawienie domyślne to często (ale nie zawsze) kierunek poziomy. Wartości dodatnie powodują obrót kamery w górę (90 stopni oznacza pionowy widok w górę), a ujemne w dół (-90 oznacza pionowy widok w dół).
• radius (domyślnie 50) określa promień (w metrach), w którym ma być wyszukiwana panorama, wyśrodkowany na podanych współrzędnych geograficznych. Prawidłowe wartości to nieujemne liczby całkowite.
• return_error_code określa, czy interfejs API ma zwracać kod błędu, gdy nie znajdzie obrazu (404 NOT FOUND), czy w odpowiedzi na nieprawidłowe żądanie (400 BAD REQUEST). Prawidłowe wartości to true i false. Jeśli ta opcja ma wartość true, zamiast ogólnego szarego obrazu zwracany jest komunikat o błędzie. Eliminuje to konieczność wykonywania osobnego połączenia w celu sprawdzenia dostępności obrazu.
• source (domyślnie default) ogranicza wyszukiwania w Street View do wybranych źródeł. Prawidłowe wartości:
  • default korzysta z domyślnych źródeł Street View; wyszukiwania nie są ograniczone do konkretnych źródeł.
  • outdoor ogranicza wyszukiwanie do kolekcji zewnętrznych. Kolekcje w pomieszczeniach nie są uwzględniane w wynikach wyszukiwania. Pamiętaj, że panoramy zewnętrzne mogą nie istnieć w przypadku określonej lokalizacji. Pamiętaj też, że wyszukiwanie zwraca tylko panoramy, w przypadku których można określić, czy są to zdjęcia wnętrz czy przestrzeni zewnętrznych. Na przykład sferyczne zdjęcia 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, dla których nie są dostępne zdjęcia Street View, interfejs Street View Static API zwraca szare zdjęcie ogólne z tekstem „Przepraszamy, nie mamy tu zdjęć”, jak pokazano w tym przykładzie:

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

Pokaż tylko prawidłowe obrazy

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

• Ustaw parametr return_error_code na true. Jeśli dla określonej lokalizacji nie ma zdjęcia, interfejs Street View Static API zwraca błąd 404 NOT FOUND zamiast ogólnego szarego obrazu.
• Poproś o metadane obrazu Street View, aby przed wysłaniem prośby sprawdzić, czy dla określonej lokalizacji dostępne są zdjęcia.