Żądanie i odpowiedź w Street View

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Żą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 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”. Interfejs Street View Static API przyciąga do panoramy najbliższej 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 szerokości i długości geograficznej, interfejs API wyszuka w promieniu 50 metrów zdjęcie najbliższe 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 należy 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, że identyfikator panoramy uległ zmianie, użyj pierwotnej lokalizacji, adresu lub współrzędnych geograficznych, aby ponownie wyszukać najbliższe panoramy w tej lokalizacji i uzyskać nowy identyfikator 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 parametrach uwierzytelniania dla klientów korzystających z abonamentu Premium.

  • heading – wskazuje kierunek kompasu, w którym skierowana jest kamera. Akceptowane wartości mieszczą się w zakresie od 0 do 360 (obie wartości oznaczają północ, przy czym 90 oznacza wschód, a 180 – południe). Jeśli nie określisz kierunku, zostanie obliczona wartość, która skieruje kamerę w stronę określonego punktu location z miejsca, w którym zrobiono najbliższe zdjęcie.
  • fov (domyślnie 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. obrazu Street View o określonym rozmiarze, pole widzenia w zasadzie reprezentuje powiększenie. Mniejsze wartości oznaczają większy poziom powiększenia.


    Zrzut ekranu przedstawiający szerokie pole widzenia, obejmujące sufit, ściany, podłogę i okno zbiornika w akwarium. Zrzut ekranu przedstawiający pole widzenia zbliżonego ujęcia, na którym widać powiększony szczegół zdjęcia Street View w akwarium.
    (Lewy: fov=120; Prawy: 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 powodują skierowanie kamery w górę (90 stopni oznacza skierowanie prosto w górę), a ujemne – w dół (-90 stopni oznacza skierowanie prosto w dół).
  • radius (domyślnie 50) określa 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 określa, czy interfejs API ma zwracać kod błędu, gdy nie znajdzie obrazu (404 NOT FOUND) lub 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. 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 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 są to zdjęcia wnętrz czy przestrzeni zewnętrznych. 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
Zrzut ekranu ze zdjęciem punktu widokowego na poziomie ulicy przedstawiającym zelektryfikowane tory kolejowe.

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 pokazano w tym przykładzie:

Zrzut ekranu przedstawiający ogólny obraz wyświetlany, gdy dla określonej lokalizacji nie są dostępne żadne zdjęcia. Tło jest jasnobrązowe i zawiera tekst „Przepraszamy, nie mamy zdjęć tego miejsca”.
Ilustracja: ogólny obraz wyświetlany, gdy dla określonej lokalizacji nie są dostępne żadne zdjęcia.

Wyświetlanie tylko prawidłowych obrazów

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 jest dostępny żaden obraz, 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.