Żądanie i odpowiedź w Street View

Żądanie 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 „&”. Poniżej znajdziesz listę dozwolonych parametrów i ich możliwych wartości.

Wymagane parametry

Wykonaj jedną z tych czynności:

• 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 pozycji kamery, aby lepiej wyświetlić określoną lokalizację. Gdy podasz współrzędne geograficzne, interfejs API przeszuka obszar o promieniu 50 metrów wokół tej 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, gdy zdjęcia zostaną zaktualizowane.

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 panoram

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 używany do weryfikacji, czy witryna generują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 subskrypcji 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 (domyślnie 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. w przypadku zdjęcia w Street View o stałym rozmiarze, pole widzenia w podstawie odpowiada powiększaniu, a mniejsze liczby oznaczają większy stopień powiększenia.

  
  
  (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 oznacza 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 zwrócony zostanie 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 używa domyślnych źródeł Street View; wyszukiwania nie są ograniczone do określonych ź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 których przypadku można określić, czy są one 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

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 zdjęć”, jak w tym przykładzie:

Pokaż tylko prawidłowe obrazy

Aby uniknąć wyświetlania ogólnego obrazu i zapewnić, ż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.