Sprawdzone metody korzystania ze statycznego interfejsu API Map Google

Statyczne internetowe interfejsy API Google Maps Platform to zbiór interfejsów HTTP do usług Google generujące obrazy, które możesz umieścić bezpośrednio na stronie.

W tym przewodniku opisano kilka typowych metod, które są przydatne podczas konfigurowania żądań obrazu i przetwarzania odpowiedzi usługi. Pełną dokumentację interfejsu Maps Static API znajdziesz w przewodniku dla programistów.

Czym jest statyczny interfejs API sieciowy?

Statyczne internetowe interfejsy API Google Maps Platform pozwalają umieścić obraz z Map Google na stronie internetowej bez konieczności stosowania JavaScriptu ani dynamicznego wczytywania stron. Statyczne internetowe interfejsy API tworzą obraz na podstawie parametrów adresu URL wysyłanych za pomocą standardowego żądania HTTPS.

Typowe żądanie do interfejsu Maps Static API ma zwykle następujący format:

  https://www.googleapis.com/staticmap/z/x/y?parameters

Uwaga: wszystkie aplikacje Maps Static API wymagają uwierzytelniania. Dowiedz się więcej o danych uwierzytelniających.

Dostęp przez SSL/TLS

Protokół HTTPS jest wymagany w przypadku wszystkich żądań Google Maps Platform, które korzystają z kluczy interfejsu API lub zawierają dane użytkowników. Żądania przesłane za pomocą protokołu HTTP, które zawierają dane wrażliwe, mogą zostać odrzucone.

Tworzenie prawidłowego adresu URL

Może Ci się wydawać, że „prawidłowy” adres URL jest oczywisty, ale nie jest to słuszne. Na przykład adres URL wpisany w pasku adresu w przeglądarce może zawierać znaki specjalne (np."上海+中國"). Przed przesłaniem przeglądarka musi je wewnętrznie przetłumaczyć na inne kodowanie. Na podstawie tego samego tokena każdy kod generujący lub akceptujący dane wejściowe w formacie UTF-8 może traktować adresy URL ze znakami UTF-8 jako „prawidłowe”, ale przed wysłaniem ich na serwer WWW musiałby je przetłumaczyć. Ten proces nazywa się kodowaniem adresów URL lub kodowaniem procentowym.

Znaki specjalne

Musimy tłumaczyć znaki specjalne, ponieważ wszystkie adresy URL muszą być zgodne ze składnią określoną w specyfikacji identyfikatora zasobów (Uniform Resource Identifier). Oznacza to, że adresy URL mogą zawierać tylko specjalny podzbiór znaków ASCII: znane symbole alfanumeryczne i niektóre znaki zarezerwowane, które mogą być używane jako znaki kontrolne w adresach URL. W tej tabeli podsumowano te znaki:

Podsumowanie prawidłowych znaków adresu URL
UstawznakówWykorzystanie adresów URL
Znaki alfanumeryczne a b c d e f g h i j k l m n o p q r s t u v s x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 Ciągi tekstowe, użycie schematu (http), port (8080) itp.
Niezarezerwowane – _ . ~ Ciągi tekstowe
Zarezerwowano ! * ' ( ) ; : @ & = + $ , / ? % [ ] Znaki kontrolne i ciągi tekstowe

Podczas tworzenia prawidłowego adresu URL musisz się upewnić, że zawiera on tylko znaki widoczne w tabeli Podsumowanie prawidłowych znaków adresu URL. Stworzenie adresu URL tak, aby użyć tego zestawu znaków, zwykle prowadzi do 2 problemów: pominięcia i zastąpienia:

  • Znaki, które chcesz obsługiwać, znajdują się poza powyższym zestawem. Na przykład znaki w językach obcych, takich jak 上海+中國, muszą być zakodowane przy użyciu powyższych znaków. Zgodnie z popularną konwencją spacje (które nie są dozwolone w adresach URL) są często oznaczane również znakiem plusa '+'.
  • W powyższym zestawie znaków występują znaki zarezerwowane, ale muszą być używane dosłownie. Na przykład znak ? jest używany w adresach URL do wskazywania początku ciągu zapytania. Jeśli chcesz użyć ciągu „?” i wiersza Mysterions, musisz zakodować znak '?'.

Wszystkie znaki przeznaczone do kodowania URL są kodowane za pomocą znaku '%' i dwuznakowej wartości szesnastkowej odpowiadającej ich znakowi UTF-8. Na przykład tekst 上海+中國 w UTF-8 będzie zakodowany na potrzeby adresu URL jako %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. Ciąg znaków ? and the Mysterians będzie zakodowany na potrzeby adresu URL jako %3F+and+the+Mysterians lub %3F%20and%20the%20Mysterians.

Typowe znaki wymagające kodowania

Oto kilka typowych znaków, które muszą być zakodowane:

Niebezpieczny znak Zakodowana wartość
Miejsce %20
%22
< %3C
> %3E
# %23
% %25
| %7C

Konwertowanie adresu URL uzyskanego z danych wejściowych użytkownika jest czasem trudne. Na przykład użytkownik może wpisać adres „ul. Główna i Piąta”. Adres URL zasadniczo powinien składać się z części, traktując wszystkie dane wejściowe użytkownika jako znaki literackie.

Dodatkowo adresy URL w usługach internetowych Google Maps Platform i statycznych internetowych interfejsach API mogą mieć maksymalnie 16 384 znaki. W przypadku większości usług ten limit znaków rzadko jest zbliżany do osiągnięcia tego limitu. Pamiętaj jednak, że niektóre usługi mają kilka parametrów, które mogą powodować długie adresy URL.