Żą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 przekonwertuj adresy takie jak „City Hall, New York, NY” na „City+Hall,New+York,NY”. Street View Static API przyciąga do panoramy sfotografowanej najbliżej lokalizacji. Gdy podasz ciąg znaków z adresem, 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 wskazywać inną panoramę.

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}, np. 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 odświeżyć dane.

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

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

Parametry opcjonalne

• signature (zalecane) to podpis cyfrowy używany do weryfikacji, 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 korzystali wcześniej z Google Maps Platform w ramach planu Premium, wymagany jest podpis cyfrowy. Więcej informacji znajdziesz w sekcji parametry 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ślna wartość to 90) określa poziome pole widzenia obrazu wyrażone w stopniach, a 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 stopni oznacza pionowy widok w dół).
• radius (domyślnie 50) określa promień (w metrach), w którym ma być wyszukiwana panorama wyśrodkowana na podanej szerokości i długości geograficznej. 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 to pole ma wartość true, zamiast ogólnego szarego obrazu zwracany jest komunikat o błędzie. Dzięki temu nie trzeba wykonywać osobnego wywołania, aby sprawdzić dostępność obrazu.
• source (domyślnie default) ogranicza wyszukiwania w Street View do wybranych źródeł. Prawidłowe wartości to:
  • 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 Indoor 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 zostały wykonane wewnątrz czy na zewnątrz. Na przykład nie są zwracane sferyczne zdjęcia, 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 tutaj zdjęć”, jak w tym przykładzie:

Ilustracja: ogólny obraz wyświetlany, gdy dla podanej 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, skorzystaj z tych sugestii:

• 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.