はじめに
マップ URL を使用すると、クロス プラットフォームで使用できる共通の URL を作成して、Google マップを起動したり、検索を行ったり、ルートやナビゲーションを取得したり、地図ビューやパノラマ画像を表示したりできます。URL の構文は、使用しているプラットフォームに関係なく同じです。
マップ URL を使用するのに Google API キーは必要ありません。
ユニバーサルなクロスプラットフォーム構文
Android アプリ、iOS アプリ、ウェブサイトのデベロッパーは、共通の URL を作成できます。この URL は、マップを開く際に使用されているプラットフォームに関係なく、Google マップを開いてリクエストされたアクションを実行します。
- Android デバイスの場合:
- Android 向け Google マップ アプリがインストールされ、有効になっている場合、URL はマップアプリで Google マップを起動し、リクエストされたアクションを実行します。
- Google マップ アプリがインストールされていないか、無効になっている場合、URL はブラウザで Google マップを起動し、リクエストされたアクションを実行します。
- iOS デバイスの場合:
- iOS 版 Google マップ アプリがインストールされている場合、URL はマップアプリで Google マップを起動し、リクエストされたアクションを実行します。
- Google マップ アプリがインストールされていない場合、URL はブラウザで Google マップを起動し、リクエストされたアクションを実行します。
- 他のデバイスでは、URL を指定するとブラウザで Google マップが起動し、リクエストされたアクションが実行されます。
アプリやウェブサイトから Google マップを起動するには、クロス プラットフォーム URL を使用することをおすすめします。これらの共通 URL を使用することで、使用しているプラットフォームに関係なく、地図に関するより幅広いリクエストを処理できるようになります。モバイル プラットフォームでのみ機能する可能性のある機能（ターンバイターン方式のナビなど）については、Android または iOS 向けのプラットフォーム固有のオプションを使用することをおすすめします。以下のドキュメントをご覧ください。
- Android 向け Google マップ インテント - 特に Android 向け Google マップ アプリを起動する場合
- iOS 用 Google マップの URL スキーム - 具体的には、iOS 用 Google マップアプリを起動するためのもの
Google マップを起動して特定のアクションを実行する
Google マップを起動して、サポートされている機能のいずれかを実行するには、リクエストするアクションに応じて、次のいずれかの形式の URL スキームを使用します。
- 検索 - 特定の場所のピンを表示する Google マップを起動するか、一般的な検索を実行して結果を表示するマップを起動します。
https://www.google.com/maps/search/?api=1¶meters - ルート
- ルートをリクエストし、結果を Google マップで表示します。
https://www.google.com/maps/dir/?api=1¶meters - 地図を表示する
— マーカーやルートを表示せずに Google マップを起動します。
https://www.google.com/maps/@?api=1&map_action=map¶meters - 候補リストを作成する
- 特定の場所のリストで Google マップを起動します。
https://www.google.com/maps/@?api=1&map_action=shortlist¶meters - ストリートビュー パノラマを表示する
— インタラクティブなパノラマ画像を起動します。
https://www.google.com/maps/@?api=1&map_action=pano¶meters
重要: パラメータ api=1 は、この URL が対象とする Maps URL のバージョンを識別します。このパラメータはすべてのリクエストで必須です。有効な値は 1 のみです。URL に api=1 が含まれていない場合、すべてのパラメータは無視され、使用中のプラットフォームに応じてブラウザまたは Google マップ モバイルアプリでデフォルトの Google マップアプリが起動します（例: https://www.google.com/maps）。
有効な URL を作成する
URL を適切にエンコードする必要があります。
たとえば、一部のパラメータでは区切り文字としてパイプ文字（|）が使用されます。これは、最終ページ URL で %7C としてエンコードする必要があります。他のパラメータでは、緯度/経度座標や市区町村、都道府県など、カンマ区切り値を使用します。カンマは %2C としてエンコードする必要があります。スペースは %20 でエンコードするか、プラス記号（+）に置き換えます。
また、URL はリクエストごとに 2,048 文字に制限されています。URL を作成する際は、この上限に注意してください。
地図操作
利用可能な地図操作は、検索、ルート、地図の表示、ショートリストの作成、ストリートビュー パノラマの表示です。リクエスト URL には、必須パラメータとオプション パラメータとともにアクションを指定します。URL の標準規則と同様に、パラメータはアンパサンド（&）文字を使用して区切ります。各アクションについて、パラメータとその有効な値のリストが検索パラメータセクションに列挙されています。
検索
検索アクションでは、表示されている地図の範囲で検索した結果が表示されます。特定の場所を検索すると、検索結果の地図に指定された場所にピンが立てられ、Place Details が表示されます。
検索 URL の作成
https://www.google.com/maps/search/?api=1¶meters
パラメータ
query（必須）: 地図上でハイライト表示する場所を定義します。クエリ パラメータは、すべての検索リクエストで必須です。query_place_id（省略可）: プレイス ID は、場所を一意に識別するテキスト表記の ID です。searchアクションの場合は、queryを指定する必要がありますが、query_place_idを指定することもできます。両方のパラメータを指定した場合、queryは Google マップでプレイス ID が見つからない場合にのみ使用されます。特定の施設に確実にリンクする場合は、プレイス ID を使用するのが最適です。緯度と経度の座標を使用して特定の場所をクエリする場合は、query_place_idを送信することをおすすめします。
検索の例
位置情報検索
場所検索では、場所の名前、住所、カンマ区切りの緯度/経度座標を使用して特定の場所を検索します。検索結果の地図には、その場所にピンが表示されます。これら 3 つの例は、異なる場所の値を使用して同じ場所を検索する方法を示しています。
例 1: 地名「Lumen Field」を検索すると、次の地図が表示されます。
https://www.google.com/maps/search/?api=1&query=lumen+field
例 2: 緯度と経度の座標のみを使用して Lumen Field を検索すると、次の地図が表示されます。地図上にピンが表示されますが、地図上にもサイドパネルにも、場所に関する追加情報は表示されません。
https://www.google.com/maps/search/?api=1&query=47.5951518%2C-122.3316393
例 3: 緯度と経度の座標とプレイス ID を使用して Lumen Field を検索すると、次の地図が表示されます。
例 4: 「Starbucks」という場所の名前を検索すると、次の地図が表示されます。
https://www.google.com/maps/search/?api=1&query=starbucks
例 5: 地名とプレイス ID を使用して特定の Starbucks を検索すると、次の地図が表示されます。
https://www.google.com/maps/search/?api=1&query=starbucks&query_place_id=ChIJsU30zM1qkFQRbnOm1_LBoG0
特定の場所の詳細を表示することが目的の場合は、次のいずれかの推奨形式を使用して検索 URL を作成します。
query=PLACE_NAME,ADDRESSquery=PLACE_NAME&query_place_id=PLACE_ID
プレイス ID をプログラムで取得するには、Places API: テキスト検索（ID のみ）機能を使用します。これは、プレイス ID を取得するための費用のかからない方法です。プレイス ID と Place API（New）リクエストの詳細。
プレイス ID は、ユーザーが地図上のスポットをクリックまたはタップしたときにも取得できます。クリック可能な POI アイコンの詳細（JavaScript、Android、iOS）をご確認ください。
カテゴリ検索
カテゴリ検索では、一般的な検索キーワードを渡すと、Google マップが指定した場所の近くで条件に一致するリスティングを検索します。場所が指定されていない場合、Google マップは現在地の近くのリスティングを検索します。カテゴリ検索の場所を指定する場合は、一般的な検索文字列に場所を含めます（例: pizza+seattle+wa）。
この例では、ワシントン州シアトルのピザ レストランを検索すると、次の地図が表示されます。
https://www.google.com/maps/search/?api=1&query=pizza+seattle+wa
ルート
経路アクションは、地図上の 2 つ以上の指定されたポイント間の経路、距離、移動時間を表示します。
ルートの URL を作成する
https://www.google.com/maps/dir/?api=1¶meters
パラメータ
origin: ルートを表示する開始地点を定義します。デフォルトでは、デバイスの位置情報など、最も関連性の高い開始位置が使用されます（利用可能な場合）。ない場合は、結果の地図に空白のフォームが表示され、ユーザーが出発地を入力できるようになります。値は、場所の名前、住所、またはカンマ区切りの緯度/経度座標です。文字列は URL エンコードする必要があります。たとえば、「City Hall, New York, NY」という住所はCity+Hall%2C+New+York%2C+NYに変換する必要があります。注: このパラメータは省略可能です。ただし、URL に
origin_place_idを指定する場合は必須です。origin_place_idを指定する場合は、URL にoriginも含める必要があります。origin_place_id（省略可）: プレイス ID は、場所を一意に識別するテキスト表記の ID です。施設を明確に指定する場合は、プレイス ID を使用すると、正しい場所にリンクされることが保証されます。このパラメータを使用する URL には、originも含める必要があります。destination: ルートのエンドポイントを定義します。指定しない場合、表示される地図に空白のフォームが表示され、ユーザーが目的地を入力できるようになります。値には、場所の名前、住所、またはカンマ区切りの緯度/経度座標を指定できます。文字列は URL エンコードする必要があります。たとえば、「City Hall, New York, NY」という住所はCity+Hall%2C+New+York%2C+NYに変換する必要があります。注: このパラメータは省略可能です。ただし、URL に
destination_place_idを指定する場合は必須です。destination_place_idを指定する場合は、URL にdestinationも含める必要があります。destination_place_id（省略可）: プレイス ID は、場所を一意に識別するテキスト表記の ID です。施設を明確に指定する場合は、プレイス ID を使用すると、正しい場所にリンクされる可能性が最も高くなります。このパラメータを使用する URL には、destinationも含める必要があります。travelmode（省略可）: 移動手段を定義します。オプションの一覧は次のとおりです。drivingwalking: 歩道や歩行者専用道路を優先します（利用可能な場合）。bicycling: 自転車専用道路がある場合は、その道路を通るルート。「Bicycling」は、人力による移動手段を指します。two-wheeler: 二輪車に適した道路を通るルート（利用可能な場合）。 「二輪車」とは、オートバイなどの原動機付二輪車を指します。詳細については、二輪車の補償をご覧ください。transitdir_action=navigate（省略可）: 出発地が利用可能かどうかによって、指定された目的地までのターンバイターン ナビゲーションまたは経路のプレビューを開始します。ユーザーが出発地を指定し、その出発地がユーザーの現在地から離れている場合、または現在のデバイスの位置情報が利用できない場合、地図にルートのプレビューが表示されます。ユーザーが出発地を指定しない場合（出発地はデフォルトで現在のデバイスの位置になります）、または出発地がユーザーの現在地に近い場合、地図アプリはターンバイターン方式ナビを起動します。なお、Google マップのすべてのプロダクトで、またはすべての目的地間でナビゲーションを利用できるわけではありません。そのような場合、このパラメータは無視されます。waypoints:originとdestinationの間で経由する 1 つ以上の中継地を指定します。複数のウェイポイントを指定するには、パイプ文字（|）を使用して場所を区切ります（例:Berlin,Germany|Paris,France）。指定できるウェイポイントの数は、リンクを開くプラットフォームによって異なります。モバイル ブラウザでは最大 3 つ、それ以外では最大 9 つのウェイポイントがサポートされています。ウェイポイントは、URL に記載されている順序で地図上に表示されます。 各ウェイポイントは、場所の名前、住所、またはカンマ区切りの緯度/経度座標のいずれかです。文字列は URL エンコードする必要があります。たとえば、「Berlin,Germany|Paris,France」のようなウェイポイントはBerlin%2CGermany%7CParis%2CFranceに変換する必要があります。注:
- ウェイポイントは、すべての Google マップ サービスでサポートされているわけではありません。サポートされていない場合、このパラメータは無視されます。
- URL で
waypoint_place_idsを指定しない限り、このパラメータは省略可能です。waypoint_place_idsを指定する場合は、URL にwaypointsも含める必要があります。
waypoint_place_ids（省略可）: プレイス ID は、場所を一意に識別するテキスト表記の ID です。Waypoint_place_idsを使用すると、waypointsのリストに一致するプレイス ID のリストを指定できます。プレイス ID は、ウェイポイントと同じ順序でリストし、パイプ文字「|」（ URL エンコードでは%7C）で区切る必要があります。特定の施設を明確に指定する場合は、プレイス ID を使用すると、正しい場所にリンクされる可能性が最も高くなります。このパラメータを使用する URL には、waypointsも含める必要があります。avoid（省略可）: ルートで回避する機能を設定します。これらのオプションを 1 つ以上設定できます。複数のオプションを設定する場合は、カンマ文字「,」（ URL エンコードでは%2C）で区切ります。ferrieshighwaystolls
travelmode が指定されていない場合、Google マップには、指定されたルートやユーザー設定に最も関連性の高いモードが 1 つ以上表示されます。
経路の例
次の URL を使用すると、地図がルート案内モードで起動し、出発地と目的地を入力できるフォームが表示されます。
https://www.google.com/maps/dir/?api=1
次の例では、ワシントン州シアトルのスペース ニードルからパイク プレイス マーケットまでの自転車ルートを示す地図を起動します。
次の例では、Google Mumbai から Mumbai International Airport までの二輪車での経路を含む地図を起動します。
次の例では、オーストラリアの Google シドニーからクイーン ビクトリア ビルディングまでの徒歩経路を示す地図を起動します。
マップを表示する
地図アクションは、マーカーやルートのない地図を返します。
マップ URL の作成
https://www.google.com/maps/@?api=1&map_action=map¶meters
パラメータ
map_action=map（必須）: 表示する地図ビューのタイプを指定します。Maps とストリートビューは同じエンドポイントを共有します。地図を表示するには、map_actionをmapとして指定する必要があります。center（省略可）: 地図ウィンドウの中心を定義します。緯度と経度の座標をカンマ区切り値として受け取ります（例:-33.8569,151.2152）。zoom（省略可）: 地図の初期ズームレベルを設定します。指定できる値は、0（全世界）から 21（個々の建物）までの整数です。上限は、選択した場所で利用可能な地図データによって異なります。デフォルト値は 15 です。basemap（省略可）: 表示する地図のタイプを定義します。値はroadmap（デフォルト）、satellite、terrainのいずれかです。layer（省略可）: 地図に表示する追加のレイヤ（存在する場合）を定義します。値は、none（デフォルト）、transit、traffic、bicyclingのいずれかにできます。
地図の例
この URL の例では、ユーザーの現在地を中心としたデフォルトの Google マップが起動します。
https://www.google.com/maps/@?api=1&map_action=map
次の例では、オーストラリアのニュー サウス ウェールズ州カトゥーンバ（-33.712206,150.311941）を中心とする地図を表示し、オプションの zoom パラメータと basemap パラメータを設定します。
ストリートビュー パノラマの表示
パノラマ アクションを使用すると、ビューアを起動して、ストリートビューの画像をインタラクティブなパノラマとして表示できます。各ストリートビュー パノラマは、単一地点からの 360 度ビューを提供します。 画像には、360 度の水平ビュー（周囲全体）と 180 度の垂直ビュー（真上から真下）が含まれています。パノラマ アクションは、カメラが中央に配置された、パノラマ画像を球体としてレンダリングするビューアを起動します。カメラを操作して、ズームやカメラの向きを制御できます。
Google ストリートビューは、 対象地域全体について、指定された場所からのパノラマビューを提供します。ユーザーが投稿したフォトスフィアとストリートビューのスペシャル コレクションも利用できます。
ストリートビュー URL の作成
https://www.google.com/maps/@?api=1&map_action=pano¶meters
パラメータ
map_action=pano（必須）: 表示するビューのタイプを指定します。Maps とストリートビューは同じエンドポイントを共有します。パノラマを表示するには、actionをpanoとして指定する必要があります。
次のいずれかの URL パラメータも必要です。
viewpoint: の位置に最も近い場所で撮影されたパノラマが表示されます。viewpointの位置は、カンマ区切りの緯度/経度座標（例: 46.414382,10.013988）で指定します。ストリートビューの画像は定期的に更新され、撮影位置も毎回わずかに異なる可能性があるため、画像が更新されると、位置が別のパノラマにスナップされる可能性があります。pano: 表示する画像の特定のパノラマ ID。panoを指定する場合は、viewpointも指定できます。viewpointは、Google マップでパノラマ ID が見つからない場合にのみ使用されます。panoが指定されているが見つからず、viewpointが指定されていない場合、パノラマ画像は表示されません。代わりに、Google マップがデフォルト モードで開き、ユーザーの現在地を中心とした地図が表示されます。
次の URL パラメータは省略可能です。
heading: カメラのコンパス方位を、北からの時計回り方向への度数で示します。指定できる値は -180 ～ 360 度です。省略すると、クエリの視点（指定されている場合）と画像の実際の場所に基づいて、デフォルトの方向が選択されます。pitch: カメラの上下の角度を指定します。 ピッチは -90 ～ 90 の度数で指定します。正の値はカメラを上向きに傾け、負の値はカメラを下向きに傾けます。デフォルトのピッチ 0 は、画像がキャプチャされたときのカメラの位置に基づいて設定されます。このため、ピッチ 0 は多くの場合、水平方向ですが、必ずそうであるとは限りません。たとえば、山で撮影された画像は、水平ではないデフォルトのピッチで表示されます。fov: 画像の水平方向の画角を決定します。画角は度数で表され、範囲は 10 ～ 100 です。デフォルトは 90 です。 固定サイズのビューポートを扱う場合、画角はズームレベルとみなされ、数値が小さいほどズームレベルが高くなります。
ストリートビューの例
最初の 2 つの例では、エッフェル塔のパノラマが表示されます。例 1 では、場所の viewpoint のみを使用し、省略可能な heading、pitch、fov パラメータを設定します。比較のため、2 つ目の例では、1 つ目の例と同じパラメータ セットに加えて pano ID を使用しています。3 つ目の例は、屋内パノラマ画像を表示します。
例 1: viewpoint のみを使用して場所を指定します。
例 2: pano ID と viewpoint ロケーションを使用します。pano ID は viewpoint よりも優先されます。この例では、パノラマ ID が見つかったため、viewpoint は無視されます。pano ID で表示されるパノラマ画像は、viewpoint のみを使用して見つかった画像よりも若干異なり、新しいことに注意してください。
例 3: パノラマ ID で指定された、英国ロンドンの Sarastro レストランの内部のパノラマを表示します。
https://www.google.com/maps/@?api=1&map_action=pano&pano=4U-oRQCNsC6u7r8gp02sLA
パノラマ ID を確認する
特定のパノラマ画像の ID を確認するには、複数の方法があります。
- JavaScript の場合は、 StreetViewPanorama クラスを使用します。
- Android の場合は、パブリック クラス StreetViewPanoramaLocation を使用します。
- iOS の場合は、 GMSPanorama クラスを使用します。
- Google ストリートビュー画像 API を使用してメタデータ リクエストを行うこともできます。 画像メタデータ リクエストは、パノラマ ID などのストリートビュー パノラマに関するデータを提供します。
候補リストを作成する
候補リストのアクションでは、特定の場所のリストが表示され、ユーザーはそれらの場所を Google マップ プロフィールに保存したり、他のユーザーと共有したり、各場所を個別に探索したりできます。
ショートリスト URL の作成
https://www.google.com/maps/@?api=1&map_action=shortlist¶meters
パラメータ
map_action=shortlist（必須）: 候補リストのアクションを指定します。place_ids（必須）: 候補リストに含める場所を定義します。このパラメータには、1 つ以上のプレイス ID をカンマ区切りの値として指定します。指定できるプレイス ID は最大 20 個です。
候補リストの例
次の例では、3 つの特定の場所を含むショートリストを含む地図を起動します。
その他の例
地点を使用したルートの例
次のルートの例では、Google マップを起動し、フランスのパリからシェルブールまでの運転ルートを表示します。このルートには、次のウェイポイントが含まれます。
| 国、市区町村 | 場所の名前 | プレイス ID |
|---|---|---|
| 1. ベルサイユ（フランス） | ヴェルサイユ宮殿 | ChIJdUyx15R95kcRj85ZX8H8OAU |
| 2. シャルトル（フランス） | シャルトル大聖堂 | ChIJKzGHdEgM5EcR_OBTT3nQoEA |
| 3. ルマン（フランス） | ル マンの聖ジュリアン大聖堂 | ChIJG2LvQNCI4kcRKXNoAsPi1Mc |
| 4. カーン（フランス） | カーン城 | ChIJ06tnGbxCCkgRsfNjEQMwUsc |
サンプル URL では、ウェイポイントがさまざまな方法で定義されているため、結果の地図上でウェイポイントの表示の違いを比較できます。
例 1: 都市、国として定義されたウェイポイント:
例 2: 特定の場所の名前として定義されたウェイポイント:
例 3: 経由地が都市と国として定義され、各経由地の特定の施設に対して waypoint_place_ids も提供されます。
例 4: 経由地を City、Country として定義していますが、経由地は前の例とは異なる順序でリストされています。URL に記載されている順序でウェイポイントが地図に表示されることを示します。
地図の例
指定された basemap（航空写真）と layer（交通機関）を含む地図を表示します。
ストリートビューの例
FIFE 画像キーを pano ID として使用して、ストリートビュー パノラマを表示します。pano ID の前に F: が付いています。
UTM パラメータを含む Google マップの URL の改善
デベロッパーが Maps URL をどのように統合しているかを Google がよりよく理解し、最適なパフォーマンスを確保できるように、URL 構造に UTM トラッキング パラメータを含めることをおすすめします。utm_source パラメータと utm_campaign パラメータを追加することで、Google は使用パターンを分析し、Maps URLs サービスを改善するための貴重なデータを得ることができます。
utm_source パラメータには、アプリケーションの名前を使用してください。utm_campaign パラメータには、ユーザーの意図したアクション（「location_sharing」、「place_details_search」、「directions_request」など）を反映する必要があります。
たとえば、UTM パラメータを含む URL は次のようになります。
https://www.google.com/maps/search/?api=1&query=Sydney+Opera+House&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE&utm_source=YOUR_APP_NAME&utm_campaign=place_details_search