Google Maps Platform の静的ウェブ API は、ウェブページに直接埋め込むことができる画像を生成する Google サービスの HTTP インターフェースのコレクションです。
このガイドでは、画像リクエストの設定とサービス レスポンスの処理について、一般的なプラクティスをいくつか説明します。Maps Static API の詳細については、デベロッパー ガイドをご覧ください。
静的ウェブ API とは
Google Maps Platform の静的ウェブ API を使用すると、JavaScript や動的なページ読み込みを必要とせずに、Google マップの画像をウェブページに埋め込むことができます。静的ウェブ API は、標準の HTTPS リクエストを使用して送信される URL パラメータに基づいて画像を作成します。
一般的な Maps Static API リクエストの形式は次のとおりです。
https://www.googleapis.com/staticmap/z/x/y?parameters
注: Maps Static API アプリケーションではすべて認証が必要です。詳細については、認証情報をご覧ください。
TLS アクセス
API キーを使用する、またはユーザーデータを含むすべての Google Maps Platform リクエストには HTTPS が必要です。センシティブ データを含む HTTP 経由のリクエストは拒否される可能性があります。
有効な URL の作成
「有効」な URL とは何か、説明の必要はないと考えられるかもしれませんが、それほど単純なことではありません。ブラウザのアドレスバーに入力される URL には特殊文字（"上海+中國" など）が含まれている場合があります。このような特殊文字は、ブラウザで別のエンコードに内部的に変換してから送信する必要があります。同様に、UTF-8 入力を生成または受け付けるコードでは、UTF-8 の文字が使用された URL を「有効」な URL として扱うことがありますが、それらの文字はウェブサーバーに送信する前に変換する必要があります。このプロセスは、URL エンコードまたはパーセント エンコードと呼ばれます。
特殊文字
すべての URL は URI（Uniform Resource Identifier）仕様で規定されている構文に従う必要があるため、特殊文字を変換する必要があります。つまり、URL には、ASCII 文字の特別なサブセット（よく使用される英数記号および URL 内で制御文字として使用される予約文字）のみを含める必要があります。次の表は、こうした特殊記号をまとめたものです。
| セット | 文字 | URL での使用法 |
|---|---|---|
| 英数字 | 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 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 9 | テキスト文字列、スキームでの使用（http）、ポート（8080）など |
| 未予約 | - _ . ~ | テキスト文字列 |
| 予約済み | ! * ' ( ) ; : @ & = + $ , / ? % # [ ] | 制御文字やテキスト文字列 |
有効な URL を作成するときは、表に記載されている文字のみを使用する必要があります。しかし、URL での使用がこの文字セットだけに制限された場合、通常は 2 つの問題が発生します。1 つは省略、もう 1 つは置き換えです。
- 処理する文字が上記のセットに含まれない場合。たとえば、「
上海+中國」のような英語以外の文字は、上記の文字を使用してエンコードする必要があります。一般的な命名規則では、URL 内で使用できないスペースもプラス記号'+'を使用して表します。 - 上記のセットに予約文字として含まれる文字を、リテラル文字として使用する必要がある場合。たとえば、「
?」は URL 内でクエリ文字列の先頭を示すために使用されます。文字列「? and the Mysterions」を使用する場合は、文字'?'をエンコードする必要があります。
URL エンコードが必要なすべての文字を、'%' と、UTF-8 文字に対応する 2 文字の 16 進数値を使用してエンコードします。たとえば、UTF-8 の「上海+中國」は、「%E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B」として URL エンコードされます。文字列「? and the Mysterians」は、「%3F+and+the+Mysterians」または「%3F%20and%20the%20Mysterians」として URL エンコードされます。
エンコードが必要な一般的な文字
エンコードする必要がある一般的な文字は次のとおりです。
| 危険な文字 | エンコードされた値 |
|---|---|
| スペース | %20 |
| " | %22 |
| < | %3C |
| > | %3E |
| # | %23 |
| % | %25 |
| | | %7C |
ユーザー入力から受け取った URL の変換には、場合によって注意が必要です。たとえば、ユーザーが住所を「5th&Main St.」と入力することも考えられます。通常は、ユーザー入力をリテラル文字として処理して、URL をパーツから作成する必要があります。
さらに、URL は、すべての Google Maps Platform ウェブサービスと Static Web API で 16,384 文字に制限されています。ほとんどのサービスでは、この文字制限に達することはめったにありません。ただし、複数のパラメータを持つ特定のサービスでは、URL が長くなる可能性があります。