Żądanie i odpowiedź w Street View

Żądanie dotyczące obrazu Street View to adres URL HTTP o takim formacie:

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

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

Wymagane parametry

Wykonaj jedną z tych czynności:

  • Wartość 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 powinna być zakodowana w formacie URL. Dlatego przed wysłaniem prośby zmień adresy takie jak „Urząd Miasta, Nowy Jork, NY” na „Urząd+Miasta,Nowy+Jork,NY” Street View Static API wybiera panoramę najbliższą danej 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 współrzędne geograficzne, interfejs API przeszuka obszar o promieniu 50 metrów wokół lokalizacji, aby znaleźć zdjęcie najbliższe tej lokalizacji. Zdjęcia Street View są okresowo aktualizowane, a zdjęcia mogą być robione z nieco innych pozycji, dlatego location może się przypiąć do innej panoramy po zaktualizowaniu zdjęć.

Lub:

  • pano to identyfikator konkretnej panoramy. Identyfikator panoramy może się zmienić w czasie, dlatego nie zapisuj tego identyfikatora. 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 artykule Odświeżanie usuniętego identyfikatora panoramy.

A także:

  • size określa rozmiar wyjściowy obrazu w pikselach. Rozmiar jest określony jako {width}x{height} – na przykład size=600x400zwraca 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 panoramy

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

  1. Zapisz adres lokalizacji lub współrzędne szerokości i długości geograficznej, których użyłeś/użyłaś do uzyskania identyfikatora panoramy, aby w razie potrzeby móc je odświeżyć.

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

Parametry opcjonalne

  • signature (zalecane) to podpis cyfrowy służący do weryfikacji, czy witryna wysyłająca żądania za pomocą klucza interfejsu API ma do tego uprawnienia. Żądania, które nie zawierają podpisu cyfrowego, mogą nie zostać zrealizowane. Więcej informacji znajdziesz w artykule Uzyskiwanie klucza i podpisu.

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

  • heading wskazuje na kompasie kierunek, w którym zwrócona jest kamera. Akceptowane wartości to 0–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 (wartość domyślna: 90) określa poziome pole widzenia obrazu wyrażone w stopniach. Maksymalna dozwolona wartość to 120. W przypadku widocznego obszaru o stałym rozmiarze, np. obrazu Street View o stałym rozmiarze, pole widzenia w podstawie reprezentuje powiększenie, a mniejsze wartości wskazują na większy stopień powiększenia.


    Zrzut ekranu przedstawiający szerokie pole widzenia, na którym widać sufit, ściany, podłogę i okno akwarium. Zrzut ekranu przedstawiający zbliżenie z widokiem z poziomu oczu, na którym widać szczegóły zdjęcia Street View w akwarium.
    (po lewej: fov=120, po prawej: 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 to pionowy widok w dół).
  • radius (domyślnie 50) ustawia promień (w metrach) w którym ma być wyszukiwana panorama wyśrodkowana na danej szerokości i długości geograficznej. Prawidłowe wartości to nieujemne liczby całkowite.
  • return_error_code wskazuje, czy interfejs API powinien zwrócić kod błędu, gdy nie zostanie znaleziony żaden obraz (404 NOT FOUND), czy 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 zwracany będzie 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 na zewnątrz. Kolekcje indoor nie są uwzględniane w wynikach wyszukiwania. Pamiętaj, że w przypadku wybranej lokalizacji panoramy zewnętrzne mogą nie istnieć. Pamiętaj też, że wyszukiwanie zwraca tylko panoramy, w przypadku których można określić, czy znajdują się 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.

Oto 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 przedstawiający zdjęcie z punktu widokowego na poziomie ulicy pokazujące zelektryfikowane tory kolejowe.

Brak dostępnych obrazów

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

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

Pokaż tylko prawidłowe obrazy

Aby uniknąć wyświetlania ogólnego obrazu i upewnić się, że Twoja strona internetowa wyświetla 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 ma dostępnego zdjęcia, zamiast ogólnego szarego zdjęcia interfejs Street View Static API zwraca błąd 404 NOT FOUND.
  • Przed wysłaniem prośby o dostęp do danych metadanych zdjęć Street View, aby sprawdzić, czy w wybranej lokalizacji są dostępne zdjęcia.