Żądanie i odpowiedź w Street View

Żądanie zdjęcia Street View to adres URL HTTP w 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ą rozdzielone znakami ampersand (&). Poniżej znajdziesz dozwolone parametry i ich możliwe 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 powinno być zakodowane na potrzeby adresu URL. Dlatego przed wysłaniem prośby przekonwertuj adresy takie jak „Urząd Miasta, Nowy Jork, NY” na „City+Hall,Nowy+Jork,NY”. Interfejs Street View Static API przyciąga do zdjęcia panoramicznego znajdującego się najbliżej lokalizacji. Gdy podasz ciąg tekstowy adresu, interfejs API może użyć innej lokalizacji kamery, aby lepiej ją wyświetlić. Po podaniu współrzędnych szerokości i długości geograficznej interfejs API wyszukuje zdjęcie najbliżej lokalizacji o promieniu 50 metrów. Zdjęcia Street View są okresowo odświeżane, a zdjęcia mogą być za każdym razem wykonywane w nieco innych miejscach. Dlatego po aktualizacji zdjęć Twój location może zmienić się w inną panoramę.

lub:

  • pano to specjalny identyfikator panoramy. Identyfikator panoramy może się z czasem zmienić, więc nie zapamiętuj go. Zamiast tego zapisz adres lokalizacji lub współrzędne szerokości i długości geograficznej, by móc odświeżyć identyfikator panoramy. Więcej informacji znajdziesz w opisie odświeżania usuniętych identyfikatorów panoram.

a także:

  • size określa rozmiar wyjściowy obrazu w pikselach. Rozmiar jest podawany jako {width}x{height} – np. size=600x400 zwraca obraz o szerokości 600 pikseli i wysokości 400 pikseli.
  • key umożliwia monitorowanie korzystania z interfejsu API przez aplikację w Google Cloud Console i zapewnia, że w razie potrzeby Google może się z Tobą skontaktować w sprawie Twojej aplikacji. Więcej informacji znajdziesz w artykule na temat uzyskiwania klucza i podpisu.

Odśwież usunięte identyfikatory panoram

Jeśli przy próbie pobrania identyfikatora panoramy zobaczysz ZERO_RESULTS lub brak wartości, oznacza to, że został on usunięty i trzeba go odświeżyć.

  1. Zapisz adres lokalizacji lub współrzędne geograficzne, które zostały użyte do uzyskania identyfikatora panoramy, aby w razie potrzeby można było go odświeżyć.

  2. Po wykryciu zmiany identyfikatora panoramy użyj pierwotnego adresu lokalizacji lub współrzędnych geograficznych, aby wyszukać najbliższe panoramy i uzyskać nowy identyfikator.

Parametry opcjonalne

  • signature (zalecany) to podpis cyfrowy używany do sprawdzania, czy wszystkie witryny generujące żądania przy użyciu klucza interfejsu API są do tego uprawnione. Żądania, które nie zawierają podpisu cyfrowego, mogą zakończyć się niepowodzeniem. Więcej informacji znajdziesz w artykule na temat uzyskiwania klucza i podpisu.

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

  • heading wskazuje na kompasie kierunek, w którym powinien znajdować się aparat. Akceptowane są wartości od 0 do 360 (obie oznaczają północ, 90 to wschód, a 180 południe). Jeśli nie określisz kierunku, zostanie obliczona taka wartość, która skieruje kamerę w kierunku wskazanego miejsca location od miejsca, w którym zostało zrobione 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, tak jak w przypadku zdjęcia Street View o określonym rozmiarze, pole widoku właściwie reprezentuje powiększenie, a mniejsze liczby oznaczają większy poziom powiększenia.


    Zrzut ekranu z szerokim zakresem widzenia obejmujący sufit, ściany, podłogę i okno zbiornika wewnątrz oceanarium. Zrzut ekranu przedstawiający zbliżenie na szczegóły zdjęcia Street View wewnątrz akwarium.
    (po lewej: fov=120; Prawa: fov=20)

  • pitch (wartość domyślna to 0) określa kąt obrotu kamery w górę lub w dół w odniesieniu do pojazdu Street View. Często, ale nie zawsze, wykonywana jest płaska orientacja pozioma. 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ń (wyrażony w metrach), w którym można wyszukać panoramę, wyśrodkowany 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 zwracać kod błędu w przypadku braku obrazu (404 NOT FOUND) czy w odpowiedzi na nieprawidłowe żądanie (400 BAD REQUEST). Prawidłowe wartości to true i false. Jeśli ma wartość true, w miejscu ogólnego szarego obrazu jest zwracany komunikat o błędzie. Dzięki temu nie będzie trzeba wykonywać osobnego wywołania w celu sprawdzenia dostępności obrazu.
  • source (wartość domyślna to default) ogranicza wyszukiwania 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 konkretnych źródeł.
    • outdoor ogranicza wyszukiwanie do kolekcji zewnętrznych. Kolekcje wnętrz nie są uwzględniane w wynikach wyszukiwania. Pamiętaj, że w przypadku podanej lokalizacji panoramy zewnętrzne mogą nie istnieć. Pamiętaj też, że wyszukiwanie zwróci panoramy tylko wtedy, gdy 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 znajdują się wewnątrz 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 z punktu widzenia na poziomie ulicy, na którym widać elektryczne tory kolejowe.

Brak dostępnych zdjęć

W przypadku lokalizacji, w których zdjęcia Street View są niedostępne, interfejs Street View Static API zwraca szary obraz ogólny z tekstem „Nie mamy tutaj zdjęć”, jak w tym przykładzie:

Zrzut ekranu przedstawiający ogólne zdjęcie wyświetlane, gdy nie ma dostępnych zdjęć danej lokalizacji. Tło jest jasnobrązowe i wyświetla tekst: „Nie mamy tutaj żadnych zdjęć”.
Rysunek: zdjęcie ogólne wyświetlane, gdy nie ma dostępnych zdjęć danej lokalizacji.

Pokaż tylko prawidłowe obrazy

Aby uniknąć wyświetlania ogólnego zdjęcia i mieć pewność, że na Twojej stronie wyświetlają się tylko prawidłowe obrazy Street View Static API, zastosuj się do tych wskazówek:

  • Ustaw parametr return_error_code na true. W takiej sytuacji interfejs Street View Static API zwraca błąd 404 NOT FOUND zamiast ogólnego szarego obrazu, jeśli dla określonej lokalizacji nie ma zdjęcia.
  • Przed wysłaniem prośby o metadane zdjęcia w Street View możesz sprawdzić, czy w danej lokalizacji są dostępne zdjęcia.