以上で完了です。

開発を始めるには、デベロッパー ドキュメント をご覧下さい。

Google Static Maps API をアクティベートする

まず初めに Google Developers Console で次の作業を行います。

  1. プロジェクトを作成または選択する
  2. Google Static Maps API をアクティベートする
  3. 適切なキーを作成する
続ける

Google Static Maps デベロッパー ガイド

Google Static Maps API を使用すると、JavaScript などの動的なページ読み込みを使用せずに Google マップの画像をウェブページに埋め込むことができます。標準 HTTP リクエスト経由で URL パラメータを送信すると、Google Static Maps API サービスは、それに基づいてマップを生成し、ウェブページに表示できる画像を返します。

注: Google Static Maps API の使用制限が変更されました。API キーを作成してリクエストに含めることによって、 Google API Console で使用状況を追跡し、必要に応じて追加の割り当てを購入できるようになっています。

このドキュメントで説明しているのは、Google Static Maps API v2 です。v1 の URL を更新する方法は、アップグレード ガイドをご覧ください。

簡単な例

次の例は、ニューヨーク市の繁華街を示す Google Static Maps API の画像(例の下に表示されています)の URL です。

https://maps.googleapis.com/maps/api/staticmap?center=Brooklyn+Bridge,New+York,NY&zoom=13&size=600x300&maptype=roadmap
&markers=color:blue%7Clabel:S%7C40.702147,-74.015794&markers=color:green%7Clabel:G%7C40.711614,-74.012318
&markers=color:red%7Clabel:C%7C40.718217,-73.998284
&key=YOUR_API_KEY

ロウアー マンハッタンの有名スポット

この画像をページに表示するために、特別なことを行う必要がないことに注意してください。JavaScript を使う必要もなく、URL を作成して <img> タグの中に入れるだけです。Google Static Maps API の画像は、ウェブページ上に画像を配置できる場所であればどこにでも配置できます。

対象読者

このドキュメントは、Google Static Maps API 画像を含むウェブサイトやモバイル端末向けのアプリケーションを開発するデベロッパーを対象としています。また、API の使用の概要や使用可能なパラメータに関するリファレンス マテリアルを示しています。

概要

Google Static Maps API は、URL による HTTP リクエストへのレスポンスとして画像(GIF、PNG、JPEG のいずれか)を返します。各リクエストでは、マップ上の位置、画像のサイズ、ズームレベル、マップタイプ、マップ上のある位置に配置するオプションのマーカーを指定できます。また、英数字でマーカーにラベルを追加することもできます。

Google Static Maps API 画像は、<img> タグの src 属性や、他のプログラミング言語におけるそれと同等の要素に埋め込まれます。Google Static Maps API 画像をウェブベースのアプリケーション(ブラウザなど)以外で使用する場合は、ウェブブラウザ内で表示された位置へのリンク、またはネイティブ Google Maps アプリケーションへのリンクを含める必要があります(Google Maps APIs Premium Plan のユーザーは、この要件が免除されています)。現在の言語における完全な要件については、Google マップ / Google Earth 利用規約のセクション 10.1.1(h)をご覧ください。

このドキュメントでは、Google Static Maps API の URL の必要な形式や使用可能なパラメータについて説明します。また、URL を指定する際に役立つヒントやコツについても説明します。

URL パラメータ

Google Static Maps API の URL は次の形式に従う必要があります。

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

HTTPS でアクセスするウェブサイトでは、ブラウザのセキュリティ警告を避けるために、Google Static Maps API 画像も HTTPS で読み込む必要があります。リクエストに機密性の高いユーザー情報(ユーザーの位置情報など)を含む場合も、HTTPS を使用することをお勧めします。

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

HTTP と HTTPS のどちらを使用する場合でも、一部の URL パラメータには必須で、その他のパラメータは省略可能です。URL の標準と同様に、パラメータはすべてアンパサンド(&)文字を使用して区切ります。各パラメータと有効な値のリストを次に示します。

重要: わかりやすく説明するために、以下の URL パラメータの説明にはエスケープ前の形式を記載しています。API にリクエストを送信する前には、パラメータに対して適切な URL エンコードを行う必要があります。たとえば、多くのパラメータで、区切り文字としてパイプ文字(|)を使用しています。このドキュメントの最初の簡単な例で示したように、最終的な URL ではパイプ文字を %7C にエンコードする必要があります。詳細については、有効な URL を作成するをご覧ください。

Google Static Maps API は、以下の URL パラメータからマップの画像を定義します。

位置パラメータ

  • center(マーカーが存在しない場合は必須): すべての端から等距離であるマップの中心を定義します。このパラメータでは、コンマで区切った緯度と経度のペア {latitude,longitude}(例:「40.714728,-73.998672」)または住所を表す文字列(例:「city hall, new york, ny」)のどちらかによって、地球上の場所を一意に特定します。詳細については、後述の位置情報をご覧ください。
  • zoom(マーカーが存在しない場合は必須): マップの拡大率を示すズームレベルを定義します。このパラメータは、表示したい地域のズームレベルに対応する数値です。詳細については、後述のズームレベルをご覧ください。

マップ パラメータ

  • size(必須): マップ画像の四角形のサイズを定義します。このパラメータは、{horizontal_value}x{vertical_value} という形式の文字列です。たとえば、500x400 は幅 500 ピクセル、高さ 400 ピクセルのマップを定義します。幅が 180 ピクセル未満の小さなマップでは、縮小サイズの Google ロゴが表示されます。このパラメータは、後述する scale パラメータの影響を受けます。最終的な出力サイズは、size と scale の値の積となります。
  • scale(オプション): 返されるピクセル数に影響します。scale=2 の場合、scale=1 の 2 倍のピクセルが返されますが、対象の領域や詳細レベルは同じです(マップの内容は変わりません)。これは、高解像度のディスプレイ向けの開発を行う場合や、印刷用のマップを生成する場合に役立ちます。既定値は 1 です。設定可能な値は 244 は Google Maps APIs Premium Plan ユーザーのみ利用可能)です。詳細については、scale の値をご覧ください。
  • format(オプション): 返される画像の形式を定義します。デフォルトで、Google Static Maps API は PNG 画像を作成します。出力可能な形式の種類には、GIF、JPEG、PNG があります。どの形式を使用すべきかは、画像の表示方法によります。通常、JPEG は圧縮率が高くなりますが、GIF や PNG の方が細かい点まで表示されます。詳細については、画像の形式をご覧ください。
  • maptype(オプション): 作成するマップのタイプを定義します。指定できる maptype の値には、roadmapsatellitehybridterrain があります。詳細については、後述の Google Static Maps API のマップタイプをご覧ください。
  • language(オプション): マップタイルに表示されるラベルの言語を定義します。このパラメータがサポートされているのは一部の国のタイルのみであることに注意してください。リクエストされた特定の言語がタイルセットでサポートされていない場合は、そのタイルセットのデフォルトの言語が使用されます。
  • region(オプション): 地政学的な配慮に基づいて表示する適切な境界を定義します。2 文字の ccTLD(トップレベル ドメイン)値で示される地域コードを指定できます。

機能パラメータ

  • markers(オプション): 画像の指定された位置に追加する 1 つまたは複数のマーカーを定義します。このパラメータは、1 つのマーカー定義と、パイプ文字(|)で区切ったパラメータを受け取ります。同じスタイルであれば、同じ markers パラメータ内で、複数のマーカーを配置することもできます。異なるスタイルのマーカーは、別の markers パラメータによって追加できます。マップにマーカーを配置する場合、通常は必須である center パラメータや zoom パラメータを指定する必要はありません。詳細については、後述の Google Static Maps API マーカーをご覧ください。
  • path(オプション): 画像の指定された位置に重ねて表示する 2 つ以上の地点が接続された単一のパスを定義します。このパラメータは、パイプ文字(|)で区切った地点を定義する文字列を受け取ります。別の path パラメータによって他のパスを追加することもできます。マップにパスを配置する場合、通常は必須である center パラメータや zoom パラメータを指定する必要はありません。詳細については、後述の Google Static Maps API パスをご覧ください。
  • visible(オプション): マーカーなどのインジケーターは表示しないものの、マップ上に表示する 1 つまたは複数の位置情報を指定します。このパラメータは、あるスポットやマップ上の位置が確実に Google Static Maps API に表示されるようにするために使用します。
  • style(オプション): マップ上の特定のスポット(道路、公園など)の表示を変更するカスタム スタイルを定義します。このパラメータは、スタイルを設定するスポットを特定する feature 引数と element 引数をとり、選択したスポットに対して一連のスタイルを適用します。別の style パラメータによって複数のスタイルを追加することもできます。詳細については、スタイル化されたマップのガイドをご覧ください。

キーおよび署名パラメータ

  • key(必須)を使用すると、Google API Console でアプリケーションの API 使用状況を監視したり、十分な量の 1 日あたりの無料の割り当てを利用したり、必要な場合には、Google からアプリケーションについての問い合わせができるようになります。詳細については、キーと署名を取得するをご覧ください。
  • signature推奨)は、API キーを使用してリクエストを生成しているサイトにその処理が承認されていることを確認するために使用されるデジタル署名です。注: 課金を有効にしている場合は、デジタル署名が必要です。マップロードの 1 日あたりの無料制限を超えた場合、その日の追加のマップロードに対しては課金が発生します。デジタル署名が含まれていない課金対象のマップロードは失敗します。詳細については、キーと署名を取得するをご覧ください。

注: Google Maps APIs Premium Plan ユーザーは、Static Maps リクエストで、API キーとデジタル署名、または有効なクライアント ID とデジタル署名を使用できます。詳細については、Premium Plan ユーザーの認証パラメータをご確認ください。

以前の Google Maps APIs for Work ライセンスのユーザーは、key ではなく、有効な client パラメータと signature パラメータをリクエストに含める必要があります。詳細については、キーと署名の取得に関するページのクライアント ID と署名のセクションをご覧ください。

URL のサイズ制限

Google Static Maps API の URL は 8,192 文字に制限されます。実際には、マーカーやパスの数が非常に多い複雑なマップを生成しない限り、これよりも長い URL が必要になることはないと思われます。ただし、一部の文字は API に送信される前にブラウザやサービスによって URL エンコードが行われ、それによって文字数が増加する可能性もあることに注意してください。詳細については、有効な URL を作成するをご覧ください。

パラメータの使用

Google Static Maps API は、URL パラメータのみで構成されるため、比較的簡単に使用できます。このセクションでは、URL の作成に必要なパラメータの使用方法を説明します。

位置の指定

Google Static Maps API では、マップ上の位置を正確に特定する必要があります。それによって、正しい位置のマップを表示(center パラメータ)したり、マップ上の場所にオプションの場所マーカーを配置(markers パラメータ)することができます。このような位置情報を指定するために、Google Static Maps API は数値(緯度と経度の値)または文字列(住所)を使用します。この数値や文字列によって、ジオコード化した場所が特定できます。

markers パラメータや path パラメータなどには、複数の位置情報を渡すことができます。複数の位置情報がある場合は、パイプ(|)文字で区切ります。

緯度と経度

緯度と経度は、小数点以下 6 桁までの数値をコンマで区切った文字列で定義します。たとえば、「40.714728,-73.998672」は有効なジオコード値です。小数点以下 6 桁を超える数値は無視されます。

経度の値は、本初子午線が通っているイギリスのグリニッジからの距離に基づくものです。グリニッジの緯度は 51.477222 であるため、center の値に 51.477222,0 を指定すると、グリニッジを中心としたマップになります。

イギリス、グリニッジ

緯度と経度の値は地表の有効な地点に対応する必要があります。緯度には -90 から 90 までの値を指定でき、経度には -180 から 180 までの値を指定できます。緯度または経度に無効な値を指定した場合は、不適切なリクエストとして拒否されます。

住所

ある場所を指す際に緯度と経度を使う人はほとんどいないでしょう。通常は、住所を使います。住所を地理的な地点に変換するプロセスはジオコーディングと呼ばれており、Google Static Maps API サービスに有効な住所を渡すことでジオコーディングを行うことができます。

パラメータに緯度と経度を渡すこともできますが、住所を示す文字列を渡すこともできます。その場合、住所のジオコーディングが行われて Google Static Maps API サービスには緯度と経度が渡されます。その値を使って、マーカーの表示や位置の指定が行われます。文字列は、URL エスケープを行う必要があります。たとえば、住所「City Hall, New York, NY」は「City+Hall,New+York,NY」と変換します。

なお、ここで言う住所は、番地などの正確な住所、名前のある道などのポリライン、市区町村、国、国立公園などの多角形状の地域のいずれかを示すものであることに注意してください。ポリライン状または多角形状の結果の場合、Google Static Maps API サーバーはその線や地域の中心を住所の中心として使用します。住所がどのようにジオコーディングされているか疑問に感じる場合は、Geocoding Utility で住所のジオコーディングを試すことができます。

次の例では、Google Static Maps API によって「Berkeley, CA」のマップを生成しています。

https://maps.googleapis.com/maps/api/staticmap?center=Berkeley,CA&zoom=14&size=400x400&key=YOUR_API_KEY

カリフォルニア州バークリー

ズームレベル

Google マップには、現在のビューの解像度を定義する「ズームレベル」という整数値があります。デフォルトの roadmap ビューでは、0(最も低いズームレベルで、1 つのマップに全世界を表示します)から 21 以上(通りや個々の建物まで拡大します)のズームレベルを指定できます。ズームレベルが 17 ほどになると、建物の輪郭(表示可能な場合)がマップ上に表示されます。この値は地域によって異なり、データが進化するにつれて変わる可能性があります。

Google マップでは、ズームレベル 0 を地球全体を表示するレベルに設定しています。ズームレベルが 1 つ増加するごとに、縦横の縮尺の精度が 2 倍になります。この方法の詳細については、Google Maps JavaScript API ドキュメントをご覧ください。

注: 地球上のすべての場所をすべてのズームレベルが表示されるわけではありません。地球上の場所によっては他の場所よりもデータの粒度が細かいため、ズームレベルは場所によって異なります。

利用できるマップタイルがないズームレベルのリクエストを送信すると、Google Static Maps API はその場所で利用可能な最大のズームレベルを表示するマップを返します。

次のリストは、各ズームレベルで表示されるおおよその詳細度を示しています。

  • 1: 世界
  • 5: 大陸
  • 10:市
  • 15:通り
  • 20:建物

次の例は、center の値が同じでズームレベルがそれぞれ 12 と 14 である 2 つのマンハッタンのマップをリクエストしています。

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&key=YOUR_API_KEY

縮小したマンハッタン  拡大したマンハッタン

画像サイズ

size パラメータは、center パラメータとともに使用してマップに表示する範囲を定義します。このパラメータに scale の値(デフォルトは 1)を掛けると、ピクセル単位でのマップの出力サイズになります。

次の表は、それぞれの scale の値に対して size パラメータに指定できる最大値を示しています。

API scale=1 scale=2 scale=4
無償版 640x640 640x640(1280x1280 ピクセルを返します) 使用不可
Google Maps APIs Premium Plan 2048x2048 1024x1024(2048x2048 ピクセルを返します) 512x512(2048x2048 ピクセルを返します)

次の例は、ズームレベル 1 で地球の赤道部分を切り抜いているリクエストです。

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=400x50&key=YOUR_API_KEY

赤道

次の例は、同じ場所を中心としたサイズが 100 x 100 ピクセルの小さなマップをリクエストしています。Google ロゴが小さくなっていることに注意してください。

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=100x100&key=YOUR_API_KEY

小さな赤道のマップ

scale の値

Google Static Maps API の size パラメータは、ピクセル単位でマップサイズを定義します。size=200x200 のマップは、縦 200 ピクセル、横 200 ピクセルで返されます。通常、コンピュータの LCD モニターは、1 インチあたりのピクセル数(ppi)が 100 で表示されます。そのため、200x200 のマップは約 2 インチ(5 センチ)四方となります。

ただし、モバイル端末の画面は高解像度化が進んでおり、ピクセル密度が 300ppi を超えるものもあります。このような端末では、次のどちらかが発生します。

  • 200x200 ピクセルのサイズの画像がほんの 1.8 センチほどに縮小され、ラベルやアイコンの表示が小さすぎて読めなくなる
  • 読みやすいように画像を拡大(ズーム)すると、ぼやけたりモザイク状になる
小さすぎる ぼやけている

モバイル端末向けの開発を行う場合は、API の scale パラメータを使用して解像度が高いマップの画像を返すようにすると、上記の問題を解決できます。scale の値と size を掛けると、ピクセル単位での実際の画像の出力サイズを求めることができます。マップの表示範囲は変わりません(デフォルトの scale の値は 1 です。指定可能な値は 1、2、(Google Maps APIs Premium Plan ユーザーのみ)4 です)。

たとえば、scale の値が 2 の場合、scale が指定されていないリクエストと同じ範囲のマップが返されますが、縦横とも 2 倍のピクセルが含まれるようになります。このマップには、高解像度の小さな画面でも読みやすい道路やラベルが含まれています。また、ブラウザで拡大や縮小をしても読みやすくなっています。

150x150 150x150&scale=2

このような画像を CSS で高さと幅を指定した img タグやdiv タグに入れると、デスクトップのブラウザでもきれいに表示されます。画像は、画質を落とすことなく正しいサイズに縮小されます。

次の表は、3 つの画像のリクエストを示しています。

  • 最初は 100x100 の画像で、scale の値は指定されていません。デスクトップでは正しく表示されますが、モバイル端末では小さすぎて読めなくなっています。
  • 2 番目のものは、マップサイズが 2 倍になっています。デスクトップでは、CSS で指定された 100x100 の img 要素の中に表示されていますが、画像を縮小しているため、道路やラベルが小さくなりすぎています。画像はモバイル端末でも正しいサイズですが、道路やラベルはやはり読めなくなっています。
  • 3 番目のリクエストは、scale=2 を指定した 100x100 のマップです。これによって、詳細情報が 200px で記載された画像が返されます。デスクトップではきれいに縮小されており、元の 100x100 のリクエストと見分けがつきません。モバイル ブラウザでも、API によって返される高解像度の効果が現れています。
端末 100x100 200x200 100x100&scale=2
デスクトップ
img タグに
height="100px"
width="100px" を指定)
高解像度
(シミュレーション)

ヒント: Android や iOS などのモバイル プラットフォーム用のアプリでは、解像度に応じて異なる画像を指定して高解像度画面をサポートするようにします。scale パラメータを使うと、簡単に画面に応じたマップ画像をリクエストできます。scale=1 を設定すると標準的な解像度の画面向け、scale=2 を設定すると高解像度画面向けのマップをリクエストできます。

高解像度のモバイル ディスプレイ向けの開発についての詳しい情報は、次のドキュメントがお勧めです。

画像の形式

画像は、ウェブの一般的なグラフィック形式であるGIFJPEGPNG で返すことができます。format パラメータには、次のうちいずれか 1 つのパラメータを渡します。

  • png8 または png(デフォルト): 8 ビット PNG 形式
  • png32: 32 ビット PNG 形式
  • gif: GIF 形式
  • jpg: JPEG 圧縮形式
  • jpg-baseline: ノンプログレッシブ JPEG 圧縮形式

一般的に、jpgjpg-baseline は画像サイズが最も小さくなりますが、不可逆な圧縮が行われているため、画像が劣化する可能性があります。gifpng8png32 は無損失な変換を行います。

ほとんどの JPEG 画像はプログレッシブです。最初に粗い画像が読み込まれ、データが届くにつれて解像度が上がってゆくため、ウェブページの画像の読み込みが早くなります。現在最も広く使われている JPEG はこの形式です。ただし、JPEG の使用方法(特に印刷用)によっては、ノンプログレッシブ(ベースライン)の画像が必要になります。そのような場合は、ノンプログレッシブの jpg-baseline 形式を使用することができます。

マップタイプ

Google Static Maps API は、次に示すいくつかの形式でマップを作成します。

  • roadmap(デフォルト): 通常の Google マップのウェブサイトに表示される標準的な道路図の画像です。maptype の値が指定されないと、Google Static Maps API はデフォルトで roadmap のタイルを返します。
  • satellite: 航空写真の画像です。
  • terrain: 物理的な起伏、地形、植生を表示する地形図の画像です。
  • hybrid: 航空写真と道路図を合成したハイブリッド画像です。航空写真の上に半透明で主要な道路や地名を表示します。

次のコードの例で、道路図と地形図のタイプの違いを確認できます。

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=roadmap&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=YOUR_API_KEY

マンハッタンの通常のマップ  マンハッタンの地形図

ハイブリッド マップでは、航空写真の画像と主要な道路や地物などが組み合わされます。次の例では、航空写真とハイブリッドのマップを表示しています。

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=satellite&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=hybrid&key=YOUR_API_KEY

マンハッタンの航空写真  マンハッタンの地形図

スタイル化されたマップ

スタイル化されたマップのガイドをご覧ください。

マーカー

markers パラメータでは、場所に対して 1 つまたは複数のマーカーを定義します。1 つの markers 宣言の中で定義されたマーカーには、すべて視覚的に同じスタイルが適用されます。異なるスタイルのマーカーを表示したい場合は、別のスタイル情報を定義した複数の markers パラメータを指定する必要があります。

markers パラメータには、次の形式で一連の値(マーカー記述子)を割り当てます。

たとえば、markers=markerStyles|markerLocation1| markerLocation2|... のように記述します。

markers 宣言の最初には、一連のマーカー スタイル(markerStyles)を宣言します。マーカー スタイルはパイプ文字(|)で区切った 0 個以上のスタイル記述子ですが、これが存在しないこともあります。その後には、1 つまたは複数の位置情報をパイプ文字(|)で区切って記述します。

スタイル情報と位置情報はどちらもパイプ文字区切りであるため、マーカー記述子内ではスタイル情報を最初に指定する必要があります。Google Static Maps API サーバーがマーカー記述子内で位置情報を見つけると、以降のマーカーのパラメータはすべて位置情報であると見なされます。

マーカー スタイル

マーカー スタイル記述子は、パイプ(|)文字で区切られた一連の値です。スタイル記述子では、マーカー記述子によってマーカーを表示する際に使用する視覚的な属性を定義します。スタイル記述子には、次のキー値ペアを含めることができます。

  • size(オプション): マーカーのサイズです。{tiny, mid, small} のいずれかを指定します。size パラメータが指定されない場合、マーカーはデフォルト(通常)のサイズで表示されます。
  • color(オプション): 24 ビットの色(例: color=0xFFFFCC)を指定するか、定義済みの色である {black, brown, green, purple, yellow, blue, gray, orange, red, white} のいずれかを指定します。

    透明度(32 ビットの 16 進カラー値)は、パスではサポートされていますが、マーカーではサポートされていないことに注意してください。

  • label(オプション): {A-Z, 0-9} の中から、1 字の数字または大文字の英字を指定します(大文字という要件は、このバージョンの API で追加されました)。サイズがデフォルトまたは mid のマーカーのみ alphanumeric-character パラメータを表示できる点に注意してください。サイズが tiny および small のマーカーは、alphanumeric-character パラメータを表示できません。

注: マーカーを使用する代わりに、カスタム アイコンを使用することもできます(詳細については、後述のカスタム アイコンをご覧ください)。

マーカーの場所

各マーカー記述子には、マップ上にマーカーを配置する場所を定義する 1 つまたは複数の位置情報を含める必要があります。この位置情報には、緯度と経度の値か住所のどちらかを指定します。複数の位置情報がある場合は、パイプ文字(|)で区切って指定します。

location パラメータは、マップ上のマーカーの位置を定義するものです。center パラメータと zoom パラメータが指定されており、その場所がマップの外にある場合、生成された画像にマーカーは表示されません。ただし、この 2 つのパラメータが指定されていない場合、Google Static Maps API サーバーは指定されたマーカーを含めた画像を自動的に作成します(後述の暗黙的な位置指定をご覧ください)。

マーカー宣言の例を次に示します。この例では、1 つのスタイルと 3 つの場所を定義している点にご注意ください。

https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&size=400x400&
markers=color:blue%7Clabel:S%7C11211%7C11206%7C11222&key=YOUR_API_KEY

ブルックリンの 3 つの郵便番号

スタイルが異なるマーカーを定義する場合は、複数の markers パラメータを指定する必要があります。たとえば、62.107733、-145.5419 の場所に「S」のラベルが付いた青いマーカー、「Delta Junction, AK」に小さな緑色のラベルのないマーカー、「Tok, AK」にサイズが mid で「C」のラベルが付いた黄色いマーカーという複数のマーカーを定義することができます。そのためには、複数の markers パラメータを使って 3 つのマーカーを定義します。この 3 つのマーカーを次の例に示します。

https://maps.googleapis.com/maps/api/staticmap?center=63.259591,-144.667969&zoom=6&size=400x400\
&markers=color:blue%7Clabel:S%7C62.107733,-145.541936&markers=size:tiny%7Ccolor:green%7CDelta+Junction,AK\
&markers=size:mid%7Ccolor:0xFFFF00%7Clabel:C%7CTok,AK"&key=YOUR_API_KEY

異なるマーカーを付けたアラスカの 3 つの町

カスタム アイコン

Google のマーカー アイコンではなく、カスタム アイコンを使用することもできます。カスタム アイコンは、markers パラメータに次の記述子を追加して指定します。

  • icon: マーカーのカスタム アイコンの URL を指定します。アイコンの画像は PNG、JPEG、GIF のいずれかの形式を使用できますが、PNG が推奨されています。

icon パラメータは URL で指定し、URL エンコードを行う必要があります。https://goo.gl などの短縮 URL サービスを使用して作成した URL を使用できます。ほとんどの短縮 URL サービスには、URL が自動的にエンコードされるというメリットもあります。アイコンのサイズは、最大 4096 ピクセル(正方形の 64x64 画像)までに制限されています。また、Google Static Maps API サービスでは、1 回のリクエストにつき最大 5 つまでの一意なカスタム アイコンを使用できます。この一意なアイコンは、Google Static Maps API で繰り返して使用できることに注意してください。

カスタム アイコンのアンカー ポイントは、画像の下部の中心に設定されます。

次の例では、Google の Chart API を使用してカスタム マーカーを作成し、ニューヨーク市にあるいくつかのコーヒーショップを表示しています。

https://maps.googleapis.com/maps/api/staticmap?size=480x480&markers=
icon:https://chart.apis.google.com/chart?chst=d_map_pin_icon%26chld=cafe%257C996600%7C
224+West+20th+Street+NY%7C75+9th+Ave+NY%7C700+E+9th+St+NY&key=YOUR_API_KEY

マンハッタンのコーヒーショップ

注: 上記の例は、複数の段階でエスケープが行われているため、わかりにくいかもしれません。Google Chart API は、URL パラメータ内の文字列の区切り文字としてパイプ文字(|)を使用しています。この文字は URL には利用できないため(上記のをご覧ください)、有効な Chart API 用の URL を作成する際に %7C にエスケープされます。次に、その結果を icon を指定する文字列として埋め込みますが、% 文字(先ほどの %7C に含まれるもの)もデータとして直接 URL に埋め込むことはできないため、%25 にエスケープする必要があります。その結果、URL には 2 段階にエンコードされた %257C が含まれることになります。Chart API の URL には & 文字も含まれています。これを URL に直接含めると、Google Static Maps API は URL パラメータの区切り文字と解釈してしまうので、この文字も同様にエンコードする必要があります。

Google Static Maps API の URL を生成する手順を次に示します。

# Intended chld parameter:
chld=cafe|996600

# Embedded in a fully valid chart URL:
https://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600

# Intended icon parameter, containing a fully valid URL:
markers=icon:https://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600

# Embedded in a valid and unambiguous Google Static Maps API URL:
...&markers=icon:https://chart.apis.google.com/chart?chst=d_map_pin_icon%26chld=cafe%257C996600

Google Static Maps API パス

path パラメータを使うと、1 つまたは複数の場所を 1 本の線で接続したパスをマップ画像に重ねて表示することができます。path パラメータには、次の形式で一連の引数値(パス記述子)を渡します。

たとえば、path=pathStyles|pathLocation1|pathLocation2|... のように記述します。

パスでつなぐそれぞれの地点をパイプ文字(|)で区切っていることに注意してください。スタイル情報と地点情報はどちらもパイプ文字区切りであるため、パス記述子内ではスタイル情報を最初に指定する必要があります。Google Static Maps API サーバーがパス記述子内で位置情報を見つけると、以降のパスのパラメータはすべて位置情報であると見なされます。

パススタイル

パススタイル記述子は、パイプ(|)文字で区切られた一連の値です。スタイル記述子では、パスを表示する際に使用する視覚的な属性を定義します。スタイル記述子には、次のキー値ペアを含めることができます。

  • weight(オプション): パスの太さをピクセル単位で指定します。weight パラメータが指定されない場合、パスはデフォルト(5 ピクセル)の太さで表示されます。
  • color(オプション): 24 ビットの色(例: color=0xFFFFCC)、32 ビットの 16 進値(例: color=0xFFFFCCFF)、または {black, brown, green, purple, yellow, blue, gray, orange, red, white} のいずれかを指定します。

    32 ビットの 16 進値を使用する場合、最後の 2 文字には 8 ビットのアルファ透過値を00(完全に透過)からFF(完全に不透明)の間で指定します。透明度は、パスではサポートされていますが、マーカーではサポートされていないことに注意してください。

  • fillcolor(オプション): パスが多角形の領域であることを示すとともに、その領域を塗りつぶす色を指定します。このパラメータに続けて指定する位置情報は、「閉じた」ループである必要はありません。Google Static Maps API サーバーは自動的に最初と最後の地点を接続します。ただし、塗りつぶす領域の外側にある線は、明示的に同じ開始位置と終了位置を指定しないと閉じられないことに注意してください。
  • geodesic(オプション): リクエストするパスを地球の曲率に沿った測地線として扱うことを示します。false の場合、パスは画面上でまっすぐな線として描画されます。デフォルトは false です。

次に、いくつかのパスの定義の例を示します。

  • 不透明度 50% の青い細線: path=color:0x0000ff80|weight:1
  • 赤い実線: path=color:0xff0000ff|weight:5
  • 太い白線: path=color:0xffffffff|weight:10

パスのスタイルはオプションです。デフォルトの属性を使用する場合は、パスの属性の定義を行う必要はありません。その場合は、パス記述子の最初の引数は最初に宣言する地点(位置情報)になります。

パスの地点

パスを描画するためには、path パラメータに 2 つ以上の地点を渡す必要があります。Google Static Maps API サーバーは指定された順番でそれぞれの地点に沿ってパスを接続します。パスの地点は、|(パイプ)文字で区切ってパス記述子に記述します。

次の例では、ニューヨークのユニオン スクエアとタイムズ スクエアをつなぐ青いパスをデフォルトの 50% の不透明度で定義しています。

ユニオン スクエアからタイムズ スクエアまでのパス

path パラメータは、次のように指定されています。

path=color:0x0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

次の例では、同じパスを不透明度 100% の赤い実線で定義しています。

ユニオン スクエアからタイムズ スクエアまでのパス

path パラメータは、次のように指定されています。

path=color:0xff0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

次の例では、マンハッタンの複数の交差点を位置情報として渡すことによって、多角形状の領域を定義しています。

ユニオン スクエアからタイムズ スクエアまでのパス

path パラメータは、次のように指定されています。

path=color:0x00000000|weight:5|fillcolor:0xFFFF0033|8th+Avenue+%26+34th+St,New+York,NY|\
8th+Avenue+%26+42nd+St,New+York,NY|Park+Ave+%26+42nd+St,New+York,NY,NY|\
Park+Ave+%26+34th+St,New+York,NY,NY

パス自体は透明な線で設定し、多角形領域を不透明度 15% で塗りつぶしている点に注意してください。

エンコードしたポリライン

複数の位置情報を渡す代わりに、パスをエンコードしたポリラインとして宣言することもできます。その場合には、path の位置情報の宣言部分に enc: プレフィックスを追加します。マップ上にエンコードしたポリラインによるパスを配置する場合、通常は必須である center パラメータや zoom パラメータを指定する必要はありません。

次の例は、ブリティッシュ コロンビア州ドーソン クリークからアラスカ州デルタ ジャンクションまでのアラスカ ハイウェイのルートをエンコードしたポリラインで示しています。

https://maps.googleapis.com/maps/api/staticmap?size=400x400&path=weight:3%7Ccolor:orange%7Cenc:polyline_data&key=YOUR_API_KEY

アラスカ ハイウェイ

通常のパスと同様に、エンコードしたポリラインのパスの path パラメータに fillcolor 引数を渡すと、多角形状の領域を定義することができます。

次の例では、ニューヨーク州ブルックリンを多角形状の領域として定義しています。

https://maps.googleapis.com/maps/api/staticmap?size=400x400&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7C
enc:encoded_data&key=YOUR_API_KEY

エンコードしたポリラインによるブルックリン

ビューポート

visible パラメータで表示する場所を指定することによって、画像のビューポートを指定することができます。visible パラメータを指定すると、Google Static Maps API サービスは定義されている場所が隠れないようにマップを作成します(このパラメータを既存のマーカーやパスと組み合わせて表示する範囲を定義することもできます)。この方法でビューポートを定義すると、ズームレベルを正確に指定しなくてもよくなります。

次の例では、MIT(マサチューセッツ工科大学)とマサチューセッツ州ケンブリッジのハーバード スクエアの両方を含み、マサチューセッツ州ボストンを中心としたマップをリクエストしています。

https://maps.googleapis.com/maps/api/staticmap?center=Boston,MA
&visible=77+Massachusetts+Ave,Cambridge,MA%7CHarvard+Square,Cambridge,MA&size=512x512&key=YOUR_API_KEY

ケンブリッジのマップ

マップの暗黙的な位置指定

通常は、centerzoom の URL パラメータを指定して、生成するマップの場所とズームレベルを定義する必要があります。ただし、markerspathvisible のいずれかのパラメータを指定する場合は、暗黙的な位置の指定を行うことができます。その場合、Google Static Maps API はそれぞれの要素の位置を評価し、その結果に基づいて適切な中心とズームレベルを決定します。

2 つ以上の要素が指定されている場合、Google Static Maps API は適切な中心とズームレベルを判断し、含まれる要素に対して十分な余白を確保します。次の例では、カリフォルニア州のサンフランシスコ、オークランド、サンノゼを含むマップを表示しています。

https://maps.googleapis.com/maps/api/staticmap?size=512x512&maptype=roadmap\
&markers=size:mid%7Ccolor:red%7CSan+Francisco,CA%7COakland,CA%7CSan+Jose,CA&key=YOUR_API_KEY

トラブルシューティングとサポート

Google Static Maps API の使用に関する詳しい情報は、サポートページをご覧ください。

何らかの問題が発生した場合、Google Static Maps API からエラーや警告が返されることがあります。特に、マップ上に表示されていないものがある場合は、警告を確認するようにしてください。新しいアプリケーションを起動する前にも、警告を確認することをお勧めします。警告は HTTP ヘッダーに含まれるため、すぐにはわからない可能性がある点に注意してください。詳細については、エラーと警告のガイドをご覧ください。

Google Static Maps API では、以前はユーザーの位置情報の検出にアプリケーションでセンサーを使用するかどうかを示すため sensor パラメータを含める必要がありましたが、このパラメータは必要なくなりました。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。