Żą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 stosowanym w adresach URL, wszystkie parametry są rozdzielone 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 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 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 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 przez aplikację 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 należy go odświeżyć.

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

2. Gdy wykryjesz, że identyfikator panoramy uległ zmianie, 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 z wcześniejszego planu Premium Google Maps Platform, wymagany jest podpis cyfrowy. Więcej informacji znajdziesz w tym artykule.

• 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 widoku o stałym rozmiarze, np. obrazu Street View o ustalonym rozmiarze, pole widzenia w istocie reprezentuje powiększenie, a mniejsze liczby oznaczają wyższy poziom powiększenia.

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

• pitch (domyślnie: 0) określa kąt widzenia kamery w górę lub w dół względem pojazdu w Street View. Często, ale nie zawsze, jest to powierzchnia płaska i pozioma. Wartości dodatnie ustawiają kąt kamery w górę (90 stopni oznacza kamerę prosto w górę), a wartości ujemne ustawiają kąt kamery w dół (-90 oznacza kamerę prosto w dół).
• radius (domyślnie: 50) ustawia promień, określony w metrach, w którym należy szukać panoramy, której środek znajduje się na podanej szerokości i długości geograficznej. Prawidłowe wartości to nieujemne liczby całkowite.
• return_error_code wskazuje, czy API powinno zwrócić 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 ustawione na 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 wyszukiwanie w Street View do wybranych źródeł. Prawidłowe wartości to:
  • default korzysta z domyślnych źródeł Street View. Wyszukiwanie nie jest ograniczone do określonych ź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 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 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.