はじめに
マップ 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 マップが起動され、リクエストされたアクションが実行されます。
クロス プラットフォーム URL を使用してアプリやウェブサイトから Google マップを起動することをおすすめします。これらの共通 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 - ストリートビュー パノラマを表示する
- インタラクティブなパノラマ画像を起動します。
https://www.google.com/maps/@?api=1&map_action=pano¶meters
重要: パラメータ api=1 は、この URL が対象とするマップ URL のバージョンを識別します。このパラメータはすべてのリクエストで必須です。有効な値は 1 のみです。URL に api=1 が含まれていない場合、すべてのパラメータは無視され、使用しているプラットフォームに応じて、ブラウザまたは Google マップ モバイルアプリでデフォルトの Google マップ アプリが起動します（https://www.google.com/maps など）。
有効な URL を作成する
URL を適切にエンコードする必要があります。
たとえば、一部のパラメータではパイプ文字（|）が区切り文字として使用されます。この文字は、最終的な URL で %7C としてエンコードする必要があります。他のパラメータでは、緯度/経度座標や市区町村、都道府県など、カンマ区切りの値を使用します。カンマは %2C としてエンコードする必要があります。スペースは %20 でエンコードするか、プラス記号（+）に置き換えます。
また、URL はリクエストごとに 2,048 文字に制限されています。URL を作成する際は、この上限に注意してください。
地図操作
使用できる地図アクションは、検索、ルート、地図の表示、ストリートビューのパノラマの表示です。アクションは、必須パラメータとオプション パラメータとともにリクエスト URL で指定します。URL の標準規則と同様に、パラメータはアンパサンド（&）文字を使用して区切ります。アクションごとに、パラメータのリストとその有効な値が [検索パラメータ] セクションに記載されています。
検索
検索アクションは、表示されている地図領域全体の検索結果を表示します。特定の場所を検索すると、結果の地図に指定された場所にピンが配置され、利用可能な場所の詳細が表示されます。
検索 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: 地名「スターバックス」を検索すると、次の地図が表示されます。
https://www.google.com/maps/search/?api=1&query=starbucks
例 5: 場所の名前とプレイス ID を使用して特定のスターバックスを検索すると、次の地図が表示されます。
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: Text Search（ID のみ）機能を使用します。 これは、プレイス ID を取得するための費用が発生しない方法です。詳しくは、場所 ID と Place API（新規）リクエストをご覧ください。
プレイス ID は、ユーザーが地図上でスポットをクリックまたはタップしたときに取得することもできます。クリック可能なスポットアイコンの詳細（JavaScript、Android、iOS）
カテゴリ検索
カテゴリ検索では、一般的な検索キーワードを渡すと、指定した場所の近くで条件に一致するリスティングが検索されます。場所が指定されていない場合、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: 自転車専用道路（利用可能な場合）を経由するルート。「自転車」は、人間が動力源となる移動手段を指します。two-wheeler: 2 輪車に適した道路を通るルート（利用可能な場合）。「二輪車」とは、オートバイなどの原動機付自転車を指します。詳細については、2 輪車の保証範囲をご覧ください。transitdir_action=navigate（省略可）: 出発地が利用可能かどうかに基づいて、指定された目的地へのターンバイターン方式のナビゲーションまたはルートのプレビューを起動します。ユーザーが出発地を指定し、その場所がユーザーの現在地に近くない、またはデバイスの現在地が利用できない場合は、地図にルート プレビューが表示されます。ユーザーが出発地を指定していない場合（この場合、出発地はデフォルトで現在のデバイスの位置になります）、または出発地がユーザーの現在の位置に近い場合は、地図でルート案内が開始されます。ナビゲーション機能は、すべての Google マップ サービスで利用できるわけではありません。また、すべての目的地間で利用できるわけでもありません。そのような場合は、このパラメータは無視されます。waypoints:originとdestinationの間に経路を設定するための中間地点を 1 つ以上指定します。複数のウェイポイントを指定する場合は、パイプ文字（|）を使用して場所を区切ります（例:Berlin,Germany|Paris,France）。使用できるウェイポイントの数は、リンクが開くプラットフォームによって異なります。モバイル ブラウザでは最大 3 つのウェイポイントがサポートされ、それ以外では最大 9 つのウェイポイントがサポートされます。ウェイポイントは、URL に表示される順序と同じ順序で地図に表示されます。 各ウェイポイントは、地名、住所、またはカンマ区切りの緯度と経度の座標のいずれかです。文字列は URL エンコードする必要があります。そのため、「ベルリン、ドイツ|パリ、フランス」などのウェイポイントは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（省略可）: ルートで避けるべき特徴を設定します。カンマ文字「,」（%2Cとして URL エンコード）で区切って、次のオプションの 1 つ以上を設定できます。ferrieshighwaystolls
travelmode が指定されていない場合、Google マップには、指定されたルートやユーザーの設定に最も関連性の高い 1 つ以上のモードが表示されます。
経路の例
次の URL は、ルート検索モードで地図を起動し、ユーザーが出発地と目的地を入力できるフォームを提供します。
https://www.google.com/maps/dir/?api=1
次の例では、ワシントン州シアトルのスペース ニードルからパイク プレイス マーケットまでの自転車ルートを表示する地図を起動します。
次の例では、Google ムンバイからムンバイ国際空港までの 2 輪車のルートを含む地図を起動します。
次の例では、オーストラリアの Google シドニーからクイーン ビクトリア ビルディングまでの徒歩ルートを表示する地図を起動します。
マップを表示する
地図アクションは、マーカーや経路のない地図を返します。
地図の URL の作成
https://www.google.com/maps/@?api=1&map_action=map¶meters
パラメータ
map_action=map（必須）: 表示する地図ビューのタイプを指定します。マップとストリートビューは同じエンドポイントを共有します。地図を表示するには、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 パラメータを設定します。
ストリートビュー パノラマの表示
pano アクションを使用すると、ビューアを起動してストリートビュー画像をインタラクティブなパノラマとして表示できます。各ストリートビュー パノラマは、単一地点からの 360 度ビューを表示します。画像には、360 度の水平ビュー（周囲全体）と 180 度の垂直ビュー（真上から真下）が含まれています。pano アクションは、カメラが中央に配置された球体としてレンダリングされたパノラマを表示するビューアを起動します。カメラを操作して、カメラのズームと向きを制御できます。
Google ストリートビューは、 対象地域全体で、指定された場所からのパノラマビューを提供します。ユーザー作成のフォトスフィアやストリートビューのスペシャル コレクションも利用できます。
ストリートビューの URL の作成
https://www.google.com/maps/@?api=1&map_action=pano¶meters
パラメータ
map_action=pano（必須）: 表示するビューのタイプを指定します。マップとストリートビューは同じエンドポイントを共有します。パノラマを表示するには、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 つ目の例では 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 Street View Image API を使用してメタデータ リクエストを送信することもできます。画像メタデータ リクエストは、パノラマ ID など、ストリートビュー パノラマに関するデータを提供します。
その他の例
地点を使用した経路の例
次の経路の例では、Google マップを起動して、フランスのパリからフランスの Cherbourg までの経路を表示します。経路には、次のウェイポイントが含まれています。
| 国、市区町村 | 場所の名前 | プレイス ID |
|---|---|---|
| 1. ベルサイユ（フランス） | ヴェルサイユ宮殿 | ChIJdUyx15R95kcRj85ZX8H8OAU |
| 2. シャトレ（フランス） | シャルトル大聖堂 | ChIJKzGHdEgM5EcR_OBTT3nQoEA |
| 3. ルマン（フランス） | ル マンの聖ジュリアンの大聖堂 | ChIJG2LvQNCI4kcRKXNoAsPi1Mc |
| 4. カーン（フランス） | カーン城 | ChIJ06tnGbxCCkgRsfNjEQMwUsc |
サンプル URL では、ウェイポイントが異なる方法で定義されているため、生成された地図でウェイポイントの表示の違いを比較できます。
例 1: 都市、国として定義されたウェイポイント:
例 2: 特定の地名として定義されたウェイポイント:
例 3: 都市、国として定義されたウェイポイント。各ウェイポイントの特定の施設の waypoint_place_ids も指定しています。
例 4: 地点は都市と国として定義されていますが、地点の順序は前の例とは異なります。地図に、URL にリストされている順序でウェイポイントが表示されることを示しています。
地図の例
指定された basemap（衛星）と layer（交通機関）の地図を表示します。
ストリートビューの例
FIFE 画像キーを pano ID として使用してストリートビュー パノラマを表示します。pano ID には F: が付いています。
UTM パラメータを使用した地図の URL の改善
デベロッパーがマップの URL をどのように統合しているかを Google が把握し、パフォーマンスを最適化できるように、URL の作成時に UTM トラッキング パラメータを組み込むことをおすすめします。utm_source パラメータと utm_campaign パラメータを追加すると、Google は使用パターンを分析し、マップ URL プロダクトを改善するための貴重なデータを入手できます。
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