地図オブジェクト

API では、地図は GoogleMap クラスと MapFragment クラスによって表されます。

コードサンプル

GitHub の ApiDemos リポジトリには、GoogleMap オブジェクトと SupportMapFragment の使用方法を示すサンプルが含まれています。

BasicMapDemoActivity: マーカーが配置された基本地図を表示する
basic_demo.xml: レイアウト定義に SupportMapFragment を追加する

Android アプリに地図を追加する

地図を追加する基本的な手順は次のとおりです。

（この手順は初回のみ必要です。）プロジェクト設定ガイドの手順に沿って API とキーを取得して、Android マニフェストに必要な属性を追加します。
地図を処理する Activity に Fragment オブジェクトを追加します。これを行うには、<fragment> 要素を Activity のレイアウトファイルに追加する方法が最も簡単です。
OnMapReadyCallback インターフェースを実装し、onMapReady(GoogleMap) コールバックメソッドを使用して、GoogleMap オブジェクトに対するハンドルを取得します。GoogleMap オブジェクトは、地図自体の内部表現です。地図のビューオプションを設定するには、GoogleMap オブジェクトを変更します。
フラグメントで getMapAsync() を呼び出して、コールバックを登録します。

それぞれの手順の詳細は以下のとおりです。

フラグメントを追加する

Fragment オブジェクトを定義するには、アクティビティのレイアウトファイルに <fragment> 要素を追加します。この要素で、android:name 属性を "com.google.android.gms.maps.MapFragment" に設定すると、MapFragment が自動的にアクティビティに追加されます。

次のレイアウトファイルには <fragment> 要素が含まれています。

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    android:name="com.google.android.gms.maps.MapFragment"
    android:id="@+id/map"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

MapFragment をコード内の Activity に追加することもできます。それには、新しい MapFragment インスタンスを作成してから、FragmentTransaction.add() を呼び出して、Fragment を現在の Activity に追加します。

 mMapFragment = MapFragment.newInstance();
 FragmentTransaction fragmentTransaction =
         getFragmentManager().beginTransaction();
 fragmentTransaction.add(R.id.my_container, mMapFragment);
 fragmentTransaction.commit();

地図コードを追加する

アプリ内で地図を操作するには、OnMapReadyCallback インターフェースを実装し、MapFragment または MapView オブジェクトでコールバックのインスタンスを設定する必要があります。このチュートリアルでは、アプリに地図を追加する最も一般的な方法である、MapFragment を使用します。最初の手順として、コールバックインターフェースを実装します。

public class MainActivity extends FragmentActivity
    implements OnMapReadyCallback {
...
}

Activity の onCreate() メソッドで、レイアウトファイルをコンテンツビューとして設定します。たとえば、レイアウトファイルの名前が main.xml の場合は、次のコードを使用します。

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
    ...
}

フラグメントに対するハンドルを取得するには、FragmentManager.findFragmentById() を呼び出して、<fragment> 要素のリソース ID を渡します。なお、レイアウトファイルを作成すると、リソース ID R.id.map が自動的に Android プロジェクトに追加されます。

次に、getMapAsync() を使用して、フラグメントにコールバックを設定します。

MapFragment mapFragment = (MapFragment) getFragmentManager()
    .findFragmentById(R.id.map);
mapFragment.getMapAsync(this);

GoogleMap オブジェクトに対するハンドルを取得するには、onMapReady(GoogleMap) コールバックメソッドを使用します。地図の使用が可能になると、コールバックがトリガーされます。これは、null ではない GoogleMap のインスタンスを提供します。地図のビューオプションの設定や、マーカーの追加などを行うには、GoogleMap オブジェクトを使用します。

@Override
public void onMapReady(GoogleMap map) {
    map.addMarker(new MarkerOptions()
        .position(new LatLng(0, 0))
        .title("Marker"));
}

地図オブジェクト

Maps SDK for Android を使用すると、Android アプリに Google マップを表示できます。これらの地図は、モバイル Google マップ（GMM）アプリに表示される地図と同じデザインで表示されます。API では、同じ機能の多くが公開されています。GMM アプリと、Maps SDK for Android で表示される地図には、次のように 2 つの大きな違いがあります。

API で表示される地図タイルには、パーソナライズされたコンテンツ（アプリに合わせて作成したスマートアイコンなど）は含まれません。
地図に表示されるアイコンには、クリックできないものもあります。たとえば、乗り継ぎ駅のアイコンはクリックできませんが、地図に追加したマーカーはクリックできます。また、API には、さまざまなマーカー操作に対応したリスナーコールバックインターフェースが用意されています。

API では、マッピング機能に加え、Android UI モデルと同様の幅広い操作もサポートされています。たとえば、ユーザー操作に応答するリスナーを定義して、地図に対する操作を設定することができます。

地図オブジェクトを使用する際に重要となるクラスは、GoogleMap クラスです。GoogleMap では、アプリ内の地図オブジェクトがモデル化されます。UI 内では、地図は MapFragment オブジェクトまたは MapView オブジェクトで表されます。

GoogleMap によって、以下の操作が自動的に処理されます。

Google マップサービスに接続する。
地図タイルをダウンロードする。
タイルをデバイスの画面に表示する。
移動やズームといった各種コントロールを表示する。
パン操作やズーム操作に対し、マップの移動やズームインまたはズームアウトで応答する。

これらの自動操作に加えて、API のオブジェクトとメソッドを使用して地図の動作を制御できます。たとえば、GoogleMap には、地図上でのキーストロークやタップ操作に応答するコールバックメソッドが含まれています。GoogleMap で指定したオブジェクトを使用して、地図にマーカーアイコンを設定してオーバーレイを追加することもできます。

MapFragment

Android Fragment クラスのサブクラスである MapFragment を使用すると、Android フラグメントに地図を配置できます。MapFragment オブジェクトは、地図のコンテナとして機能し、GoogleMap オブジェクトへのアクセス権を付与します。

View とは異なり、Fragment はアクティビティでのユーザーインターフェースの動作や部分を表すものです。1 つのアクティビティで複数のフラグメントを組み合わせて、複数のペインがある UI を構築したり、複数のアクティビティでフラグメントを再利用したりできます。詳しくは、フラグメントに関する Android ドキュメントをご覧ください。

MapView

Android View クラスのサブクラスである MapView を使用すると、Android View に地図を配置できます。View は画面の長方形の領域を表し、Android アプリおよびウィジェットの基本的な構成要素となるものです。MapFragment と同様に、MapView は地図のコンテナとして機能し、GoogleMap オブジェクトを通じて中核となる地図機能を表示します。

API を完全なインタラクティブモードで使用している場合は、MapView クラスで、アクティビティライフサイクルメソッド（onCreate()、onStart()、onResume()、onPause()、onStop()、onDestroy()、onSaveInstanceState()、onLowMemory()）を MapView クラスの対応するメソッドに転送する必要があります。GitHub の ApiDemos リポジトリには、アクティビティライフサイクルメソッドの転送方法を示すサンプルが含まれています。ライトモードで API を使用している場合は、ライフサイクルイベントを転送しなくてもかまいません。詳しくは、ライトモードに関するドキュメントをご覧ください。

地図タイプ

Maps SDK for Android 内では、さまざまなタイプの地図を使用できます。地図の全体的な表示方法は、その地図のタイプによって決まります。たとえば、地図帳には通常、境界線を示すことを主眼とした政治的な地図が掲載されているほか、道路地図には、都市や地域のすべての道路が表示されています。

Maps SDK for Android では、次の 4 種類の地図と、地図が一切表示されないオプションが用意されています。

標準: 通常の道路地図。道路、一部の人工物、河川などの重要な自然物を表示します。道路および対象物のラベルも表示されます。
ハイブリッド: 航空写真データに道路地図を加えたもの。道路および対象物のラベルも表示されます。
航空写真: 航空写真データ。道路および対象物のラベルは表示されません。
地形: 地形データ。この地図では、色、等高線とラベル、遠近感を表すための陰影が使用されます。一部の道路とラベルも表示されます。
なし: タイルは使用されません。地図は、タイルを読み込まない空のグリッドとしてレンダリングされます。

地図タイプを変更する

地図のタイプを設定するには、GoogleMap オブジェクトの setMapType() メソッドを呼び出して、GoogleMap で定義されているタイプ定数のいずれかを渡します。たとえば、航空写真の地図を表示する方法は次のとおりです。

GoogleMap map;
...
// Sets the map type to be "hybrid"
map.setMapType(GoogleMap.MAP_TYPE_HYBRID);

以下の画像は、同じ場所を標準、ハイブリッド、地形の各タイプで表示した地図を比較したものです。

インドアマップ

ズームレベルの高い地図には、空港、ショッピングモール、大規模小売店、乗り換え駅といった屋内空間の構内図が表示されます。これらの構内図はインドアマップと呼ばれ、「標準」および「航空写真」地図タイプ（GoogleMap.MAP_TYPE_NORMAL と GoogleMap.MAP_TYPE_SATELLITE）で表示されます。インドアマップは、地図が拡大されると自動的に有効になり、縮小されると表示されなくなります。

サポート終了のお知らせ: 今後のリリースでは、インドアマップは normal 地図タイプでのみご利用いただけるようになります。以降のリリースでは、satellite、terrain、hybrid の地図でインドアマップはサポートされなくなります。インドアマップのサポートが終了しても、引き続き isIndoorEnabled() は現在と同様に setIndoorEnabled() で設定された値を返します。デフォルトでは、setIndoorEnabled は true となっています。これらの地図タイプでインドアマップをご利用いただけなくなる時期については、リリースノートでお知らせします。

API でインドアマップを使用する

API でのインドアマップの機能の概要は次のとおりです。

インドアマップを無効にするには、GoogleMap.setIndoorEnabled(false) を呼び出します。デフォルトでは、インドアマップは有効になっています。インドアマップは、一度に 1 つの地図でのみ表示されます。デフォルトでは、アプリに最初に追加された地図が表示されます。異なるマップにインドアマップを表示したい場合は、最初の地図でインドアマップを無効にしてから、2 番目のマップで setIndoorEnabled(true) を呼び出します。
デフォルトのレベルピッカー（階数ピッカー）を無効にするには、GoogleMap.getUiSettings().setIndoorLevelPickerEnabled(false) を呼び出します。詳しくは、地図の操作に関する説明をご覧ください。
GoogleMap のインターフェースである OnIndoorStateChangeListener を使用すると、新しい建物がフォーカスの対象となったときや、建物で新しいレベルがアクティブになったときにリスナーを呼び出すよう設定できます。詳しくは、地図の操作に関する説明をご覧ください。
GoogleMap.getFocusedBuilding() では、現在フォーカスの対象となっている建物を取得します。次に、現在アクティブなレベルを特定するには、IndoorBuilding.getActiveLevelIndex() を呼び出します。IndoorBuilding オブジェクトと IndoorLevel オブジェクトで取得可能なすべての情報については、リファレンスドキュメントをご覧ください。

基本地図のスタイル設定はインドアマップには影響しません。

構内図を追加する

インドアマップ（構内図）は、一部の地域でのみご利用いただけます。アプリで表示したい建物の構内図データを使用できない場合は、以下の方法を使用します。

Google マップに直接構内図を追加します。この方法では、Google マップのすべてのユーザーが構内図を使用できるようになります。
構内図を地面オーバーレイまたはタイルオーバーレイとして地図に表示します。この方法では、アプリのユーザーにのみ構内図が表示されるようになります。

交通状況レイヤ

地図上に交通量情報を重ねて表示する機能を、ユーザーに提供することができます。これにより、ユーザーが地域の交通状況を視覚的に把握できるようになります。交通状況レイヤのオンとオフを切り替えるには setTrafficEnabled() メソッドを呼び出し、交通状況レイヤが現在オンになっているかどうかを確認するには isTrafficEnabled() メソッドを呼び出します。地図上に表示される交通状況レイヤの例を次に示します。

Google マップに表示される交通状況レイヤ

初期状態を設定する

Maps API では、アプリのニーズに合わせて地図の初期状態を設定できます。指定できる項目は次のとおりです。

カメラの位置（場所、ズーム、方向、傾斜など）。カメラの位置指定について詳しくは、カメラとビューをご覧ください。
地図タイプ。
ズームボタンやコンパスを画面に表示するかどうか。
ユーザーがカメラを操るために使用できる操作。
ライトモードを有効にするかどうか。ライトモードマップは、完全な API で提供される機能の一部がサポートされている、地図のビットマップ画像です。

地図の初期状態を設定するには、XML を使用するか（アクティビティのレイアウトファイルに地図を追加している場合）、プログラムを使用します（プログラムで地図を追加している場合）。

XML 属性を使用する

このセクションでは、XML レイアウトファイルを使用してアプリに追加した地図の初期状態を設定する方法について説明します。

Maps API では、MapFragment または MapView の一連のカスタム XML 属性が定義されており、これを使用して、レイアウトファイルから地図の初期状態を直接設定できるようになっています。現在定義されている属性は次のとおりです。

mapType。これを使用して、表示する地図のタイプを指定できます。有効な値として、none、normal、hybrid、satellite、terrain などがあります。
cameraTargetLat、cameraTargetLng、cameraZoom、cameraBearing、cameraTilt。これらを使用して、カメラの初期位置を指定できます。カメラの位置とそのプロパティについて詳しくは、こちらをご覧ください。
uiZoomControls、uiCompass。これらを使用して、地図にズームコントロールとコンパスを表示するかどうかを指定できます。詳しくは、UiSettings をご覧ください。
uiZoomGestures、uiScrollGestures、uiRotateGestures、uiTiltGestures。これらを使用して、地図に対するインタラクションでどの操作を有効または無効にするかを指定できます。詳しくは、UiSettings をご覧ください。
zOrderOnTop。地図ビューのサーフェスをウィンドウ上に重ねて配置するかどうかを制御します。詳しくは、SurfaceView.setZOrderOnTop(boolean) をご覧ください。なお、この設定は、地図に表示可能な他のすべてのビュー（ズームコントロールや現在地ボタンなど）に適用されます。
useViewLifecycle。MapFragment でのみ有効です。この属性では、地図のライフサイクルを、フラグメントのビューとフラグメント自体のどちらに紐付けるかを指定します。詳しくは、こちらをご覧ください。
liteMode。true の値を指定すると、マップがライトモードに設定されます。ライトモードマップは、完全な API で提供される機能の一部がサポートされている、地図のビットマップ画像です。この属性のデフォルト値は false です。

XML レイアウトファイル内でこれらのカスタム属性を使用するには、まず次の名前空間宣言を追加する必要があります。名前空間は任意のものを選択でき、map である必要はありません。

xmlns:map="http://schemas.android.com/apk/res-auto"

次に、標準の Android 属性の場合と同様に、map: プレフィックスを付けた属性をレイアウトコンポーネントに追加できます。

カスタムオプションを指定して MapFragment を設定する方法を、次の XML コードスニペットに示します。同じ属性を MapView にも適用できます。

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:map="http://schemas.android.com/apk/res-auto"
  android:name="com.google.android.gms.maps.SupportMapFragment"
  android:id="@+id/map"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  map:cameraBearing="112.5"
  map:cameraTargetLat="-33.796923"
  map:cameraTargetLng="150.922433"
  map:cameraTilt="30"
  map:cameraZoom="13"
  map:mapType="normal"
  map:uiCompass="false"
  map:uiRotateGestures="true"
  map:uiScrollGestures="false"
  map:uiTiltGestures="true"
  map:uiZoomControls="false"
  map:uiZoomGestures="true"/>

プログラムで行う場合

このセクションでは、プログラムでアプリに追加した地図の初期状態を設定する方法について説明します。

MapFragment（または MapView）をプログラムで追加した場合、地図の初期状態を設定するには、オプションを指定して GoogleMapOptions オブジェクトを渡します。XML で使用可能なオプションとまったく同じものを使用できます。GoogleMapOptions オブジェクトは、次のように作成します。

GoogleMapOptions options = new GoogleMapOptions();

続けて、次のようにオブジェクトを設定します。

options.mapType(GoogleMap.MAP_TYPE_SATELLITE)
    .compassEnabled(false)
    .rotateGesturesEnabled(false)
    .tiltGesturesEnabled(false);

地図を作成する際にこれらのオプションを適用するには、次のいずれかを行います。

MapFragment を使用している場合は、MapFragment.newInstance(GoogleMapOptions options) 静的ファクトリーメソッドを使用してフラグメントを作成し、カスタム設定のオプションを渡します。
MapView 使用している場合は、MapView(Context, GoogleMapOptions) コンストラクタを使用して、カスタム設定のオプションを渡します。

地図のパディング

この動画では、地図のパディングの例を紹介しています。

Google の地図は、コンテナ要素（通常は MapView または MapFragment）で定義された領域全体に表示されるようになっています。地図の表示形式と動作のいくつかは、次のように、コンテナのサイズによって定義されます。

カメラの位置は、パディングされた領域の中心が対象となります。
地図のコントロールは、地図の端からの相対的な位置に配置されます。
著作権表示や Google ロゴなどの法的情報は、地図の下端に沿って表示されます。

地図の周囲にパディングを追加するには、GoogleMap.setPadding() メソッドを使用します。地図は引き続きコンテナ全体に表示されますが、テキストとコントロールの位置、地図の操作、カメラの移動は、より小さい地図に対して行われているかのようになります。このため、次のような変化が生じます。

API 呼び出しやボタンのタップ（コンパスボタン、現在地ボタン、ズームボタンなど）によるカメラの移動は、パディングが追加された領域に対して相対的に行われます。
getCameraPosition() は、パディングされた領域の中心を返します。
Projection.getVisibleRegion() は、パディングされた領域を返します。
UI コントロールは、コンテナの端から、指定したピクセル分のスペースを空けて表示されます。

地図の一部に重ねて表示される UI を設計する際は、パディングが役立ちます。たとえば、以下の画像では、地図の上部と右側にパディングが追加されています。地図のコントロールと法的テキストは、パディングされた領域（緑色で表示）の端に沿って表示されますが、地図は引き続きコンテナ全体（青色で表示）に表示されます。この例では、メニューを地図の右側にフローティングして、地図のコントロールが隠れないにようすることができます。

地図のパディング

地図をローカライズする

MapView または MapFragment をアプリに追加すると、ユーザーのデバイスの設定や位置情報に基づいて、地図上のテキスト要素が適切な言語で表示されます。アプリの使用言語を、サポートされている言語の一部に制限するには、resConfigs 項目を Gradle ファイルに追加します。これは、使用していない言語を除外する場合に役立つほか、アプリのバイナリサイズを抑えることもできます。次に例を示します。

defaultConfig {
    resConfigs "en", "fr", "es", "zh", "de", "ja", "ru", "ko", "pt", "in"
}

詳しくは、Android アプリのローカライズをご覧ください。