Overview

究極のカーナビゲーション体験をお届けします！

パイオニアのクラウドナビゲーションSDKは、長年にわたる経験と専門知識に基づき、最高品質のルート探索を実現しています。 道を知り尽くしたパートナーのような案内があなたを的確に目的地へと導きます。

さらに、カスタマイズ性が高い地図描画機能により、自由な表現が可能です。

クラウドナビゲーションSDKを活用して、あなたのカーナビゲーションアプリを革新的なものへと進化させましょう。

パイオニア株式会社 © Pioneer Corporation. All Rights Reserved.

クラウドナビゲーションSDKの特徴

助手席のパートナーのような道案内

• 地図を見なくても音声だけで目的地にたどり着けるように「いつ」「どこで」「どうする」を分かりやすく、的確なタイミングで伝えます。

視認性の高い地図・UI部品

• 運転中に確認しやすい地図の色使い、道路描画で安全運転に貢献します。

ドライバー目線の安全で快適なルート探索

• パイオニアの長年の経験に裏付けされた最適なルートを提供します。

高精度な自車位置補正/マッチング

• GPSの情報だけで位置を決めるのではなく、走行状況や地図の形状も判断材料に加えて現在位置を推定します。
• GPSの測位しないトンネル内であっても、測位状況や道路状況などから現在推定を推定し位置の更新とガイダンスを行います。

多彩な地点検索

• 国内中の地点検索はもちろん、案内中ルート周辺に限定した検索も可能です。

渋滞知らずの快適ドライブ

• リアルタイムに渋滞情報を解析し、渋滞を回避するルートを提案・案内します。

オンライン

• 地図データや地点検索データベースはサーバーの更新に伴い自動的にバージョンアップされます。
• SDKの各機能はネットワーク通信が必須のため、オフライン環境ではご利用になれません。

このガイドの使用方法

このガイドは各章が独立しており、任意の順序で読むことができます。

• サンプルアプリを動かして挙動を確かめたい場合は、「サンプルアプリを試す」の手順を参照してください。
• SDKをアプリに組み込む方法を確認したい場合は、「アプリにSDKを組み込む」の手順を参照してください。
• 機能ごとの解説は、「UseCases」を参照してください。
• 詳細なAPI仕様は、「API Reference」を参照してください。
• 専門用語や固有名詞の解説は、「Glossary」を参照してください。

Get Started

この章ではSDKを利用したアプリを構築するための基礎知識について説明します。

サンプルアプリを試す

Android Studioでプロジェクトを開き、任意のデバイスでアプリを実行してください。

新しいアプリにSDKを組み込んで地図を表示する

本ガイドの開発環境は Android Studio Giraffe および Gradle7.1 を対象としています。
また、ソースコードは全てJavaで記述しています。

Gradle依存関係構築

*.aarをアプリケーションのapp/libsディレクトリに配置します。

次に、アプリのbuild.gradleに以下の記述を追加して*.aarが依存関係に取り込まれるようにし、 必要なパッケージの依存関係を構築します。

implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
implementation 'com.mapbox.maps:android:10.14.0'
implementation 'com.mapbox.extension:maps-androidauto:0.5.0'
implementation 'com.google.android.gms:play-services-location:21.0.1'
implementation "androidx.car.app:app-projected:1.2.0"

次に、プロジェクトのbuild.gradleに以下の記述を追加して、MapBoxパッケージのCredentialを設定します。

allprojects {
    repositories {
        google()
        jcenter()

+       maven {
+           url 'https://api.mapbox.com/downloads/v2/releases/maven'
+           authentication {
+               basic(BasicAuthentication)
+           }
+           credentials {
+               username = 'mapbox'
+               password = project.properties['MAPBOX_DOWNLOADS_TOKEN'] ?: ""
+           }
+       }
    }
}

MapBox public access tokenの設定

MapBoxの'Configure your public token'の手順に従い、トークンを設定してください。

例えば、app/src/main/res/values/developer-config.xmlを追加して、以下のように設定します。

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools">
	<string name="mapbox_access_token" translatable="false" tools:ignore="UnusedResources">YOUR_PUBLIC_MAPBOX_ACCESS_TOKEN</string>
</resources>

secret access token 及び public access token について、 具体的な値(文字列)については営業窓口までお問い合わせください。

AndroidManifestによる権限設定

AndroidAutoを使用する場合、AndroidManifest.xmlに以下の記述を追加して権限を設定します。

    <uses-permission android:name="androidx.car.app.NAVIGATION_TEMPLATES" />

    <application
        <!-- snip -->
        >

        <!-- You must add xml/automotive_app_desc -->
        <meta-data
            android:name="com.google.android.gms.car.application"
            android:resource="@xml/automotive_app_desc" />

        <!-- Create a theme for your app -->
        <meta-data
            android:name="androidx.car.app.theme"
            android:resource= "@style/CarAppTheme" />

        <!-- You choose your minCarApiLevel -->
        <meta-data
            android:name="androidx.car.app.minCarApiLevel"
            android:value="3" />

        <!-- Link to your implementation of CarAppService -->
        <service
            android:name=".car.YourCarAppService"
            android:exported="true"
            tools:ignore="ExportedService">

            <intent-filter>
                <action android:name="androidx.car.app.CarAppService" />
                <category android:name="androidx.car.app.category.NAVIGATION" />
            </intent-filter>
        </service>
    </application>

SDKの初期化

SDKは使用開始前に初期化処理が必要です。 詳細な手順は「Initialize」 を参照してください。
ここでは地図を表示するための最小限の手順を説明します。

まずNavi.initialize()によってSDK全体の初期化を行います。 NaviInitInfoコンストラクタのcontextはApplication Contextを指定してください。

private void initializeNavi(Context context) {
    NaviInitInfo initInfo = new NaviInitInfo(context);
	initInfo.setCloudEnvironment(Common.CloudEnvironment.PRODUCTION);
	initInfo.setTrafficProviderKey(PROVIDER_KEY); // 具体的なキー(文字列)については営業窓口までお問い合わせください。さい。
	initInfo.setTrafficProviderUserID(USER_ID); // 具体的なID(文字列)については営業窓口までお問い合わせください。
	initInfo.setApiKey(API_KEY); // 具体的なキー(文字列)については営業窓口までお問い合わせください。

    Navi.getInstance().initialize(initInfo, new NaviInitListener() {
        @Override
        public void onInitCompleted(ErrorCode errorCode, NaviInitResult naviInitResult) {
            if (errorCode == ErrorCode.NONE) {
                Navi.getInstance().setMobileAppLifecycle(getLifecycle());
            }
        }
    });
}

続いて、地図の初期化を行います。
例えば、端末の全画面に地図を表示したい場合、次のようなFrameLayoutを用意してください。

<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent">

    <FrameLayout
        android:id="@+id/container"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
    />
</RelativeLayout>

地図の描画領域はSupportFragmentで、これを既存のFragmentと置き換えることでSDKが自動的に地図更新できるようになります。 ここでは上述のFrameLayoutをgetSupportFragmentManager を利用して置き換えてみます。

private Map map = null;
private void initializeMap() {
    getSupportFragmentManager().beginTransaction()
            .replace(R.id.container, SupportMapFragment.newInstance(), "supportMapFragment")
            .commitNow();

    SupportMapFragment supportMapFragment = (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.container);
    supportMapFragment.initialize(new MapSetting(), new OnMapEventListener() {
        @Override
        public void onInitializationCompleted(ErrorCode errorCode) {
            if (errorCode == ErrorCode.NONE) {
                map = supportMapFragment.getMap();
                Navi.getInstance().attach(map);
            }
        }

        @Override
        public void onMapModeChanged(Map.MapMode mode) { }
    });
}

このinitializeMap()関数をNaviInitListener.onInitializationCompleted()完了に合わせて呼び出すことで、地図を描画できます。

    Navi.getInstance().initialize(initInfo, new NaviInitListener() {
        @Override
        public void onInitCompleted(ErrorCode errorCode, NaviInitResult naviInitResult) {
            if (errorCode == ErrorCode.NONE) {
                Navi.getInstance().setMobileAppLifecycle(getLifecycle());
+               initializeMap();
            }
        }
    });

このように地図が表示されれば成功です。

なお、現在位置と違う地図を出している状態ですが、この時点では正常です。

自車位置を特定する

アプリの権限のうち、位置情報を許可してください。

SDK初期化完了後にNavi.startPositioning()を呼び出せば、それ以降自車位置を更新し続けます。

    Navi.getInstance().initialize(initInfo, new NaviInitListener() {
        @Override
        public void onInitCompleted(ErrorCode errorCode, NaviInitResult naviInitResult) {
            if (errorCode == ErrorCode.NONE) {
                Navi.getInstance().setMobileAppLifecycle(getLifecycle());
+               Navi.getInstance().startPositioning(new PositioningSetting());
                initializeMap();
            }
        }
    });

起動後に地図を自車位置中心に移動する

自車位置を中心に地図を描画し続けるには、Map.setMapMode()による描画指定、および自車位置へのカメラ位置移動が必要です。

private void setMapCenterToOwnCarPosition(Map map) {
    CameraOptions cameraOptions = new CameraOptions();
    cameraOptions.setCenter(Navi.getInstance().getRunInfo().getOwnCarInfo().getGeoCoordinate());
    map.moveToPoint(cameraOptions, null);
    map.setMapMode(Map.MapMode.HEADING_UP);
}

setMapCenterToOwnCarPosition()をOnMapEventListener.onInitializationCompleted()通知時に呼び出してください。

        @Override
        public void onInitializationCompleted(Error error) {
            if (error == Error.NONE) {
                map = supportMapFragment.getMap();
                Navi.getInstance().attach(map);
+               setMapCenterToOwnCarPosition(map);
            }
       }

これで起動完了とともに自車位置を中心に地図が描画されるようになります。

地図の制御方法の詳細は「Camera Control」を参照してください。

ルートを探索して案内を開始する

ルート探索の詳細は「Route」を参照してください。
ここでは地図を長押しした地点へのルートを探索し、案内を開始する最小限の手順を説明します。

まず、地図の長押しを検知するために、Map.addOnMapLongClickListener()でリスナを登録します。

        @Override
        public void onInitializationCompleted(Error error) {
            if (error == Error.NONE) {
                map = supportMapFragment.getMap();
                Navi.getInstance().attach(map);
                setMapCenterToOwnCarPosition(map);
+               map.addOnMapLongClickListener(new OnMapLongClickListener() {
+                   @Override
+                   public boolean onMapLongClick(GeoCoordinate point) {
+                       return false;
+                   }
+               });
            }
        }

次に、その地点へのルートを探索する処理(startNavigation())を追加し、OnMapLongClickListener.onMapLongClick()でそれを呼び出します。

private void startNavigation(GeoCoordinate goal) {
    RoutePlan routePlan = new RoutePlan();
    routePlan.setEndPoint(goal);
    routePlan.setRouteOptions(new RouteOptions());

    Navi.getInstance().calculateRoute(routePlan, new CalcRouteListener() {
        @Override
        public void onCompleted(ErrorCode errorCode, CalcRouteResult calcRouteResult) {
            if (errorCode == CalcRouteListener.ErrorCode.NONE) {
                Navi.getInstance().startGuidance(null);
            }
        }
    });
}

                        @Override
                        public boolean onMapLongClick(GeoCoordinate point) {
+                           startNavigation(point);
                            return false;
                        }

最後に、誘導音声の出力を有効化するため、NaviInitListener.onInitCompleted()にNavi.startVoiceEngine()を追加します。

            @Override
            public void onInitCompleted(ErrorCode errorCode, NaviInitResult naviInitResult) {
                if (errorCode == ErrorCode.NONE) {
                    Navi navi = Navi.getInstance();
                    navi.setMobileAppLifecycle(getLifecycle());
                    navi.startPositioning(new PositioningSetting());
+                   navi.startVoiceEngine(new VoiceEngineInitListener() {
+                       @Override
+                       public void onInitCompleted(ErrorCode errorCode) {
+                       }
+                   });

                    initializeMap();
                }
            }

これで地図を長押しした地点へのルートを探索できるようになりました。

擬似走行して誘導音声を確認する

SDKには机上で動作確認するための手段としてデモ走行機能を提供しています。

次のようなstartDemoRun()関数を追加し、CalcRouteListener.onCompleted()でそれを呼び出せばルート探索完了と同時にルート上の擬似走行を開始します。

    private void startDemoRun() {
        DemoRunSetting demoRunSetting = new DemoRunSetting();
        demoRunSetting.setDemoType(Common.DemoType.AUTO);
        demoRunSetting.setDemoUpdateCycle(Common.DemoUpdateCycle.DEMO_UPDATE_CYCLE_1HZ);
        demoRunSetting.setAutoRepeat(true);
        Navi.getInstance().startDemoRun(demoRunSetting);
    }

            @Override
            public void onCompleted(ErrorCode errorCode, CalcRouteResult calcRouteResult) {
                if (errorCode == CalcRouteListener.ErrorCode.NONE) {
                    Navi.getInstance().startGuidance(null);
+                   startDemoRun();
                    setMapCenterToOwnCarPosition(map);
                }
            }

デモ走行機能の詳細は「Demo Run」を参照してください。

package com.pioneer.android.myapplication;
import android.content.Context;
import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
import com.pioneer.android.mpa.CalcRouteListener;
import com.pioneer.android.mpa.CalcRouteResult;
import com.pioneer.android.mpa.CameraOptions;
import com.pioneer.android.mpa.Common;
import com.pioneer.android.mpa.DemoRunSetting;
import com.pioneer.android.mpa.GeoCoordinate;
import com.pioneer.android.mpa.Map;
import com.pioneer.android.mpa.MapSetting;
import com.pioneer.android.mpa.Navi;
import com.pioneer.android.mpa.NaviInitInfo;
import com.pioneer.android.mpa.NaviInitListener;
import com.pioneer.android.mpa.NaviInitResult;
import com.pioneer.android.mpa.OnMapEventListener;
import com.pioneer.android.mpa.OnMapLongClickListener;
import com.pioneer.android.mpa.PositioningSetting;
import com.pioneer.android.mpa.RouteOptions;
import com.pioneer.android.mpa.RoutePlan;
import com.pioneer.android.mpa.SupportMapFragment;
import com.pioneer.android.mpa.VoiceEngineInitListener;
import com.pioneer.sample.myapplication.R;
import com.pioneer.sample.myapplication.databinding.MainActivityBinding;
public class MainActivity extends AppCompatActivity {
private Map map = null;
private MainActivityBinding binding;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    binding = MainActivityBinding.inflate(getLayoutInflater());
    setContentView(binding.getRoot());

    naviInitialize(this);
}

private void naviInitialize(Context context) {
    NaviInitInfo initInfo = new NaviInitInfo(context);
    initInfo.setCloudEnvironment(Common.CloudEnvironment.PRODUCTION);
    initInfo.setTrafficProviderKey(PROVIDER_KEY);
    initInfo.setTrafficProviderUserID(USER_ID);
    initInfo.setApiKey(API_KEY);

    Navi.getInstance().initialize(initInfo, new NaviInitListener() {
        @Override
        public void onInitCompleted(ErrorCode errorCode, NaviInitResult naviInitResult) {
            if (errorCode == ErrorCode.NONE) {
                Navi navi = Navi.getInstance();
                navi.setMobileAppLifecycle(getLifecycle());
                navi.startPositioning(new PositioningSetting());
                navi.startVoiceEngine(new VoiceEngineInitListener() {
                    @Override
                    public void onInitCompleted(ErrorCode errorCode) {
                    }
                });

                initializeMap();
            }
        }
    });
}

private void initializeMap() {
    getSupportFragmentManager().beginTransaction()
            .replace(R.id.container, SupportMapFragment.newInstance(), "supportMapFragment")
            .commitNow();

    SupportMapFragment supportMapFragment = (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.container);
    supportMapFragment.initialize(new MapSetting(), new OnMapEventListener() {
        @Override
        public void onInitializationCompleted(Error error) {
            if (error == Error.NONE) {
                map = supportMapFragment.getMap();
                Navi.getInstance().attach(map);
                setMapCenterToOwnCarPosition(map);

                map.addOnMapLongClickListener(new OnMapLongClickListener() {
                    @Override
                    public boolean onMapLongClick(GeoCoordinate point) {
                        startNavigation(point);
                        return false;
                    }
                });

            }
        }

        @Override
        public void onMapModeChanged(Map.MapMode mode) { }
    });
}

private void setMapCenterToOwnCarPosition(Map map) {
    CameraOptions cameraOptions = new CameraOptions();
    cameraOptions.setCenter(Navi.getInstance().getRunInfo().getOwnCarInfo().getGeoCoordinate());
    map.moveToPoint(cameraOptions, null);
    map.setMapMode(Map.MapMode.HEADING_UP);
}

private void startNavigation(GeoCoordinate goal) {
    RoutePlan routePlan = new RoutePlan();
    routePlan.setEndPoint(goal);
    routePlan.setRouteOptions(new RouteOptions());

    Navi.getInstance().calculateRoute(routePlan, new CalcRouteListener() {
        @Override
        public void onCompleted(ErrorCode errorCode, CalcRouteResult calcRouteResult) {
            if (errorCode == CalcRouteListener.ErrorCode.NONE) {
                Navi.getInstance().startGuidance(null);
                startDemoRun();
                setMapCenterToOwnCarPosition(map);
            }
        }
    });
}

private void startDemoRun() {
    DemoRunSetting demoRunSetting = new DemoRunSetting();
    demoRunSetting.setDemoType(Common.DemoType.AUTO);
    demoRunSetting.setDemoUpdateCycle(Common.DemoUpdateCycle.DEMO_UPDATE_CYCLE_1HZ);
    demoRunSetting.setAutoRepeat(true);
    Navi.getInstance().startDemoRun(demoRunSetting);
}

}

SDKの責務について

SDKは以下の機能について責任を持ちます。

• 自車位置更新処理。
• 地図描画、地図のジェスチャー検知、地図への線描画、地図へのアイコン描画処理。
• 地点検索処理とその結果。
• ルート探索処理とその結果。
• システム標準TTSを用いた音声によるルート誘導。
• 渋滞情報の取得処理とその結果。

SDKが提供するGUI部品は次の２点のみです。

• 地図(SupportMapFragment)
• 交差点イラスト図と方面案内図(BitMap)

これ以外のGUI部品は、アプリが自由に構築できます。

用語集

案内地点 (Guide point)

案内地点とは、ルート通りに進行するために案内が必要な道路上の地点のことです。

詳細はルートと案内地点、通過交差点の関係をご覧ください。

通過交差点 (Pass point)

通過交差点とは、交差点・分岐・踏切などの何らかの案内可能な特徴を持った道路上の地点のことです。

レーンバイレーン案内 (Lane by lane guide)

レーンバイレーン案内とは、車線移動の単位で案内する誘導方式のことです。

並走道路

並走道路とは、異なる路線の道路が極めて近い距離で同一方向に敷設されている道路のことです。

例えば次のような道路です：

• 高速高架道路と、その下の一般道
• 高速道路と、そのすぐ脇にある一般道

ルートアドバイザー (Route advisor)

ルートアドバイザーとは、ルート案内中により良いルートを提供する機能のことです。

VICS

VICS（ビックス）とは、渋滞や交通規制などの道路交通情報を、 FM多重放送やビーコンを使ってリアルタイムにカーナビに届けるシステムのことです。

SDKはオンデマンドVICSによりVICS情報を取得します。

VICS情報

VICS情報とは、VICSから得られる以下のデータのことです。

• 事象・規制情報
• 渋滞旅行時間リンク情報 (どの道路がどのくらい通過に時間がかかるのか)
• SA・PA情報
• 駐車場情報

オンデマンドVICS

オンデマンドVICSとは、オンデマンドVICS専用サーバーに接続し、VICS情報を取得する機能のことです。
取得できる情報はビーコン情報と同じ種類の情報です。

プローブ渋滞情報 (Probe traffic information)

プローブ渋滞情報とはパイオニアが独自に収集した渋滞情報のことです

テレメトリ (Telemetory)

テレメトリとは、車両がどこをどのように移動しているかという匿名化されたデータを収集し、地図を作成・更新するプロセスのことです。

ジオコーディング (Geocoding)

ジオコーディングとは、住所や地名を緯度・経度の値に変換する処理のことです。

逆ジオコーディング (Reverse Geocoding)

逆ジオコーディングとは、緯度・経度の値を住所やPOIなどの地図情報に変換する処理のことです。

POI (Point of Interest)

POIとは、Point of Interestの略称のことです。
直訳すると興味のある地点ですが、カーナビにおいては店舗や施設を意味します。

ルートプロフィール (Route profile)

ルートプロフィールとは、出発地から目的地までの間に通る道路名や区間距離、有料道を使用する場合の料金などを確認するための機能のことです。

ヘディングアップ (Heading up)

ヘディングアップとは、地図画面上で常に進行方向が上になるように地図を表示することです。

ノースアップ (North up)

ノースアップとは、地図画面上で常に北が上になるように地図を表示することです。

デモ走行 (Demo running)

デモ走行とは、設定したルートを実際に道路を走行する事なく、自車をルート上を出発地から目的地まで擬似的に走行させる機能のことです。

ログ走行 (Log running)

ログ走行とは、保存したログ走行ファイルから走行を再現する機能のことです。

マップマッチング (Map matching)

マップマッチングとは、現在走行中の道路を特定するプロセスのことです。

予測進路 (Predicted route)

予測進路とは、案内中ルートがないときに自車がどの道路を進むのか予測した進路のことです。

推定速度 (Estimated velocity)

推定速度とは、トンネル内のマッチングずれを軽減するために推定した自車の進路・速度のことです。

UseCases

この章ではSDKの各機能の詳細をそれぞれ説明します。

• Setup

  • Initialize -- 初期化処理について
  • User Setting -- ユーザーごとの設定値について

• Map

  • Camera Control -- 地図描画制御方法について
  • Icon Control -- アイコン描画について
  • Gesture Control -- ユーザーの地図操作について
  • Customize Map Design -- 地図のカスタマイズについて
  • Breadcrumbs -- 自車走行軌跡について
  • Cruising Area -- 航続可能エリア表示について

• Search

  • Free Word Search -- フリーワード検索について
  • Genre Search -- ジャンル検索について
  • Address Search -- 住所検索について
  • Reverse Geocoding -- 緯度経度の地図情報変換について
  • Route Vicinity Search -- ルート周辺検索について
  • Charging Station Search -- 充電施設検索について
  • Search History -- 検索履歴について

• Route

  • New Route -- 新規ルート探索について
  • Charging Route -- EV専用ルート探索について
  • Erase Route -- ルート消去について
  • Edit Route -- ルート編集について
  • Compare Route -- ルート比較について
  • New Route Recommendation -- 新ルート提案について
  • Access Interchange Select -- 高速道路入口出口IC指定について

• Navigation

  • Route Guidance -- ルート誘導音声について
  • Illust -- 誘導画面について
  • Highway Mode -- ハイウェイモードについて

• Location -- 自車位置について

• Navigation support

  • Traffic Guide -- 渋滞情報について
    • Traffic Guidance -- 渋滞情報音声案内について
    • Draw Jam Line -- 渋滞情報の地図描画について
    • Display Incident Spot -- 渋滞、規制情報のアイコン表示について
    • Display Parking Staus -- 駐車場混雑状況のアイコン表示について
  • Caution Guide -- 注意案内情報について

Setup

• 初期化処理

  • アプリ起動時SDKを使用するために行う初期化処理です。

• ユーザーセッティング

  • ナビの設定やルート探索条件のようなユーザーごとの設定を行う機能です。

詳細は各機能のガイドを参照して下さい。

Initialize

SDK使用時はナビ機能(Navi),検索機能(SearchJP),地図表示機能(SupportMapFragment),AndroidAuto用地図機能(CarMap)の初期化が必要です。

各機能のInitilizeタイミングや制約について紹介します。

ナビ機能(Navi)

Initializeタイミング

Navi.initialize()を呼ぶタイミング

• アプリ起動時
• NaviInitInfoのユーザー切り替え時

initialize(NaviInitInfo, NaviInitListener)による初期化完了(onInitCompleted受信)後にNaviクラスが使用可能になります。

初期化時設定項目　

初期化時に設定が必要な項目は以下の通りです。

NaviInitInfo initInfo = new NaviInitInfo(this);
initInfo.setCloudEnvironment(Common.CloudEnvironment.PRODUCTION);
initInfo.setApiKey(API_KEY); // 具体的なキー(文字列)については営業窓口までお問い合わせください。
initInfo.setTrafficProviderKey(PROVIDER_KEY); // 具体的なキー(文字列)については営業窓口までお問い合わせください。
initInfo.setTrafficProviderUserID(USER_ID); // 具体的なID(文字列)については営業窓口までお問い合わせください。

Navi.getInstance().initialize(initInfo, new NaviInitListener() {
    @Override
    public void onInitCompleted(ErrorCode errorCode, NaviInitResult naviInitResult) {
        if (errorCode == ErrorCode.NONE) {

            // 現在のデバイスの位置情報に基づく現在位置の更新を開始(Positioning機能をONに)する
            Navi.getInstance().startPositioning(new PositioningSetting())

            // ライフサイクル設定
            Navi.getInstance().setMobileAppLifecycle(getLifecycle());

            // 音声案内エンジン初期化
            Navi.getInstance().startVoiceEngine(new VoiceEngineInitListener() {
                @Override
                public void onInitCompleted(ErrorCode errorCode) {}
            });

            // 誘導情報(GuidePointList, PathPointList）更新イベントリスナー設定を行います。
            Navi.getInstance().setGuidePointDataChangedListener(new GuidePointDataChangedListener() {
                @Override
                public void onChanged(Navi.GuidePointCreateStatus status) {
                }   
            });

            // 走行情報更新イベントリスナーを追加
            Navi.getInstance().setRunInfoListener(new RunInfoListener() {
                @Override
                public void onUpdate() {}
            });
            // 音声案内イベントリスナーを追加
            Navi.getInstance().setGuideEventListener(new GuideEventListener() {
                @Override
                public void onGuide(Common.GuideEventKind guideEvent, String guidancePhrase, Common.GuideLanguageKind guidanceLanguage) {}
            });
        } else {
            // Naviの初期化失敗　
            // エラー内容によりリトライやネットワークの接続状況確認メッセージ表示,サポートセンターに連絡など
        }
    }
});

検索機能(SearchJP)のInitializeタイミング

SearchJP.initialize()を呼ぶタイミング

• アプリ起動時

initialize(SearchInitInfo)後にSearchJPクラスが使用可能になります。

SearchSettingInfoの各propertyは全て設定必須です。

SearchJP.SearchInitInfo searchInitInfo = new SearchJP.SearchInitInfo();
searchInitInfo.setCloudEnvironment(Common.CloudEnvironment.PRODUCTION);
searchInitInfo.setApiKey(API_KEY); // 具体的なキー(文字列)については営業窓口までお問い合わせください。
searchInitInfo.setTrafficProviderKey(PROVIDER_KEY); // 具体的なキー(文字列)については営業窓口までお問い合わせください。
searchInitInfo.setTrafficProviderUserID(USER_ID); // 具体的なID(文字列)については営業窓口までお問い合わせください。

SearchJP.getInstance().initialize(searchInitInfo);

地図表示機能(SupportMapFragment)

Initializeタイミング

SupportMapFragment.initialize()を呼ぶタイミング

• Navi.initialize()でNaviの初期化が完了したタイミング、またはAuthenticationStatusChangedListener.onChanged(AuthenticationType: AUTH_APIKEY, status: true)が通知されたタイミング。

initialize(MapSetting, OnMapEventListener)での初期化完了（onInitializationCompleted受信）後にgetMap()してMapクラスが使用可能になります。

初期化時設定項目　

初期化時に設定が必要な項目は以下の通りです。

MapSetting mapSetting = new MapSetting();
mapSetting.setMapStyle(Map.MapStyle.DEFAULT);

// MapFragment初期化
SupportMapFragment supportMapFragment = (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.mapFragment);
supportMapFragment.initialize(mapSetting, new OnMapEventListener() {
    @Override
    public void onInitializationCompleted(ErrorCode errorCode) {

        if (errorCode == ErrorCode.NONE) {
            // getMap()してMapが使用可能
            Map map = supportMapFragment.getMap();

            // Naviのアタッチ
            Navi.getInstance().attach(map);

            // 長押しイベントリスナー追加
            map.addOnMapLongClickListener(new OnMapLongClickListener() {
                @Override
                public boolean onMapLongClick(GeoCoordinate point) {}
            });

            // 短押しイベントリスナー追加
            map.addOnMapClickListener(new OnMapClickListener() {
                @Override
                public boolean onMapClick(GeoCoordinate point) {}
            });

            // 地図スケール変更イベントリスナー追加
            map.setOnMapScaleChangeListener(new OnMapScaleChangeListener() {
                @Override
                public void onScaleChanged() {}
            });
        }
    }
});

AndroidAuto用地図表示機能(CarMap)

Initializeタイミング

carMap.initialize(MapSetting, OnMapEventListener)を呼ぶタイミング

• AndroidAuto起動時
• Navi.initialize()でNaviの初期化が完了したタイミング、またはAuthenticationStatusChangedListener.onChanged(AuthenticationType: AUTH_APIKEY, status: true)が通知されたタイミング。

initialize(MapSetting, OnMapEventListener)での初期化完了（onInitializationCompleted受信）後にgetMap()してMapクラスが使用可能になります。

初期化時設定項目　

初期化時に設定が必要な項目は以下の通りです。

// CarAppServiceの生成
public class NavigationService extends CarAppService {

   @NonNull
   @Override
   public HostValidator createHostValidator() {
      return HostValidator.ALLOW_ALL_HOSTS_VALIDATOR;
   }

   @NonNull
   @Override
   public Session onCreateSession() {
      return new NavigationSession();
   }
}

// Sessionの生成
public class NavigationSession extends Session {

   @NonNull
   @Override
   public Screen onCreateScreen(@NonNull Intent intent) {
      return new NavigationScreen(getCarContext());
   }
}

// Screenの生成
public class NavigationScreen extends Screen {

    protected NavigationScreen(@NonNull CarContext carContext) {
        // CarMap初期化
        CarMap carMap = new CarMap(carContext);

        MapSetting mapSetting = new MapSetting();
        mapSetting.setMapStyle(Map.MapStyle.DEFAULT);

        carMap.initialize(mapSetting, new OnMapEventListener() {
            @Override
            public void onInitializationCompleted(ErrorCode errorCode) {
                if (errorCode == ErrorCode.NONE) {
                    // getMap()してMapが使用可能
                    Map map = carMap.getMap();
                    
                    Navi.getInstance().attach(map);
                    // AndroidAuto用のライフサイクル設定
                    Navi.getInstance().setAndroidAutoLifecycle(getLifecycle());
                }
            }

            @Override
            public void onRestoreCompleted(Error error) {
                }

            @Override
            public void onMapModeChanged(Map.MapMode mapMode) {
            }
        });

        carMap.setCarMapObserver(new CarMapObserver() {
           @Override
           public void onAttached(@NonNull SurfaceContainer surfaceContainer) {}

           @Override
           public void onDetached(@NonNull SurfaceContainer surfaceContainer) {}

           @Override
           public void onVisibleAreaChanged(@NonNull Rect visibleArea, @NonNull EdgeInsets edgeInsets) {}

           @Override
           public void onStableAreaChanged(@NonNull Rect stableArea, @NonNull EdgeInsets edgeInsets) {}
       });

        carMap.setGestureHandler(new CarMapGestureHandler(){
            @Override
            public void onScroll() {}

            @Override
            public void onFling() {}

            @Override
            public void onScale() {}
        });
    }
}

User Setting

ナビの設定やルート探索条件のようなユーザーごとの設定値を切り替えるための方法を紹介します。

基本設定内容

SetupInfoでルート探索/案内時の設定をすることが可能です。

基本設定のサンプルコードは以下の通りです。

    SetupInfo setupInfo = new SetupInfo();
    setupInfo.setDistanceUnit(Common.DistanceUnit.METER);
    setupInfo.setGuideLanguageKind(Common.GuideLanguageKind.JAPANESE);
    setupInfo.setNaviMode(Common.NaviMode.NORMAL);
    setupInfo.setRatesClass(Common.RatesClass.STANDARD_SIZED_CAR);
    setupInfo.setEtcConnection(Common.ETCConnection.ETC);
    setupInfo.setCareJamToETA(Common.CareJamToETA.CONSIDER);
    setupInfo.setCareRegulation(Common.CareRegulation.CONSIDER);
    setupInfo.setCareTimeRegulation(Common.CareTimeRegulation.CONSIDER);
    
    Navi.getInstance().setSetupInfo(setupInfo, new UserSettingResultListener() {
        @Override
        public void onCompleted(ErrorCode errorCode) {
            if (errorCode == ErrorCode.NONE) {
                // 設定成功
            }
            else {
               // 設定失敗
            }
        }
    });

Map

地図は視点の変更、デザインを変更、地図上の独自のアイコンを追加、等を行うことにより表示を変更することが可能です。また、地図や地図上の描画物に対してタップやジェスチャーによる操作を行うことができます。この章ではそれらの変更や操作について紹介します。

• 地図表示の変更

  • 地図モードや、カメラを使った地図表示の変更方法の紹介です。

• アイコンの管理

  • 地図上にアイコンを表示し管理する方法の紹介です。

• ジェスチャーの管理

  • 地図や地図上の描画物に対して行うタップやジェスチャーを管理する方法の紹介です。

• 地図デザインの変更

  • 地図上の各種デザインを変更する方法の紹介です。

• 走行軌跡

  • 地図上に表示する走行軌跡についての紹介です。

• 航続可能領域

  • 航続可能な領域を地図上に表示する方法の紹介です。

詳細は各機能のガイドを参照して下さい。

Camera Control

この章では地図の表示変更の方法を紹介します。

マップモード

マップモードは自車位置情報と地図の連動方法に関するモードで以下の3種類があります。

Map.setMapModeにより上記のマップモードを変更することができます。

地図の表示変更

一般的な3DCGと同様にカメラの位置やその要素を変更することで地図の表示を変更することができます。変更可能な要素は以下の通りです。

中心座標

設定することで地図の表示の中心座標を変更することができます。

回転角

設定することで地図を回転させることができます。

ズームレベル

設定することで地図の縮尺を変更することができます。

Map.setZoomLevel()ではズームレベル指定してズームすることができます。

Map.zoomIn/Out()では呼び出し毎にズームレベル0.5単位で拡大、縮小することができます。ズームの単位を変更することも可能です。

Map.zoomTo()ではズームレベルではなく表示領域を指定します。

傾き

設定することで地図の傾きを変更することができます。

パディング

設定することで地図の上下左右のパディング領域を変更することができます。

setOrientation(), setCenter()等の地図の表示を変更する関数はパディング領域を除いた領域に適用されます。 例えば地図画面の上部に別のUI部品を表示した際にその分、上部にパディングを設定することでユーザーから見た地図の中心を適切に保つことが可能です。

アニメーション時間

設定することで地図のアニメーション時間を変更することができます。

CameraOptionsによる表示変更

CameraOptionsオブジェクトに各種設定を行い、Map.moveToPoint(), Map.flyToPoint()の、アニメーション動作が異なるいずれかに渡すことで複数のカメラ要素を同時に設定し、地図の表示を変更することができます。

CameraOptions cameraOptions = new CameraOptions();
GeoCoordinate position = new GeoCoordinate(35.689595, 139.692221);

cameraOptions.setCenter(position);
cameraOptions.setLevel(13.5);

map.moveToPoint(cameraOptions, null);

地図の表示変更通知

地図の表示変更をリスナーにより検知することができます。変更内容と対応するリスナーは以下の通りです。

Icon Control

この章ではアイコンを地図上に表示し、制御するための方法を紹介します。

アイコンの表示方法

Map.addUserIcon()を呼び出すことで、アプリは任意のアイコンを地図上に表示することができます。

例えばユーザーが地図の特定の場所を長押した際にその場所にアイコンを表示したい場合は以下のようになります。

1. addOnMapLongClickListenerでOnMapLongClickListenerを登録します。
2. OnMapLongClickListenerで長押しした場所の緯度経度を取得しMapIconオブジェクトを生成します。
3. 生成したMapIconオブジェクトをMap.addUserIcon()に渡します。

map.addOnMapLongClickListener(new OnMapLongClickListener() {
    @Override
    public boolean onMapLongClick(GeoCoordinate point) {
        MapIcon icon = new MapIcon();
        icon.setImageResource(R.drawable.icon); // アプリで用意するアイコン用画像のリソース
        icon.setID("icon_id");
        icon.setPosition(point);
        map.addUserIcon(icon);

        return false;
    }
});

アイコンの制御方法

Map.addUserIcon()含め、アイコンに関する主な制御関数は以下の通りです。

アイコンクリックイベント

アイコンに対するクリックは以下のOnIconClickListenerで検出することができます。

// アイコンクリック通知リスナー追加
map.addOnIconClickListener(new OnIconClickListener() {
    @Override
    public void onIconClick(IconKind kind, MapIcon icon) {
        // クリック時の処理を書く
    }
}

プリセットアイコン

地図上のアイコンにはユーザーが表示するアイコン以外にも予めSDKで用意（プリセット）されているアイコンがあり、Map.updatePresetIcon()によりそれらのアイコンの画像を変更することができます。

立ち寄り地のアイコンを変更する際のサンプルコードは以下の通りです。

MapIcon wayPointIcon = new MapIcon();
wayPointIcon.setImageResource(R.drawable.myWayPointIcon); // 変更する画像のリソース
map.updatePresetIcon(Map.IconKind.ROUTE_STOPOVER1, wayPointIcon);

変更可能なプリセットアイコンの一覧はMap.IconKindに定義されています。

Tap & Gesture Control

この章では地図に対するユーザーの操作を検出する方法を紹介します。

タップ操作

地図のタップや、地図上の特定のオブジェクトのタップを検知することができます。検知可能な操作と対応するリスナーは以下の通りです。

地図の操作検知

地図の操作検知のサンプルコードは以下の通りです。

map.addOnMapClickListener(new OnMapClickListener() {
    @Override
    public boolean onMapClick(GeoCoordinate point) {
        // pointにクリックした場所の緯度経度が格納されています
        return false;
    }
});

地物の操作検知

地物は地図上のコンビニアイコンや地名などのオブジェクトです。

地物の操作検知例は以下の通りです。地物の情報はMapFeatureとして格納され、複数のキーと値のペアとして取り出すことができます。

map.addOnMapFeatureClickListener(new OnMapFeatureClickListener() {
    @Override
    public void onClick(@NonNull GeoCoordinate point, @NonNull List<MapFeature> features) {
        String name = features.get(0).getValue("name"); // "name"キーの値を取得
    }
});

キーはMapFeature.getKeys()で一覧を取得することができます。

ジェスチャー

SDKでは地図に対するいくつかの複雑な動作（ジェスチャー）をサポートしています。サポートされている地図に対するユーザーのジェスチャーの種類は以下の通りです。

SCROLL_GESTURE

1本指でドラッグし地図をスクロールします。

ROTATE_GESTURE

2本指を回転し地図を回転します。

TILT_GESTURE

2本指を前後にスライドし地図の傾きを変えます。

QUICK_ZOOM_GESTURE

1本指でダブルタップしたままドラッグすることで地図を拡大、縮小します。

DOUBLE_TAP_GESTURE

1本指のダブルタップで地図を拡大し、2本指のダブルタッチで地図を縮小します。

ZOOM_GESTURE

2本指でピンチ操作し地図を拡大、縮小します。

Map.setMapGesture()で各ジェスチャの設定の有効・無効を変更することが可能です。（デフォルト全て有効）

Map.setAllGesturesEnabled()で全てのジェスチャの有効・無効を一括で変更することもできます。

ジェスチャーの検出

リスナーを設定することで地図に対するユーザーのジェスチャーを検出することができます。ジェスチャーとそのリスナーの対応は以下の通りです。

各リスナーではジャスチャーの開始、ジェスチャー中、終了がそれぞれ通知されます。例えばOnMapMoveListenerでぞれぞれの通知を受け取るためのサンプルコードは以下の通りです。

map.addOnMapMoveListener(new OnMapMoveListener() {
    @Override
    public void onMoveBegin() {
        // 移動の開始
    }

    @Override
    public void onMove() {
        // 移動中
    }

    @Override
    public void onMoveEnd() {
        // 移動の終了
    }
});

Customize Map Design

この章では地図のデザインをカスタマイズする方法について紹介します。

カスタマイズ可能なデザイン

地図のデザインはカスタマイズが可能です。カスタマイズ可能なデザインは以下の通りです。

• 住宅地図モード
• 地図のスタイル
• 自車マークのデザイン
• ルート線のデザイン

スタイル変更

Map.changeStyle()を実行することで地図デザインを変更することができます。

以下の3つのスタイルから選択できます。

スタイル名	表示	特徴
DEFAULT		細街路の色を抑えるなど、検索結果や重畳する情報が見やすい地図スタイル
NAVIGATION		走行中に必要な道路の情報を強調した、ナビゲーション案内中に適した地図スタイル
CROSSING		交差点案内用に、交差点の道路形状を見やすくチューニングした地図スタイル

地図スタイルを誘導地図に切り替えるコードは以下の通りになります。

map.changeStyle(Map.MapStyle.NAVIGATION);

地図レイヤーに関して

地図スタイルは以下のようなレイヤー構成になっており、ルート線や渋滞線のレイヤーは『道路ネットワーク』の上に挿入されます。

ルート線の描画位置を変更したい等の地図カスタマイズに関してはご問い合わせください。

地図レイヤーの操作

Map.setLayerVisible()により特定の地図レイヤーの表示/非表示を切り替えることができます。

サンプルコードは以下の通りです。

// 高速道路のIC名を非表示
Map.setLayerVisible("highway-exit-labels",false)

// 地図の信号機アイコンを非表示
Map.setLayerVisible("traffic-label",false)

// ブランドロゴを非表示
Map.setLayerVisible("brand_logo",false)

その他のレイヤー名に関してはお問合せください

住宅地図モード

地図上に建物名称や居住者名、番地などが詳しく表示されますが、これらのラベルは地図の回転に追従せず常に北を上にした情報になります。
住宅地図モード中はどのスタイルでも指定したズームレベルよりも詳細な範囲で自動で住宅地図が表示され、住宅地図モードを終了するか後述するスタイル変更を行うまで継続します。

住宅地図モードを開始するコードは以下の通りです。

Map.beginHousingMapDisplay(15, new Map.ShowHousingMapCompleteListener() {
    @Override
    public void onComplete(ErrorCode errorCode) {
    }
});

この例ではズームレベル15以上の場合に自動で住宅地図が表示されるようになります。

住宅地図モードを終了するコードは以下の通りです。

//  住宅地図の表示を解除
map.endHousingMapDisplay();

自車マークのデザイン変更

CarMarkerDesignを生成しMap.setCarMarkerDesign()に渡すことで自車マークのデザインを変更することができます。

CarMarkerDesign carMarkerDesign = new CarMarkerDesign(getApplicationContext());
carMarkerDesign.setBearingImage(AppCompatResources.getDrawable(getApplicationContext(), R.drawable.my_car_mark));　// 自車マークのリソース

map.setCarMarkerDesign(carMarkerDesign);

自車マークは以下の画像で構成されています。

• TopImage：自車マークの上部画像
• BearingImage：自車マークの中央画像
• ShadowImage：自車マークの背景画像

画像はTop＞Bearing＞Shadowの順に重ね合わせて表示されます。それぞれCarMarkerDesign.setTopImage(), setBearingImage(), setShadowImage()で設定を行なって下さい。

ルート線のデザイン変更

Navi.setRouteDesign()によりNaviにattachされている全ての地図上に描画されるルート線のデザインを変更することができます。

ルート線の種類

状況に応じてルート線は複数のデザインを持っています。デザインを変更可能なルート線の種類は以下の通りです。

• 案内中（Navi.startGuidance()後）ルート
• 案内開始（Navi.startGuidance()）前の複数ルート探索結果で、選択されているルート
• 案内開始（Navi.startGuidance()）前の複数ルート探索結果で、選択されていないルート
• 新ルート（ルートアドバイザー、ルート比較）
• 分岐点から合流点までの新ルート（ルートアドバイザー）
• 分岐点から合流点までの旧ルート（ルートアドバイザー）
• 現在の区間（出発地から目的地までを立寄地で区切った区間）

案内中ルートと新ルートのデザイン例
この例では白い縞模様のルートが新ルートです。

一般道、有料道それぞれで別のデザインを設定することができます。

設定可能なデザイン

ルート線のデザインは

• ルート本体用
• ルート内側の縁取り用
• ルート外側の縁取り用

に分かれており、それぞれに色、太さを設定することが可能です。

SDKでは指定された色、太さの線を外側縁取り用＞内側縁取り用＞本体用＞の順番で描画する実装になっているため、内側の縁取り用の線を本体用の線より太くする必要があり、また外側の縁取り用の線を内側の縁取り用の線より太くする必要があります。

例えば有料道の案内中ルート本体の色、太さを変更するサンプルコードは以下の通りです。

RouteDesign tollDesign = new RouteDesign();
tollDesign.setRouteBodyColor(255, 0, 0);　// red
tollDesign.setRouteBodyWidth(10);
tollDesign.setBorder1Color(0, 255, 0); // green
tollDesign.setBorder1Width(15);
tollDesign.setBorder2Color(0, 0, 255); // blue
tollDesign.setBorder2Width(20);

Navi.getInstance().setRouteDesign(Common.TollRoadKind.TOLL, Map.RouteLineKind.GUIDANCE, tollDesign);

実線、破線

以下のルート線は実線、破線を指定することが可能で、破線はそのパターンを設定することもできます。

• 新ルート（ルートアドバイザー、ルート比較）
• 分岐点から合流点までの新ルート（ルートアドバイザー）

破線のパターンは破線を形成する交互の破線と間隔の長さを設定します。

RouteDesign tollDesign = new RouteDesign();
tollDesign.setRouteBodyColor(100, 150, 200);
tollDesign.setRouteBodyWidth(10);
// 破線
tollDesign.setRouteBodyLineType(RouteDesign.LineType.DASHED);
// 破線のパターン（Listで破線の長さと破線の間隔の長さを指定）
List<Double> dashArray = new ArrayList<>(Arrays.asList(1.0, 1.0));
tollDesign.setDashArray(dashArray);

Navi.getInstance().setRouteDesign(Common.TollRoadKind.TOLL, Map.RouteLineKind.NEW_ROUTE, tollDesign);

通過速度別のデザイン

渋滞や事故等によりルートの区間毎に通過に掛かる時間が異なりますが、 案内開始前のルート線ではその通過速度別のデザインを設定することができます。通過速度の種類は以下の通りです。

• 通常
• 低速
• ごく低速

通過速度通常のデザインは通常のルート線のデザインが用いられますが、低速、ごく低速の区間に関してはデザインを変更することが可能です。

ルート消去線（交差点拡大図）のデザイン

交差点拡大図では図内の通過したルートはルート消去線によって上書きされます。

このルート消去線のデザインも変更可能です。

設定可能なデザイン一覧

ルート種別毎の変更可能なデザインは以下の通りです。

Breadcrumbs

この章では走行軌跡の表示や操作について紹介します。

走行軌跡の仕様

走行軌跡は直線距離で約50mごとに端末内部に暗号化され記録されます。
(必ず50mではなく速度やGPS更新のタイミングによっては70mなどになる可能性もあります。)

デフォルトでは1000個、最大は5000個まで収集できます。
使用しているスマートフォンの処理能力によってはパフォーマンスが低下する可能性があるため、表示する端末の処理能力にあった設定をしてください。

走行軌跡のファイルはIDで管理されます。
同じ端末で異なるユーザーがログインする場合は、IDを変更することでユーザー毎に異なる走行軌跡を表示することができます。 IDは途中で変更することはできません。

収集モードと最大値の設定

NaviInitInfoで指定し、NaviのInitializeにて初期化します。
Initializeに関しては4.1.1. Initializeを参照ください

走行軌跡の表示

走行軌跡を表示したいMapに対してsetBreadcrumbsVisible()で設定できます。

走行軌跡の画像変更

走行軌跡を表示したいMapに対してsetBreadcrumbsImage()で設定できます。

走行軌跡の消去

Navi.eraseBreadcrumbs()を行うことで全ての走行軌跡が全て消去されます。

Cruising Area

この章ではCruising Areaの表示方法、制御方法について紹介します。

Cruising Areaとは

電力/燃料の消費量を推定し、推定した電力燃料消費率で到達可能なエリアを表示する機能です。

Cruising Area設定方法

大まかに以下の流れで設定します。

1. EnergyInfoの各パラメータを設定します。
2. EnergyInfo.ExtendCruisingAreaで表示したい燃料または電力消費率を設定します。
3. CruisingAreaRequestにEnergyInfoを設定し、Navi.getCruisingArea()を呼び出します。

日産リーフの後続可能領域を作成するサンプルは以下の通りです。

EnergyInfo energyInfo = new EnergyInfo();
energyInfo.setModel("ZAA-ZE1");
energyInfo.setEnergyType(EnergyInfo.EnergyType.ELECTRIC);

EnergyInfo.TypeElectric typeElectric = new EnergyInfo.TypeElectric();
typeElectric.setBattery(40F); // バッテリ容量[kWh]
energyInfo.setTypeElectric(typeElectric);

energyInfo.setEnergyInfoExtension(EnergyInfo.EnergyInfoExtension.CRUISINGAREA);
EnergyInfo.ExtendCruisingArea extendCruisingArea = new EnergyInfo.ExtendCruisingArea();
extendCruisingArea.setCruisingAreaRateList(new ArrayList<>(Arrays.asList(100, 50)));  // 電力消費率100%, 50%で到達可能な領域
energyInfo.setExtendCruisingArea(extendCruisingArea);

CruisingAreaRequest request = new CruisingAreaRequest();
request.setEnergyInfo(energyInfo);

Navi.getInstance().getCruisingArea(request, new CruisingAreaListener() {
	@Override
	public void onCompleted(ErrorCode errorCode, CruisingAreaResult result) {

		if (errorCode == ErrorCode.NONE) {
			// 地図全体が画面に収まるように拡大率を調整
			List<GeoCoordinate> pathPointList = new ArrayList<>();
			pathPointList.add(result.getRange().getLeftBottom());
			pathPointList.add(result.getRange().getRightTop());
			GeoBoundingBox geoBoundingBox = GeoBoundingBox.getBoundingBoxContainingGeoCoordinates(pathPointList);
			map.zoomTo(geoBoundingBox, 0, false);
		}
		else {
			// 失敗
		}
	}
});

Cruising Areaの条件調整

CruisingAreaRequest.Optionsによって、

• 探索基準
• 有料道路利用有無
• スマートIC利用有無

を切り替えられます。

CruisingAreaRequest request = new CruisingAreaRequest();
CruisingAreaRequest.Options options = new CruisingAreaRequest.Options();
options.setPriority(CruisingAreaRequest.Options.Priority.DISTANCE);
request.setOptions(options);

CruisingAreaRequest request = new CruisingAreaRequest();
CruisingAreaRequest.Options options = new CruisingAreaRequest.Options();
options.setPriority(CruisingAreaRequest.Options.Priority.MAIN_ROAD);
request.setOptions(options);

CruisingAreaRequest request = new CruisingAreaRequest();
CruisingAreaRequest.Options options = new CruisingAreaRequest.Options();
options.setPriority(CruisingAreaRequest.Options.Priority.MAIN_ROAD);
options.setUseToll(false);
options.setUseSmartIC(false);
request.setOptions(options);

Cruising Areaのデザイン変更

CruisingAreaDesignを設定して表示方法をカスタマイズできます。

CruisingAreaDesign.Contour contour = new CruisingAreaDesign.Contour();
contour.setFillColor(Color.RED); // 塗りつぶし色
contour.setFillOpacity(0.2f); // 不透明率
contour.setOutLine(true); // 境界線描画有無
contour.setOutLineColor(Color.BLACK); // 境界線色
contour.setOutLineWidth(2.00F); // 境界線幅(pixel)

List<CruisingAreaDesign.Contour> contourList = new ArrayList<>();
contourList.add(contour);

CruisingAreaDesign design = new CruisingAreaDesign();
design.setContourList(contourList);
Navi.getInstance().setCruisingAreaDesign(design);

Cruising Areaの表示制御について

全ての地図に対する制御

Cruising Areaを削除したい場合、Navi.eraseCruisingArea()を呼び出してください。

個別の地図に対する制御

Cruising Areaの表示、非表示を切り替えるには該当MapのMap.cruisingAreaVisibleをtrue(表示する)、またはfalse(非表示にする)に設定します。

個別の地図に対してデザインを変更したい場合、該当MapのMap.setCruisingAreaDesignを設定します。

個別の地図に対してCruising Areaを表示したい場合、該当MapのMap.setCruisingAreaを設定します。 引数にはNavi.getCruisingAreaResult()で取得したresultを渡してください。

個別の地図に対してCruising Areaを削除したい場合、該当MapのMap.eraseCruisingArea()を呼び出してください。

Search

目的地検索機能について

目的地検索機能ではルート探索において目的地を地図上から探すことなく、名称やジャンルを入力から目的地を探し、設定するための機能を提供します。以下の機能に大別されます。

• フリーワード検索

  • 目的地を設定するためにフリーワードにより施設を検索する機能です。

• ジャンル検索

  • 特定のジャンル（コンビニエンスストア等）に該当する施設のみを検索する機能です。

• 住所検索

  • 住所からその緯度経度を検索する機能です。

• 逆ジオコーディング

  • 緯度経度から住所を検索する機能です。

• ルート周辺検索

  • 案内中のルート周辺の施設を検索する機能です。

• 充電施設検索

  • 充電施設を検索する機能です。

• 検索履歴

  • 検索履歴の追加、取得、削除を行う機能です。

詳細は各機能のガイドを参照して下さい。

Free Word Search

この章では目的地を設定するためにフリーワードにより施設を検索（フリーワード検索）するための方法を紹介します。

おおまかな処理の流れ

フリーワード検索の処理の流れは以下の通りです。

1. SearchJP.FreewordSearchRequestのインスタンスを生成します。
   • 検索したいワードを設定します。
   • 検索したい場所の緯度経度、半径（指定しない場合は全国が対象）を設定します。
2. 設定済みのSearchJP.FreewordSearchRequestオブジェクトを引数に、SearchJP.search()を呼び出します。
3. 検索が完了すると、Listenerにて検索結果が通知されます。これで検索完了です。

SearchJP.FreewordSearchRequest request = new SearchJP.FreewordSearchRequest();

request.setKeyword("都庁");

GeoCoordinate position = new GeoCoordinate(35.689595, 139.692221);
request.setPosition(position);

SearchJP.getInstance().search(request, new SearchJP.SearchResultListener() {
	@Override
	public void onCompleted(SearchJP.ErrorCode errorCode, SearchJP.SearchResult searchResult) {
		// searchResultに検索結果が格納されています
	}
});

高度な検索

ソート順を指定する

SearchJP.FreewordSearchRequest.SortTypeで検索結果のソート順を指定することができます。 指定可能なソート順は以下の通りです。

• RECOMMENDED（おすすめ順）
• DISTANCE（距離順）

複数ワード検索

フリーワード検索では複数のワードを空白で区切ることでAND検索を行うことができます。

例：パイオニア カーナビ

ジャンル検索との組み合わせ

SearchJP.FreewordSearchRequestでワードに加えてジャンルキーを設定することでワードとジャンルのAND検索を行うことができます。ジャンルキーの取得方法についてはGenre Searchを参照して下さい。

駐車場満空情報を取得する

検索結果に駐車場が含まれる場合、その駐車場の混雑（満空）情報を取得することができます。

1. SearchJP.FreewordSearchRequest.Extensions のインスタンスを生成します。
   • 検索したいワードを設定します。
   • 検索したい場所の緯度経度、半径（指定しない場合は全国が対象）を設定します。
2. 設定済みのSearchJP.FreewordSearchRequest.Extensionsオブジェクトの、setParkingAvailabilityFlagを引数trueで呼び出します。
3. 生成したインスタンスをSearchJP.FreewordSearchRequestのsetExtentions()でリクエストに設定します

SearchJP.FreewordSearchRequest request = new SearchJP.FreewordSearchRequest();

SearchJP.FreewordSearchRequest.Extensions extensions = new SearchJP.FreewordSearchRequest.Extensions();
extensions.setParkingAvailabilityFlag(true);
request.setExtensions(extensions);

設定したリクエストを引数に、SearchJP.search()を呼び出すことで駐車場の混雑情報を取得することができます。取得可能な混雑情報は以下の通りです。

駐車場入口

検索した施設には駐車場の入口情報が設定されている場合があります。この駐車場の入口情報をルート探索時にすることで適切な駐車場入口に案内するルートを探索することができます。

Genre Search

この章では目的地を設定するために特定のジャンルに該当する施設を検索（ジャンル検索）するための方法を紹介します。

ジャンル

ジャンル階層

ジャンル検索ではユーザーがジャンル階層リストからジャンルを階層的に選択することを想定しています。

そのためジャンル情報は階層（レベル）化されており、上位のジャンルほど広範なジャンルになります。例えばコンビニエンスストアのジャンル階層は以下の通りです。

買物（レベル1）＞ コンビニエンスストア（レベル2）＞ セブンイレブン（レベル3）

ジャンルのレベルは1〜4までとなっており、数字が大きくなるほど詳細なジャンルになります。

ジャンル階層情報取得方法

SearchJP.getGenreList()の引数に取得したジャンル階層を設定し呼び出して下さい。処理が完了すると、Listenerにて階層情報取得結果が通知されます。

SearchJP.getInstance().getGenreList(1, new SearchJP.GenreListener() {
    @Override
    public void onCompleted(SearchJP.ErrorCode errorCode, List<SearchJP.Genre> genres) {
        // genresにジャンル情報が格納されています
    }
});

ジャンル名とジャンルキー

ジャンルにはジャンル名（文字列）とジャンルキー（整数値）がそれぞれ定義されています。例えばコンビニエンスストアの場合は以下の通りです。

• ジャンル名：コンビニエンスストア
• ジャンルキー：404

ジャンル検索を行う際にはこのジャンルキーを指定して検索を行うことになります。

おおまかな処理の流れ

ジャンル検索の流れは以下の通りです。

1. SearchJP.FreewordSearchRequestのインスタンスを生成します。
   • 検索したいジャンルのジャンルキーを設定します。
   • 検索したい場所の緯度経度、半径（指定しない場合は全国が対象）を設定します。
2. 設定済みのSearchJP.FreewordSearchRequestオブジェクトを引数に、SearchJP.search()を呼び出します。
3. 検索が完了すると、Listenerにて検索結果が通知されます。これで検索完了です。

SearchJP.FreewordSearchRequest request = new SearchJP.FreewordSearchRequest();

List<Integer> genrekeyList = new ArrayList<>();
genrekeyList.add(404);
request.setGenreKeyList(genrekeyList);

GeoCoordinate position = new GeoCoordinate(35.689595, 139.692221);
request.setPosition(position);

SearchJP.getInstance().search(request, new SearchJP.SearchResultListener() {
	@Override
	public void onCompleted(SearchJP.ErrorCode errorCode, SearchJP.SearchResult searchResult) {
		// searchResultに検索結果が格納されています
	}
});

Address Search

この章では目的地を設定するために住所から位置を検索（住所検索）するための方法を紹介します。

住所

住所階層

住所検索ではユーザーが住所階層リストから住所を階層的に選択することを想定しています。

そのため住所情報は階層（レベル）化されており、上位の住所ほど広範なエリアになります。住所階層と対応エリアは以下の通りです。

例えばレベル0（地方）では 「北海道・東北」「関東」「甲信越・北陸」「東海」「近畿」「中国」「四国」「九州・沖縄」の住所情報が取得できます。

住所コード

住所にはレベル毎に対応する住所コードが付与されています。

おおまかな処理の流れ

1. まず最上位階層（地方）の住所情報を取得します。
   • 取得した住所情報をアプリのUI上でユーザーに提示します。
2. 選択された地方の住所情報に含まれる住所コードを元にさらに下位（都道府県以下）の住所階層情報を取得します。
   • 住所情報にはその住所の位置を表す緯度経度情報が含まれます。その場所を目的地としたい場合はそこで住所検索を終了します。
3. 下位の住所階層情報が無くなるまで2.を繰り返します。

住所階層（最上位）情報取得方法

住所階層（最上位）情報の取得方法は以下の通りです。

1. SearchJP.GetLocationListByAddressRequestのインスタンスを生成します。
   • 特に設定は不要です。デフォルトで最上位階層（レベル0）の階層情報を取得します
2. SearchJP.GetLocationListByAddressRequestオブジェクトを引数に、SearchJP.search()を呼び出します。
3. 処理が完了すると、Listenerにて住所階層情報の取得結果が通知されます。

SearchJP.GetLocationListByAddressRequest request = new SearchJP.GetLocationListByAddressRequest();

SearchJP.getInstance().search(request, new SearchJP.AddressListener() {
    @Override
    public void onCompleted(SearchJP.ErrorCode errorCode, List<SearchJP.Address> addresses) {
        // addressesに住所階層情報が格納されています
    }
});

住所階層情報取得方法

住所階層情報の取得方法は以下の通りです。

1. SearchJP.GetLocationListByAddressRequest のインスタンスを生成します。
   • 検索したい住所の親階層で取得した住所情報の住所コードを設定します。
     • 例えば「北海道・東北」地方の都道府県レベルの住所階層情報を取得した場合、住所コードは'-01'（レベル0で取得した「北海道・東北」地方の住所コード）を設定します。
     • 住所階層を指定する必要はありません。住所コードから階層が自動的に判別されます。
2. SearchJP.GetLocationListByAddressRequestオブジェクトを引数に、SearchJP.search()を呼び出します。
3. 処理が完了すると、Listenerにて住所階層情報の取得結果が通知されます。

SearchJP.GetLocationListByAddressRequest request = new SearchJP.GetLocationListByAddressRequest();
request.setParentAddressCode("-01");

SearchJP.getInstance().search(request, new SearchJP.AddressListener() {
    @Override
    public void onCompleted(SearchJP.ErrorCode errorCode, List<SearchJP.Address> addresses) {
        // addressesに住所階層情報が格納されています
    }
});

Reverse Geocoding

この章では目的地を設定するために位置から住所、施設を検索（逆ジオコーディング）するための方法を紹介します。

逆ジオコーディングについて

逆ジオコーディングでは指定した位置から最も近い住所、施設を検索することができます。

ユーザーがタップした地図上の位置が本来ユーザーが設定したい目的地（住所、施設）から少し外れている場合でも、逆ジオコーディングで近くの住所、施設をユーザーに提示、選択してもらうことにより適切なルートを探索することができるようになります。

おおまかな処理の流れ

逆ジオコーディングの流れは以下の通りです。

1. SearchJP.ReverseGeocodingRequestのインスタンスを生成します。
   • 検索したい場所の緯度経度を設定します。
2. 設定済みのSearchJP.ReverseGeocodingRequestオブジェクトを引数に、SearchJP.search()を呼び出します。
3. 検索が完了すると、Listenerにて検索結果が通知されます。これで検索完了です。
   • 設定した緯度経度から直線距離で一番近い住所地点を取得することができます。
   • また、設定した緯度経度から半径100m以内の施設を取得することができます。

GeoCoordinate position = new GeoCoordinate(35.689595, 139.692221);

SearchJP.ReverseGeocodingRequest request = new SearchJP.ReverseGeocodingRequest(position);

SearchJP.getInstance().search(request, new SearchJP.ReverseGeocodingListener() {
    @Override
    public void onCompleted(SearchJP.ErrorCode errorCode, SearchJP.ReverseGeocodingResult reverseGeocodingResult) {
        // addressesに検索結果が格納されています
    }
});

Route Vicinity Search

この章ではルート周辺の施設を検索（ルート周辺検索）するための方法を紹介します。

ルート周辺検索について

ルート周辺検索では指定したルート周辺の施設を検索することができます。ルートの左右200mの範囲に含まれる施設が検索対象になり、道路に面した施設だけを検索するのではない点にご注意下さい。

おおまかな処理の流れ

新しくルートを探索する方法についてはNew Routeを参照して下さい。

1. SearchJP.RouteVicinitySearchRequestのインスタンスを生成します。
   • 検索したい場所の緯度経度を設定します。
   • 周辺を検索したいルートの形状情報を設定します。
     • 形状情報はRouteResult.getPathPointList()で取得可能です。
   • 検索したいワード、もしくはジャンルのジャンルキーを設定します。
     • ジャンルキーの取得方法についてはGenre Searchを参照して下さい。
     • ワード、ジャンルキーの両方を設定した場合はAND検索になります。
2. 設定済みのSearchJP.RouteVicinitySearchRequestオブジェクトを引数に、SearchJP.search()を呼び出します。
3. 検索が完了すると、Listenerにて検索結果が通知されます。これで検索完了です。

SearchJP.RouteVicinitySearchRequest request = new SearchJP.RouteVicinitySearchRequest();

request.setKeyword("都庁");

GeoCoordinate position = new GeoCoordinate(35.689595, 139.692221);
request.setPosition(position);

request.setRoutePathPointList(pathPointList); // ルート探索時の形状情報

SearchJP.getInstance().search(request, new SearchJP.SearchResultListener() {
    @Override
    public void onCompleted(SearchJP.ErrorCode errorCode, SearchJP.SearchResult searchResult) {
		// searchResultに検索結果が格納されています
    }
});

Charging Station Search

この章では充電施設を検索するための方法を紹介します。

充電施設検索方法

SDKは充電施設を検索する手段を３通り用意しています。

おおまかな処理の流れ

1. SearchJP.ChargingStationSearchRequestのインスタンスを生成し、rangeTypeに検索方法を指定します。
2. 検索方法に沿ったパラメータを設定します。
3. パラメータ設定済みのオブジェクトを引数にSearchJP.search()を呼び出し、検索を実行します。
4. 検索が完了すると、SearchJP.SearchResultListenerにて検索結果が通知されます。これで検索完了です。

周辺検索

周辺検索では、指定座標を中心とした半径radiusメートル内にある充電施設を検索します。

SearchJP.ChargingStationSearchRequest request = new SearchJP.ChargingStationSearchRequest();
request.setPosition(Navi.getInstance().getRunInfo().getOwnCarInfo().getGeoCoordinate());

request.setRangeType(SearchJP.ChargingStationSearchRequest.RangeType.AROUND);
SearchJP.ChargingStationSearchRequest.Around around = new SearchJP.ChargingStationSearchRequest.Around();
around.setRadius(1000); // 検索半径[m]
request.setAround(around);

SearchJP.getInstance().search(request, new SearchJP.SearchResultListener() {
	@Override
	public void onCompleted(SearchJP.ErrorCode errorCode, SearchJP.SearchResult searchResult) {
		// 見つかった全ての地点にアイコンを貼り付ける
		for (SearchJP.Place place : searchResult.getPlaceList()) {
			MapIcon icon = new MapIcon();
			icon.setImageResource(R.drawable.pin);
			icon.setIconAnchor(MapIcon.Icon_Anchor.ICON_ANCHOR_BOTTOM);
			icon.setID("Search Result");
			icon.setPosition(place.getPosition());
			m_map.addUserIcon(icon);
		}
	}
});

ルート沿い検索

ルート沿い検索では、案内中ルートや案内候補ルートの周辺pathWidthメートル以内の施設に限定して検索します。

SearchJP.ChargingStationSearchRequest request = new SearchJP.ChargingStationSearchRequest();
request.setPosition(Navi.getInstance().getRunInfo().getOwnCarInfo().getGeoCoordinate());

// RouteVicinity
request.setRangeType(SearchJP.ChargingStationSearchRequest.RangeType.ROUTE_VICINITY);
SearchJP.ChargingStationSearchRequest.RouteVicinity routeVicinity = new SearchJP.ChargingStationSearchRequest.RouteVicinity();

RouteResult routeResult = Navi.getInstance().getRouteResult();
routeVicinity.setPathPointList(Common.convertRouteResultToPathPointList(routeResult));
routeVicinity.setPathWidth(200); // ルートに対して左右それぞれ200メートルまで検索範囲とする
request.setRouteVicinity(routeVicinity);

SearchJP.getInstance().search(request, new SearchJP.SearchResultListener() {
	@Override
	public void onCompleted(SearchJP.ErrorCode errorCode, SearchJP.SearchResult searchResult) {
		for (SearchJP.Place place : searchResult.getPlaceList()) {
			MapIcon icon = new MapIcon();
			icon.setImageResource(R.drawable.pin);
			icon.setIconAnchor(MapIcon.Icon_Anchor.ICON_ANCHOR_BOTTOM);
			icon.setID("Search Result");
			icon.setPosition(place.getPosition());
			m_map.addUserIcon(icon);
		}
	}
});

ポリゴン内検索

ポリゴン内検索では、Cruising Areaの範囲内にある施設に限定して検索します。

SearchJP.ChargingStationSearchRequest request = new SearchJP.ChargingStationSearchRequest();
request.setPosition(Navi.getInstance().getRunInfo().getOwnCarInfo().getGeoCoordinate());

request.setRangeType(SearchJP.ChargingStationSearchRequest.RangeType.POLYGON);
SearchJP.ChargingStationSearchRequest.Polygon polygon = new SearchJP.ChargingStationSearchRequest.Polygon();
polygon.setOuterRing(Navi.getInstance().getCruisingAreaResult().getOuterRingList().get(0));
request.setPolygon(polygon);

SearchJP.getInstance().search(request, new SearchJP.SearchResultListener() {
	@Override
	public void onCompleted(SearchJP.ErrorCode errorCode, SearchJP.SearchResult searchResult) {
		for (SearchJP.Place place : searchResult.getPlaceList()) {
			MapIcon icon = new MapIcon();
			icon.setImageResource(R.drawable.pin);
			icon.setIconAnchor(MapIcon.Icon_Anchor.ICON_ANCHOR_BOTTOM);
			icon.setID("Search Result");
			icon.setPosition(place.getPosition());
			m_map.addUserIcon(icon);
		}
	}
});

高度な検索設定

SearchJP.ChargingStationSearchRequest.Extensions.ChargingSpotFilterを設定することで検索条件を変更できます。

例えば急速充電が可能で終日営業している施設に限定して検索したい場合のサンプルは以下の通りです。

SearchJP.ChargingStationSearchRequest.Extensions extensions = new SearchJP.ChargingStationSearchRequest.Extensions();
SearchJP.ChargingStationSearchRequest.Extensions.ChargingSpotFilter filter = new SearchJP.ChargingStationSearchRequest.Extensions.ChargingSpotFilter();
filter.setChargingTypeList(Arrays.asList(SearchJP.ChargingType.RAPID));
filter.setAllHoursFlag(true);
extensions.setChargingSpotFilter(filter);

Search History

この章では検索履歴を追加、取得、削除するための方法を紹介します。

検索履歴

SDKでは各種検索を行った結果を検索履歴として登録する事ができます。登録可能な主な項目は以下の通りです。

• 名前
• 住所
• 登録日時

その他の項目に関してはSearchJP.SearchHistoryを参照して下さい。

検索履歴の追加

検索履歴の追加にはSearchJP.addSearchHistoryを使用します。処理の流れは以下の通りです。

1. SearchJP.AddSearchHistoryRequestのインスタンスを生成します。
   • 登録したい履歴を設定します。
   • IDは必ず登録する必要があります。削除時にIDをキーに履歴を削除します。
2. 設定済みのSearchJP.AddSearchHistoryRequestオブジェクトを引数に、SearchJP.addSearchHistory()を呼び出します。
3. 追加が完了すると、Listenerにて追加結果が通知されます。これで追加完了です。

サンプルコードは以下の通りです。

SearchJP.AddSearchHistoryRequest request = new SearchJP.AddSearchHistoryRequest();
List<SearchJP.SearchHistory> historyList = new ArrayList<>();

SearchJP.SearchHistory history = new SearchJP.SearchHistory();
history.setHistoryId("1"); // 必須
history.setName("パイオニア川越");
history.setYomi("パイオニアカワゴエ");
history.setAddress("埼玉県川越市山田25-1");
history.setType(SearchJP.SearchHistory.Type.POI);
history.setTimestamp("2023-02-01T13:59:59Z");
historyList.add(history);

request.setSearchHistoryList(historyList);

SearchJP.getInstance().addSearchHistory(request, new SearchJP.AddSearchHistoryListener() {
    @Override
    public void onCompleted(SearchJP.ErrorCode errorCode) {
    }
});

検索履歴の取得

検索履歴の取得にはSearchJP.getSearchHistoryを使用します。処理の流れは以下の通りです。

1. SearchJP.GetSearchHistoryRequestのインスタンスを生成します。
2. 設定済みのSearchJP.GetSearchHistoryRequestオブジェクトを引数に、SearchJP.getSearchHistory()を呼び出します。
3. 取得が完了すると、Listenerにて取得結果が通知されます。これで取得完了です。

サンプルコードは以下の通りです。

SearchJP.GetSearchHistoryRequest request = new SearchJP.GetSearchHistoryRequest();

SearchJP.getInstance().getSearchHistory(request, new SearchJP.GetSearchHistoryListener() {
    @Override
    public void onCompleted(SearchJP.ErrorCode errorCode, SearchJP.GetSearchHistoryResult result) {
        // resultに検索履歴が格納されている
    }
});

検索履歴の削除

特定の検索履歴の削除

特定の検索履歴を削除したい場合、削除したい履歴のIDを指定しSearchJP.deleteSearchHistoryを呼び出します。処理の流れは以下の通りです。

1. SearchJP.DeleteSearchHistoryRequestのインスタンスを生成します。
   • 削除したい履歴をのIDリストを設定します。
2. 設定済みのSearchJP.DeleteSearchHistoryRequestオブジェクトを引数に、SearchJP.deleteSearchHistoryを呼び出します。
3. 削除が完了すると、Listenerにて削除結果が通知されます。これで削除完了です。

サンプルコードは以下の通りです。

SearchJP.DeleteSearchHistoryRequest request = new SearchJP.DeleteSearchHistoryRequest();
List<String> removeHistoryIdList = new ArrayList<>();
removeHistoryIdList.add("1");

request.setHistoryIdList(removeHistoryIdList);

SearchJP.getInstance().deleteSearchHistory(request, new SearchJP.DeleteSearchHistoryListener() {
    @Override
    public void onCompleted(SearchJP.ErrorCode errorCode) {
    }
});

特定の検索履歴の全削除

全ての検索履歴を削除したい場合はSearchJP.deleteAllSearchHistoryを呼び出します。サンプルコードは以下の通りです。

SearchJP.getInstance().deleteAllSearchHistory(new SearchJP.DeleteSearchHistoryListener() {
    @Override
    public void onCompleted(SearchJP.ErrorCode errorCode) {
    }
});

Route

ルートを探索したりルートを編集する機能は下の機能に大別されます。

• 新ルート探索

  • 新しいルートを探索します。

• EV用ルート探索

  • EV向けルートを探索します。目的地まで電力が足りないと予想される場合に自動的に充電施設を立ち寄り地に設定します。

• ルート消去

  • 案内中ルートを消去します。

• 案内中ルート編集

  • 案内中ルートを加工します。

• ルート比較

  • 案内中ルートと新ルートを比較、更新します。

• ルートアドバイザー

  • SDKがより良いルートを提案します。

• 高速道路入口出口調整

  • 使用する高速道路の入口、出口を調整します。

詳細は各機能のガイドを参照してください。

New Route

この章では新しくルートを探索するための方法を紹介します。

ルート探索のおおまかな処理の流れ

新しいルートを探索する処理の流れは以下の通りです。

1. RoutePlan のインスタンスを生成します。
   • 目的地を設定します。
   • 探索して欲しいルートの条件の数だけRouteOptionsインスタンスを生成し、RoutePlanオブジェクトに設定します。
2. 設定済みのRoutePlanオブジェクトを引数に、Navi.calculateRoute()を呼び出します。
3. 探索が完了すると、Listenerにて処理結果が通知されます。これで探索完了です。
4. 探索したルートで案内を開始したい場合、Navi.startGuidance()を呼び出します。

SDKデフォルトのルートを探索をする

RoutePlanとRouteOptionsは初期値を持っており、set関数にて設定されない限りは初期値が用いられます。

最低限設定が必要な項目は、

• RoutePlanの目的地 (setEndPoint)
• RouteOptionsのRouteID (setRouteID)

の2つです。

以下に例を示します。

RoutePlan routePlan = new RoutePlan();
routePlan.setEndPoint(new GeoCoordinate(35.932524, 139.471761)); // パイオニア川越工場

RouteOptions options = new RouteOptions();
options.setRouteID(1); // 複数ルート同時に探索する際のルートごとの識別子です。任意の値を設定可能です。

List<RouteOptions> optionList = new ArrayList<>();
optionList.add(options);
routePlan.setMultiRouteOptions(optionList);

Navi.getInstance().calculateRoute(plan, new CalcRouteListener() {
	@Override
	public void onCompleted(ErrorCode errorCode, CalcRouteResult calcRouteResult) {
		
		if (errorCode == CalcRouteListener.ErrorCode.NONE) {
			Navi.getInstance().startGuidance(new StartGuidanceListener() {
				@Override
				public void onCompleted(ErrorCode errorCodeOfStartGuidance, GuidePointResult guidePointResult) {
					if (errorCodeOfStartGuidance == StartGuidanceListener.ErrorCode.NONE) {
					}
				}
			});
		} else {
			// ルート探索失敗
		}
	}
});

上記のサンプルコードは下記のサンプルコードと等価です。

RoutePlan routePlan = new RoutePlan();
routePlan.setStartPointCurrent();
routePlan.setEndPoint(new GeoCoordinate(35.932524, 139.471761));
routePlan.setPersonalize(false);
routePlan.setVehicleInfo(null);
routePlan.setEnergyInfo(null);
routePlan.setWayPoints(null);
routePlan.setRouteWayPoints(null);
routePlan.setDesignationTimeUsage(RoutePlan.DesignationTimeUsage.None);

RouteOptions options = new RouteOptions();
options.setRouteID(1);
options.setAddAlternative(false);
options.setPriorityRank(1);
options.setSearchCriteria(RouteOptions.SearchCriteria.RECOMMENDED);
options.setUseToll(true);
options.setUseHighway(true);
options.setUseFerry(true);
options.setUseSmartIC(true);
options.setUseLearnData(true);
options.setCareJam(true);
options.setCareRegulation(true);
options.setCareTimeRegulation(true);
options.setCareUnpavedRoad(false);

List<RouteOptions> optionList = new ArrayList<>();
optionList.add(options);
routePlan.setMultiRouteOptions(optionList);

Navi.getInstance().calculateRoute(plan, new CalcRouteListener() {
	@Override
	public void onCompleted(ErrorCode errorCode, CalcRouteResult calcRouteResult) {
		
		if (errorCode == CalcRouteListener.ErrorCode.NONE) {
			Navi.getInstance().startGuidance(new StartGuidanceListener() {
				@Override
				public void onCompleted(ErrorCode errorCodeOfStartGuidance, GuidePointResult guidePointResult) {
					if (errorCodeOfStartGuidance == StartGuidanceListener.ErrorCode.NONE) {
					}
				}
			});
		} else {
			// ルート探索失敗
		}
	}
});

ルート探索が成功すると、自動的に地図にルート線が反映されます。

ルートを削除する場合、 Navi.eraseRoute()を呼び出してください。

Navi.getInstance().eraseRoute(null);

ルートの特徴を変更する

RouteOptions.SearchCriteriaを設定することで、探索するルートの特徴を変更できます。

パイオニア川越工場を目的地に、距離を優先したルート探索を行うサンプルコードは以下の通りです。

RoutePlan routePlan = new RoutePlan();
routePlan.setEndPoint(new GeoCoordinate(35.932524, 139.471761)); // パイオニア川越工場

RouteOptions options = new RouteOptions();
options.setRouteID(1);
options.setSearchCriteria(RouteOptions.SearchCriteria.DISTANCE);

List<RouteOptions> optionList = new ArrayList<>();
optionList.add(options);
routePlan.setMultiRouteOptions(optionList);

Navi.getInstance().calculateRoute(plan, new CalcRouteListener() {
	@Override
	public void onCompleted(ErrorCode errorCode, CalcRouteResult calcRouteResult) {
		
		if (errorCode == CalcRouteListener.ErrorCode.NONE) {
			Navi.getInstance().startGuidance(new StartGuidanceListener() {
				@Override
				public void onCompleted(ErrorCode errorCodeOfStartGuidance, GuidePointResult guidePointResult) {
					if (errorCodeOfStartGuidance == StartGuidanceListener.ErrorCode.NONE) {
					}
				}
			});
		} else {
			// ルート探索失敗
		}
	}
});

パイオニア川越工場を目的地に、時間を優先したルート探索を行うサンプルコードは以下の通りです。

RoutePlan routePlan = new RoutePlan();
routePlan.setEndPoint(new GeoCoordinate(35.932524, 139.471761)); // パイオニア川越工場

RouteOptions options = new RouteOptions();
options.setRouteID(1);
options.setSearchCriteria(RouteOptions.SearchCriteria.TIME);

List<RouteOptions> optionList = new ArrayList<>();
optionList.add(options);
routePlan.setMultiRouteOptions(optionList);

Navi.getInstance().calculateRoute(plan, new CalcRouteListener() {
	@Override
	public void onCompleted(ErrorCode errorCode, CalcRouteResult calcRouteResult) {
		
		if (errorCode == CalcRouteListener.ErrorCode.NONE) {
			Navi.getInstance().startGuidance(new StartGuidanceListener() {
				@Override
				public void onCompleted(ErrorCode errorCodeOfStartGuidance, GuidePointResult guidePointResult) {
					if (errorCodeOfStartGuidance == StartGuidanceListener.ErrorCode.NONE) {
					}
				}
			});
		} else {
			// ルート探索失敗
		}
	}
});

渋滞や規制を考慮するルートを探索する

RouteOptionsのsetCareJam()、setCareRegulation()、setCareTimeRegulation()を設定することで trueなら考慮、falseなら未考慮のルートを探索できます。

車両に合ったルートを探索する

車両情報を設定することで車両情報を考慮したルート探索を行うことが可能です。

車種、車高、車重、車幅、危険物積載有無をVehicleInfoで設定します。

例えば車高を200cmに設定した場合、180cmの車高制限がある道を避けてルート探索を行います。

サンプルコードは以下の通りです。

RoutePlan routePlan = new RoutePlan();
routePlan.setEndPoint(new GeoCoordinate(35.932524, 139.471761)); // パイオニア川越工場

RouteOptions options = new RouteOptions();
options.setRouteID(1); // 複数ルート同時に探索する際のルートごとの識別子です。任意の値を設定可能です。

List<RouteOptions> optionList = new ArrayList<>();
optionList.add(options);
routePlan.setMultiRouteOptions(optionList);

VehicleInfo vehicleInfo = new VehicleInfo();
vehicleInfo.setVehicleType(VehicleInfo.VehicleType.ORDINARY_AND_MEDIUM_PASSENGER);
vehicleInfo.setVehicleHeight(200);
vehicleInfo.setVehicleWidth(175);
vehicleInfo.setVehicleWeight(1645);
vehicleInfo.setDangerousLoaded(false);
routePlan.setVehicleInfo(vehicleInfo);

Navi.getInstance().calculateRoute(plan, new CalcRouteListener() {
	@Override
	public void onCompleted(ErrorCode errorCode, CalcRouteResult calcRouteResult) {
		
		if (errorCode == CalcRouteListener.ErrorCode.NONE) {
			Navi.getInstance().startGuidance(new StartGuidanceListener() {
				@Override
				public void onCompleted(ErrorCode errorCodeOfStartGuidance, GuidePointResult guidePointResult) {
					if (errorCodeOfStartGuidance == StartGuidanceListener.ErrorCode.NONE) {
					}
				}
			});
		} else {
			// ルート探索失敗
		}
	}
});

燃料/電力情報設定

エコ・コスト優先の探索を実施する場合および推定燃費/電費を算出する場合はEnergyInfoで燃料/電力情報の指定が必要です。

指定必須な燃料/電力情報は燃料種別や指定する情報によって異なり、以下の通りになります。

以下がトヨタカローラのガソリン車で燃料情報を設定し燃費を取得するまでの例です。

RoutePlan routePlan = new RoutePlan();
routePlan.setEndPoint(new GeoCoordinate(35.932524, 139.471761)); // パイオニア川越工場

RouteOptions options = new RouteOptions();
options.setRouteID(1); // 複数ルート同時に探索する際のルートごとの識別子です。任意の値を設定可能です。

List<RouteOptions> optionList = new ArrayList<>();
optionList.add(options);
routePlan.setMultiRouteOptions(optionList);

EnergyInfo energyInfo = new EnergyInfo();
energyInfo.setModel("6AA-ZWE219-AEXSB");	
energyInfo.setEnergyType(EnergyInfo.EnergyType.GASOLINE);
energyInfo.setHeight(144);
energyInfo.setWidth(175);
energyInfo.setWeight(1645);
energyInfo.setDisplacement(1.797F);
energyInfo.setIdlingStop(false);
routePlan.setEnergyInfo(energyInfo);

Navi.getInstance().calculateRoute(routePlan, new CalcRouteListener() {
	@Override
	public void onCompleted(ErrorCode errorCode, CalcRouteResult calcRouteResult) {
		if (CalcRouteListener.ErrorCode.NONE == errorCode) {
			// 推定燃費/電力の取得
			if (calcRouteResult.getRouteResults().get(0).getEstimatedEnergyInfo() != null) {
				float energyConsumption = calcRouteResult.getRouteResults().get(0).getEstimatedEnergyInfo().getEnergyConsumption();
			}
			Navi.getInstance().startGuidance(new StartGuidanceListener() {
				@Override
				public void onCompleted(ErrorCode errorCodeOfStartGuidance, GuidePointResult guidePointResult) {
					if (errorCodeOfStartGuidance == StartGuidanceListener.ErrorCode.NONE) {
					}
				}
			});
		}
		else {
			// ルート探索失敗
		}
	}
});

高度な目的地設定

駐車場を指定してルートを探索する

大型商業施設など、駐車場入り口座標と施設の中心座標が大きく離れている場合、 施設中心座標を目的地に指定すると駐車場入り口ではない道路を通過するルートになることがあります。

このような低品質なルートになるのを避けるため、駐車場の入り口座標を指定したルート探索が可能です。

例えば、東京スカイツリーを目的地に設定し、駐車場を近隣の民間駐車場に指定したルートを探索するサンプルは以下の通りです。

RoutePlan routePlan = new RoutePlan();
routePlan.setEndPoint(new GeoCoordinate(35.7100409, 139.810719));

plan.getRouteEndPoint().setParkingEntranceList(new ArrayList<ParkingEntrance>() {{
	// Dパーキング 東京スカイツリー前第１
	add(new ParkingEntrance(new ParkingEntrance.Toll(false), new GeoCoordinate(35.709085753910045, 139.80820773937228)));
}});

RouteOptions options = new RouteOptions();
options.setRouteID(1); // 複数ルート同時に探索する際のルートごとの識別子です。任意の値を設定可能です。

List<RouteOptions> optionList = new ArrayList<>();
optionList.add(options);
routePlan.setMultiRouteOptions(optionList);

Navi.getInstance().calculateRoute(plan, new CalcRouteListener() {
	@Override
	public void onCompleted(ErrorCode errorCode, CalcRouteResult calcRouteResult) {
		
		if (errorCode == CalcRouteListener.ErrorCode.NONE) {
			Navi.getInstance().startGuidance(new StartGuidanceListener() {
				@Override
				public void onCompleted(ErrorCode errorCodeOfStartGuidance, GuidePointResult guidePointResult) {
					if (errorCodeOfStartGuidance == StartGuidanceListener.ErrorCode.NONE) {
					}
				}
			});
		} else {
			// ルート探索失敗
		}
	}
});

目的地やルートのメタデータを設定する

目的地の検索結果などは検索直後に参照するのは容易ですが、アプリケーション再起動後に参照するには工夫が必要です。

そのための関数としてRouteEndPoint.setInfo() が用意されています。 この関数で設定された文字列はサーバーに保存され、RouteResult.RouteProfileInfo.getInfo()で参照できます。

例えば目的地名, 目的地名のカタカナ読みの2つの情報を保存するサンプルコードは以下の通りです。

RouteEndPoint routeEndPoint = routePlan.getRouteEndPoint();
routeEndPoint.setInfo(
	new HashMap<String, String>() {{
		put("destination name", "ファミリーマート 本駒込六丁目店");
		put("destination yomi", "ファミリーマート ホンコマゴメ ロクチョーメ テン");
	}}
);

立ち寄り地を追加する

目的地以外の地点を経由するルートを引きたい場合は RoutePlan に経由したい地点を追加します。

緯度経度のみを指定して立ち寄り地を追加する

パイオニア川越工場を目的地に、東京スカイツリーを立ち寄り地に設定したルート探索を行うサンプルコードは以下の通りです。

RoutePlan routePlan = new RoutePlan();
routePlan.setEndPoint(new GeoCoordinate(35.932524, 139.471761)); // パイオニア川越工場

List<GeoCoordinate> waypoints = new ArrayList<>();
waypoints.add(new GeoCoordinate(35.7100409, 139.810719)); // 東京スカイツリー
routePlan.setWayPoints(waypoints);

RouteOptions options = new RouteOptions();
options.setRouteID(1);

List<RouteOptions> optionList = new ArrayList<>();
optionList.add(options);
routePlan.setMultiRouteOptions(optionList);

Navi.getInstance().calculateRoute(plan, new CalcRouteListener() {
	@Override
	public void onCompleted(ErrorCode errorCode, CalcRouteResult calcRouteResult) {
		
		if (errorCode == CalcRouteListener.ErrorCode.NONE) {
			Navi.getInstance().startGuidance(new StartGuidanceListener() {
				@Override
				public void onCompleted(ErrorCode errorCodeOfStartGuidance, GuidePointResult guidePointResult) {
					if (errorCodeOfStartGuidance == StartGuidanceListener.ErrorCode.NONE) {
					}
				}
			});
		} else {
			// ルート探索失敗
		}
	}
});

立ち寄り地の駐車場入口座標を指定する

目的地に追加するのと同様に設定可能です。

List<RouteWayPoint> routeWayPoints = routePlan.getRouteWayPoints();
routeWayPoints.get(0).setAlongside(true);
routeWayPoints.get(0).setParkingEntranceList(new ArrayList<ParkingEntrance>() {{
	// Dパーキング 東京スカイツリー前第１
	add(new ParkingEntrance(new ParkingEntrance.Toll(false), new GeoCoordinate(35.709085753910045, 139.80820773937228)));
}});

条件が異なるルートを同時に探索する

最短距離のルートと時間優先のルート、幹線優先のルート、推奨ルートの4本を同時に探索する

RoutePlan routePlan = new RoutePlan();
routePlan.setEndPoint(goal);

List<RouteOptions.SearchCriteria> criteriaList = new ArrayList<RouteOptions.SearchCriteria>() {{
	add(RouteOptions.SearchCriteria.DISTANCE);
	add(RouteOptions.SearchCriteria.TIME);
	add(RouteOptions.SearchCriteria.MAIN_ROAD);
	add(RouteOptions.SearchCriteria.RECOMMENDED);
}};

List<RouteOptions> optionList = new ArrayList<>();
int routeId = 1;
for (RouteOptions.SearchCriteria criteria : criteriaList) {
	RouteOptions options = new RouteOptions();
	options.setSearchCriteria(criteria);
	options.setRouteID(routeId);
	routeId++;
	optionList.add(options);
}
routePlan.setMultiRouteOptions(optionList);

Navi.getInstance().calculateRoute(plan, new CalcRouteListener() {
	@Override
	public void onCompleted(ErrorCode errorCode, CalcRouteResult calcRouteResult) {
		
		if (errorCode == CalcRouteListener.ErrorCode.NONE) {
			Navi.getInstance().selectCalculateRoute(getSelectedRouteResult()); // 複数ルート探索した時はどのルートで案内開始したいのか指定してください
			Navi.getInstance().startGuidance(new StartGuidanceListener() {
				@Override
				public void onCompleted(ErrorCode errorCodeOfStartGuidance, GuidePointResult guidePointResult) {
					if (errorCodeOfStartGuidance == StartGuidanceListener.ErrorCode.NONE) {
					}
				}
			});
		} else {
			// ルート探索失敗
		}
	}
});

有料道路を回避するルートと、有料道路を使うルートを探索する

ある目的地goalに対して、有料道路を経由しないルートと有料道路を経由する可能性があるルートを同時に探索するサンプルコードは以下の通りです。

RoutePlan routePlan = new RoutePlan();
routePlan.setEndPoint(goal);

RouteOptions noToll = new RouteOptions();
noToll.setRouteID(1);
noToll.setUseToll(false);

RouteOptions useToll = new RouteOptions();
useToll.setRouteID(2);
useToll.setUseToll(true); // 明示的に設定しなくても初期値はtrueです

List<RouteOptions> optionList = new ArrayList<>();
optionList.add(noToll);
optionList.add(useToll);
routePlan.setMultiRouteOptions(optionList);

Navi.getInstance().calculateRoute(plan, new CalcRouteListener() {
	@Override
	public void onCompleted(ErrorCode errorCode, CalcRouteResult calcRouteResult) {
		
		if (errorCode == CalcRouteListener.ErrorCode.NONE) {
			Navi.getInstance().selectCalculateRoute(getSelectedRouteResult()); // 複数ルート探索した時はどのルートで案内開始したいのか指定してください
			Navi.getInstance().startGuidance(new StartGuidanceListener() {
				@Override
				public void onCompleted(ErrorCode errorCodeOfStartGuidance, GuidePointResult guidePointResult) {
					if (errorCodeOfStartGuidance == StartGuidanceListener.ErrorCode.NONE) {
					}
				}
			});
		} else {
			// ルート探索失敗
		}
	}
});

Charging Route

この章では新しくEV向けのルートを探索するための方法を紹介します。

EV向けルートの特徴

• 現在のバッテリ容量、到着時のバッテリ容量閾値、および充電開始目安から、充電が必要な場合に自動で充電施設を立ち寄り地に設定したルートを探索します。
• 自動的に追加される充電施設は最大５カ所です。
• ユーザーが任意に設定できる立ち寄り地は195箇所です。

EV向けルート探索方法

EV向けルートを探索するには車両情報(EnergyInfo)が必要です。 EnergyInfoの基本的な設定方法はこちらを参照してください。

これに加え、EnergyInfo.ExtendChargingAreaの設定が必須です。

例えば、日産リーフの設定例は以下の通りです。

EnergyInfo energyInfo = new EnergyInfo();
energyInfo.setModel("ZAA-ZE1"); // 車両型式
energyInfo.setEnergyUnitPrice(31f); // 電気代単価[円/kWh]

EnergyInfo.TypeElectric electric = new EnergyInfo.TypeElectric();
electric.setBattery(40f);
energyInfo.setTypeElectric(electric);

EnergyInfo.ExtendChargingArea chargingArea = new EnergyInfo.ExtendChargingArea();
chargingArea.setBatteryLevel(100); // 現在のバッテリ容量[%]
chargingArea.setBatteryLevelAtSupply(20); // 充電する目安[%]
chargingArea.setBatteryLevelOnArrival(20); // 目的地到着時に残しておきたいバッテリ容量[%]
energyInfo.setExtendChargingArea(chargingArea);

このように設定したenergyInfoをRoutePlan.setEnergyInfo()で設定し、Navi.calculateChargingRoute()にてルート探索します。

RoutePlan routePlan = new RoutePlan();
routePlan.setEndPoint(new GeoCoordinate(35.932524, 139.471761));

// 設定したEnergyInfoを適用
routePlan.setEnergyInfo(energyInfo);

Navi.getInstance().calculateChargingRoute(routePlan, (errorCode, calcRouteResult) -> {
	if (errorCode == CalcRouteListener.ErrorCode.NONE) {
		Navi.getInstance().startGuidance(new StartGuidanceListener() {
			@Override
			public void onCompleted(ErrorCode errorCodeOfStartGuidance, GuidePointResult guidePointResult) {
				if (errorCodeOfStartGuidance == StartGuidanceListener.ErrorCode.NONE) {
				}
			}
		});
	} else {
		// ルート探索失敗
	}
});

Erase Route

Navi.eraseRoute()にて案内中ルートを消去できます。
処理結果はEraseRouteListenerで通知されます。

ルート消去に成功すると、Naviにattachされている全ての地図のルート線が自動的に消去されます。

Navi.getInstance().eraseRoute(new EraseRouteListener() {
	@Override
	public void onCompleted(ErrorCode errorCode) {
	}
});

Edit Route

この章では案内中のルートを調整して別のルートにする方法を紹介します。

立ち寄り地追加

ルートに新しい立ち寄り地を設定するには、 Navi.editRoute()を使用します。

calculateRoute()を使ってもルートに立ち寄り地を追加できますが、 editRoute()はこれまで走行してきたルートを考慮した探索結果になる点が異なります。

たとえば、立ち寄り済みの立ち寄り地がある状況でcalculateRoute()による新ルート探索をした場合、 立ち寄り地を再度通るルートを探索します。

一方、editRoute()の場合は立ち寄り済みの地点を通るルートは探索しません。

editRoute()関数はRoutePlanオブジェクトを利用しますので、 calculateRoute()で使用したオブジェクトを再利用できるようにしておくとよいでしょう。

東京駅丸の内口を立ち寄り地点に追加してルート再探索するサンプルコードは以下の通りです。

RoutePlan plan = getCurrentRoutePlan(); // 何らかの手段で再利用するものと仮定します。
plan.addWayPoint(new GeoCoordinate(35.68152901559053, 139.76564067909706)); // 東京駅丸の内口

Navi.getInstance().editRoute(plan, new CalcRouteListener() {
	@Override
	public void onCompleted(ErrorCode errorCode, CalcRouteResult calcRouteResult) {
		if (errorCode == CalcRouteListener.ErrorCode.NONE) {
			// 成功した時の処理を記述してください
		}
	}
});

Compare Route

この章はルート比較について説明します。

ルート比較とは

新ルートを探索した時、案内中ルートと比べて距離や時間、料金がどの程度変わるのか、ルート形状がどう変わるのか、を比較するための機能です。

処理の流れ

1. 案内中ルートがある状態でCompareRouteRequestインスタンスを生成します。
2. 別ルートの条件を RouteOption によって調整します。
3. Navi.compareRoute()を呼び出します。リスナで結果が通知されます。
4. 処理結果が成功だった場合、新ルートで案内するか、案内中ルートの案内を継続するか選択できます。 新ルートで案内したい場合、Navi.startGuidance()の引数に compareRouteResult.getNewRoute() を指定します。 案内中ルートの案内を継続したい場合、Navi.cancelCompareRouteResult();を呼び出します。

有料道路を全く使わないルートを探索するサンプルコードは以下の通りです。

CompareRouteRequest request = new CompareRouteRequest();
RouteOptions options = new RouteOptions();
options.setUseToll(false);
options.setUseHighway(false);
request.setRouteOptions(options);

Navi.getInstance().compareRoute(request, (errorCode, compareRouteResult) -> {
	if (errorCode != CompareRouteListener.ErrorCode.NONE) {
		// 処理失敗
		return;
	}

	if (!compareRouteResult.isChangeRoute()) {
		// ルートに変化なし
		return;
	}

	if (newRouteSelected()) {
		// 新しいルートが選択された
		Navi.getInstance().startGuidance(compareRouteResult.getNewRoute(), new StartGuidanceListener() {
			@Override
			public void onCompleted(ErrorCode errorCode, GuidePointResult guidePointResult) {
				if (errorCode == StartGuidanceListener.ErrorCode.NONE) {
					// 成功時の処理が何かあればここに記述
				}
			}
		});
	}
	}
	else {
		// 案内中ルートでの案内を継続する
		Navi.getInstance().cancelCompareRouteResult();
	}
});

Route Advisor

ルートアドバイザーとは、ルート案内中により良いルートを提供する機能のことです。

SDKは以下の条件のいずれかを満たすとき、新ルートを提案します。

1. より良いルートが見つかった
2. 交通状況の変化によりルート上に通行止めが発生した

前者は、例えば渋滞を回避して早く目的地に到着するルートや、到着時間と有料道路料金のバランスから一般道を走行するルートなどです。

より良いルートの提案はドライバーの好みに合わなければ無視できますが、通行止めによる新ルート提案は無視せずドライバーにルート変更を余儀なくされることを通知し、新ルートに切り替えるべきでしょう。

提案を受ける

SDKから新ルートの提案を受けるにはRouteAdvisorListenerを設定します。

Navi.getInstance().setRouteAdvisorListener(new RouteAdvisorListener() {
	@Override
	public void onNewRouteProvideStarted(RouteAdvisorInfo routeAdvisorInfo) {
		// 新しいルートが提案された時に呼び出されます。
		// 画面に新ルートの特徴やルート全景を表示するとよいでしょう。
	}

	@Override
	public void onDistanceUpdated(RouteAdvisorInfo routeAdvisorInfo) {
		// 新ルートにした時、現在案内中ルートから逸れる地点までの距離が変化した時に呼び出されます。
		// あと何メートル以内に新・旧どちらかのルートを選んで欲しい、という処理を記述できます。
	}

	@Override
	public void onDistanceUpdateStopped() {
		// 新ルートが選ばれずにしばらく走行した時に呼び出されます。
		// これ以降、別のルートが提案されるまでリスナ呼び出しは発生しなくなります。
	}
});

[TODO] ルート新旧の比較のスクリーンショットを貼る

提案の種類を判別する

RouteAdvisorInfo.getType()で新ルートがどのような経緯で提案されたのか判別できます。

新ルートに切り替える

RouteAdvisorListenerで通知されるRouteAdvisorInfoをNavi.startGuidance()の引数に指定します。

Navi.getInstance().startGuidance(routeAdvisorInfo.getNewRoute(), (errorCode, guidePointResult) -> {
	if (errorCode == StartGuidanceListener.ErrorCode.NONE) {
		// 新ルート切り替え成功
	}
	else {
		// 新ルート切り替え失敗
	}
});

案内中ルートを継続する

提案された新ルートが不要な場合、Navi.cancelRouteAdvisorRoute()で消去します。

Navi.getInstance().cancelRouteAdvisorRoute();

Access Interchange Select

この章では高速道路の入口・出口のインターチェンジを調整する方法を紹介します。

この機能によって以下のようなドライバーの要望に応えられます。

• 高速道路を使う区間を絞っても所要時間にさほど変化がないので料金を抑えたい。
• 使用するICの周辺はいつも混雑するので少しずらしたい。

調整可能な範囲は入口・出口、それぞれ前後3つ分です。 前後3つの間にジャンクションが存在している場合、それぞれの路線ごとに最大3つ分まで選択肢に加わります。

例えば、東名高速道路の浜松ICから高速道路に入る経路の場合、前後にジャンクションが存在しませんので基準地点(浜松IC)を含む７地点から選択できます。

例えば、伊勢湾岸道路のみえ川越ICから高速道路を出る経路の場合、インターチェンジ3つ分の距離内に東名阪自動車道、新名神高速道路、国道475号線(東海環状自動車道)へ繋がるジャンクションが存在しています。 この場合、Fig.2のように各路線の出口を選択できます。

乗り降りICのデータ構造

路線ごとに施設リストが格納されています。

路線には通し番号が振られていて、施設は固有のIDが振られています。 施設はインターチェンジがジャンクションのどちらかで、ジャンクションの場合はそのジャンクションに接続されている路線の通し番号リストが格納されています。

Fig.3はFig.1を図示したものです。

Fig.4はFig.2を図示したものです。

みえ川越を起点としたリストには以下4つの路線が存在し、路線それぞれに施設リストが格納されています。

1. 伊勢湾岸自動車道
2. 東名阪自動車道
3. 新名神高速道路
4. 国道475号線(東海環状自動車道)

乗り降りIC指定処理の概要

1. Navi.getAccessibleIC()にて施設情報を取得します。結果がAccessICGetListenerで通知されます。
2. 画面に結果を表示して、ドライバーに施設を選択してもらいます。
3. AccessICRerouteRequestオブジェクトを生成し、選択した施設のIDを設定します。
4. Navi.reroute()にて、ルート再探索を実施します。結果がAccessICRerouteListenerで通知されます。ErrorCodeがNONEであれば成功です。

{
	// 施設情報を取得します
	Navi.getInstance().getAccessibleIC(m_accessICRerouteResult, new AccessICGetListener() {
		@Override
		public void onCompleted(ErrorCode errorCode, AccessICGetResult accessICGetResult) {
			if (errorCode == AccessICGetListener.ErrorCode.NONE) {
			// 成功時の処理
			}
		}
	});
}

// ~~ 中略 ~~

{
	// 選択された施設からルート再探索要求用オブジェクトを構築し、ルート再探索を実施します。
	// 入口施設のIDは entranceFacilityId、 出口施設IDは exitFacilityId に格納されていると仮定します。
	AccessICRerouteRequest.ICSpecification entrance = new AccessICRerouteRequest.ICSpecification();
	entrance.setId(entranceFacilityId);
	entrance.setKind(AccessICRerouteRequest.ICSpecification.Kind.SET);

	AccessICRerouteRequest.ICSpecification exit = new AccessICRerouteRequest.ICSpecification();
	exit.setId(exitFacilityId);
	exit.setKind(AccessICRerouteRequest.ICSpecification.Kind.SET);

	AccessICRerouteRequest request = new AccessICRerouteRequest();
	request.setEntrance(entrance);
	request.setExit(exit);

	AccessICRerouteListener accessICRerouteListener = new AccessICGetListener() {
		@Override
		public void onCompleted(ErrorCode errorCode, AccessICGetResult accessICGetResult) {
			if (errorCode == AccessICGetListener.ErrorCode.NONE) {
			// 成功時の処理
			}
		}
	};

	// 案内開始前ルートがある場合、reroute()の引数にそのルートを指定する必要があります。
	if (Navi.getInstance().hasRouteCandidates()) {
		Navi.getInstance().reroute(Navi.getInstance().getSelectRouteResult(), request, accessICRerouteListener);
	}
	else {
		Navi.getInstance().reroute(request, accessICRerouteListener);
	}
}

乗り降りIC指定解除の概要

AccessICRerouteRequestによって設定したインターチェンジを元に戻すことができます。

AccessICRerouteRequest.ICSpecificationオブジェクトを生成し、Kind.RELEASEを設定してください。 なお、施設IDは設定不要です。

AccessICRerouteRequest.ICSpecification entrance = new AccessICRerouteRequest.ICSpecification();
entrance.setKind(AccessICRerouteRequest.ICSpecification.Kind.RELEASE);

AccessICRerouteRequest request = new AccessICRerouteRequest();
request.setEntrance(entrance);

3つ先より遠いインターチェンジを探したい

起点となったインターチェンジではないインターチェンジに変更し、再度Navi.getAccessibleIC()を呼び出すと変更したインターチェンジを起点とした施設リストが生成されます。

この手順を繰り返すことで任意のインターチェンジから出入りできるようになります。

Navigation

この章では音声や画面でドライバーを目的地に誘導する方法を紹介します。

誘導には以下の機能があります。

• 音声誘導

  • 音声を使う誘導。

• 誘導画面

  • 画面を使う誘導。

• ハイウェイモード

  • 高速道路専用の画面を使う誘導。

詳細は各機能のガイドを参照して下さい。

音声誘導

音声誘導とはドライバーに「いつ」「どのように行動するか」を音声で伝え目的地に導く機能です。
この章では音声誘導をドライバーに提供する方法を紹介します。

音声誘導は案内中ルートがある時だけ提供されます。
ルート探索・案内開始方法は「New Route」を参照してください。

案内方法

SDKが提供する案内方法は２種類あり、 Settingのナビモード設定によって変化します。

誘導音声の取得方法

GuideEventListenerで誘導音声を取得するサンプルコードは以下の通りです。

Navi.getInstance().setGuideEventListener(new GuideEventListener() {
    @Override
    public void onGuide(Common.GuideEventKind guideEvent, String guidancePhrase, Common.GuideLanguageKind guidanceLanguage) {
        switch (guideEvent) {
			case PASSED:
			case FIRST_TIME:
			case SECOND_TIME:
			case THIRD_TIME:
			case JUST:
			case VOICE_NAVI:
				// 誘導音声のイベント受信処理
				break;
            default:
                break;
        }
    }
}

NaviModeがNORMALの場合、案内地点間の誘導回数は最大５回で、 GuideEventKindでどのタイミングにおける誘導なのかを通知します。

NaviModeがLANE_BY_LANEの場合は一律Common.GuideEventKind.VOICE_NAVIで通知します。

目的地・立ち寄り地到着案内

目的地や立ち寄り地に到着したとき、GuideEventListener.onGuide()による音声案内以外に、 DestinationArrivedListener.onArrived()またはWayPointArrivedListener.onArrived()を通知します。

これらの通知を受けるにはNavi.setDestinationArrivedListener()、Navi.setWayPointArrivedListener()でリスナを設定してください。

//立寄地到着イベントリスナーを追加
Navi.getInstance().setWayPointArrivedListener(new WayPointArrivedListener() {
	@Override
	public void onArrived() {
	}
});

//目的地到着イベントリスナーを追加
Navi.getInstance().setDestinationArrivedListener(new DestinationArrivedListener() {
	@Override
	public void onArrived() {
	}
});

誘導画面

案内地点を画面で示すことで「どこで行動するか」をわかりやすく伝えられます。

この章では画面表示を主体とした誘導を提供する方法を紹介します。

画面表示の種類

下表に示す３種類が利用できます。

Type	概要	画像提供方式
交差点拡大図	案内地点を地図の中心に置き、ルート線を矢印にして図示したものです。	SDKがSupportMapFragment に直接描画
案内イラスト	案内地点形状と、どの車線をどう通過するか図示したものです。	Bitmap
方面案内図	方面看板に進行方向を図示したものです。	Bitmap

事前準備

交差点拡大図および案内イラストを利用する場合、案内地点の交差点情報をNavi.getIntersectionData()で事前に取得しておいてください。

// 交差点情報取得
Navi.getInstance().getIntersectionData(guidePointID, true, new GetIntersectionDataListener() {
	@Override
	public void onCompleted(ErrorCode errorCode, GetIntersectionDataListener.Data data) {
		// 取得成功
		if (errorCode == ErrorCode.NONE && Navi.getInstance().getRouteNumber() == data.getRouteNumber()) {
			eraseGuidePointID = data.getEraseGuidePointID(); // Viewを非表示にするタイミングの判定に使用します。
			intersectionDataList = data.getIntersectionDataList(); // 後で使うので保持してください
		}
	}
});

事後処理

RunInfoが示す次の案内地点のIDがeraseGuidePointIDよりも大きくなった時、表示していた交差点拡大図や案内イラストを非表示にします。

案内地点が短距離の間に連続する場合、getEraseGuidePointID()を呼び出した時点でのRunInfoの次の案内地点IDより2以上進んだ値になり得ます。 非表示・表示を繰り返すことによる画面ちらつきを防ぐため、getEraseGuidePointID()を非表示のトリガにすることを推奨します。

final int nextGuidePointId = Navi.getInstance().getRunInfo().getNextGuidePoint().getGuidePoint().getGuidePointID();
if (nextGuidePointId >= eraseGuidePointID) {
	// 非表示処理を実行してください
}

交差点拡大図

交差点拡大図はMapの制御によって表示します。
常時表示するMapインスタンスとは別のインスタンスを生成し、それを拡大図専用として使うことを推奨します。

交差点拡大図を出すにはMap.showIntersectionView()を使用します。
この関数の引数にIntersectionMapSettingが必要ですが、動的に設定を変えなくてもよいなら次のように関数化しておくと便利です。

private IntersectionMapSetting createMyIntersectionMapSetting(Map map) {
	IntersectionMapSetting intersectionMapSetting = new IntersectionMapSetting();
	intersectionMapSetting.setWaitFully(true);
	intersectionMapSetting.setWaitFullyTimeoutTime(4000);
	intersectionMapSetting.setImmediateRemoveRouteLine(true);
	intersectionMapSetting.setZoomLevel(16.0);
	final float mapWidth = map.getWidth();
	final float mapHeight = map.getHeight();
	final float left = mapWidth * 0.2f;
	final float top = mapHeight * 0.2f;
	final float right = mapWidth * 0.8f;
	final float bottom = mapHeight * 0.8f;
	intersectionMapSetting.setArrowRange(new RectF(left, top, right , bottom));
	
	return intersectionMapSetting;
}

Map.showIntersectionView()を使用するサンプルコードは以下の通りです。

// 以下、map オブジェクトはどこかで用意されていると仮定します。
IntersectionMapSetting intersectionMapSetting = createMyIntersectionMapSetting(map);
map.showIntersectionView(intersectionData, intersectionMapSetting, new IntersectionViewListener() {
	@Override
	public void onCompleted(ErrorCode errorCode, int eraseGuidePointID) {
		// eraseGuidePointID は Navi.getIntersectionData() で取得したものと同じ値になります
	}
});

// 以下の処理で案内地点の旗を立てます。
// 必須ではありませんが、曲がる地点の視認性を向上させるために設定した方がいいでしょう。
GuidePoint guidePoint = Navi.getInstance().getRunInfo().getNextGuidePoint().getGuidePoint();
MapIcon image = new MapIcon();
image.setImageResource(R.drawable.baloon_guide);
image.setID(icontype_guidePoint);
image.setPosition(guidePoint.getGeoCoordinate());
map.addUserIcon(image);

案内イラスト

案内イラストはBitMap制御によって表示します。

Navi.getIntersectionData()で取得したデータに交差点の案内イラストが存在していれば、Bitmapで参照できます。
取得したBitMapはImageViewなどで表示してください。

// 該当地点(guidePointId)のイラストを探す。
IntersectionData.IllustData illustData = null;
for (IntersectionData intersectionData : intersectionData) {
	if (intersectionData.getGuidePointID() == guidePointId) {
		illustData = intersectionData.getIllustData();
		break;
	}
}

if (illustData == null || illustData.getIllust() == null) {
	return;
}

Bitmap illustBmp = illustData.getIllust();

ImageView imageView = (ImageView)findViewById(ResoureIdOfIllust); // Resource IDはアプリ固有の値をご利用ください
imageView.setImageBitmap(illustData.getIllust());

方面案内図

方面案内図はBitMap制御によって表示します。

案内地点のGuidePoint.DistrictSignに方面案内図が存在していれば、GuidePoint.DistrictSign.getIllust()でBitmapを取得できます。
取得したBitMapはImageViewなどで表示してください。

GuidePoint.DistrictSign districtSign = Navi.getInstance().getRunInfo().getNextGuidePoint().getGuidePoint().getDistrictSign();
districtSign.getIllust(new GuidePoint.DistrictSign.IllustListener() {
	@Override
	public void onCompleted(ErrorCode errorCode, Bitmap illust) {
		// 案内地点にイラストがない場合はリスナ呼び出しが発生しません。
		// イラストがない場合、getIllust()の戻り値がfalseになります。

		if (errorCode == ErrorCode.NONE) {
			ImageView imageView = (ImageView)findViewById(ResoureIdOfDistrictSignIllust); // Resource IDはアプリ固有の値をご利用ください
			imageView.setImageBitmap(illust);
		}
	}
});

その他の表示

画面表示に利用可能な要素を紹介します。

残距離

案内地点までの残距離を取得するにはRunInfo.GuidePointInfo.getDistance()を利用します。
RunInfoから取得してください。

float distanceUntilGuidePoint = Navi.getInstance().getRunInfo().getNextGuidePoint().getDistance();

案内方向

案内地点をどちらに曲がるのかを取得するにはGuidePoint.getDirection()を利用します。
RunInfoから取得してください。

GuidePoint.GuideDirection direction = Navi.getInstance().getRunInfo().getNextGuidePoint().getGuidePoint().getDirection();

交差点名

案内地点の交差点名称を取得するにはGuidePoint.getCrossName()を利用します。
RunInfoから取得してください。

String crossName = Navi.getInstance().getRunInfo().getNextGuidePoint().getGuidePoint().getCrossName();

信号機有無

案内地点に信号機が設置されているかどうかを取得するにはPassPoint.isTrafficLight()を利用します。
RunInfoから取得してください。

// 次の案内地点に対応する PassPoint を参照します
final boolean hasTrafficLightOnGuidePoint = Navi.getInstance().getRunInfo().getNextGuidePoint().getPassPoint().isTrafficLight();

車線

車線情報はGuidePoint.LaneInfoで定義されており、 案内地点や通過交差点の車線情報を取得するにはそれぞれ、

• GuidePoint.getLane()
• PassPoint.getLane()

を利用します。

LaneInfoは1本の車線を表現するデータ構造で、これをListで保持することで複数車線を表現します。
Listの先頭要素は左端の車線です。Indexが一つ増えるごとに1つ右の車線を示します。

LaneInfoが持つデータ概要を下表に示します。

これらのデータを組み合わせることで、Fig.1のように車線を表現します。

地図上に直近の通過交差点の信号機や一時停止標識、踏切のアイコンを表示する

地図画面に信号機、一時停止標識、踏切のアイコンを拡大表示したい場合、まずRunInfo.PassPointInfoが示すPassPointの

• PassPoint.isTrafficLight()
• PassPoint.isStopSign()
• PassPoint.isRailCross()

によってその地点に存在する地物を特定します。

PassPointを通過するごとに直近のPassPointのアイコンを更新するサンプルコードは以下の通りです。

// currentPassPointID, mapは広域変数と仮定します。

PassPoint pp = Navi.getInstance().getRunInfo().getNextPassPoint().getPassPoint();
if (pp.getPassPointID() == currentPassPointID) {
	return;
}

if (pp.getPassPointID() > currentPassPointID) {
	int iconRID = R.drawable.empty;
	if (pp.isTrafficLight()) {
		iconRID = R.drawable.traffic_light;
	}
	else if (pp.isStopSign()) {
		iconRID = R.drawable.stop_sign;
	}
	else if (pp.isRailCross()) {
		iconRID = R.drawable.rail_cross;
	}

	// 通過した地点のアイコンを消去
	map.deleteUserIcon("PassPoint");

	MapIcon icon = new MapIcon();
	icon.setImageResource(iconRID);
	icon.setID("PassPoint");
	icon.setPosition(pp.getGeoCoordinate());
	map.addUserIcon(icon);
}

Highway Mode

ハイウェイモードはFig.1のように高速道路の施設までの所要時間や施設が持つサービス一覧を提供する機能です。

この章ではハイウェイモードのデータを取り扱う方法を紹介します。

ハイウェイモード データ型の概要

ハイウェイモード データ型はHighwayInfoで表現されます。

このclassは大類すると以下2つのデータを持っています。

• 出口までのルート上の施設情報(HighwayInfo.FacilityInfo)のリスト
• 出口の情報(HighwayInfo.ExitInfo)

FacilityInfoはその施設がインターチェンジなのか、休憩施設なのか、ジャンクションなのか、といった施設種別や 現在地からの所要時間、施設名称が格納されます。
また、その施設に至るまでにある交通状況のアイコンも格納されます。(例: )
休憩施設の場合、その施設が提供するサービス(店舗情報、お手洗い、ハイウェイ情報ターミナルなど)が格納されます。 (例: )

ExitInfoはFacilityInfoから交通規制アイコン、渋滞状況、駐車場混雑状況を削除したデータ型です。

ハイウェイモード データ取得方法

使用可能になるタイミングや更新タイミングはHighwayModeChangedListenerにて通知されますので、Navi.setHighwayModeChangedListener()でリスナを設定してください。

Navi.getInstance().setHighwayModeChangedListener(new HighwayModeChangedListener() {
	@Override
	public void onModeChanged(boolean isHighwayMode) {
		if (isHighwayMode) {
			// trueならハイウェイモードのデータが利用可能です。
		}
		else {
			// falseならハイウェイモードのデータが利用不能になります。
		}
	}

	@Override
	public void onUpdate() {
		// onUpdate()はデータ内容が更新されたことだけしか通知されませんので、これをトリガにNaviから取得します。
		HighwayInfo highwayInfo = Navi.getInstance().getHighwayInfo();
		if (highwayInfo != null) {
			// FacilityInfoは距離が近い順に格納されています
			for (HighwayInfo.FacilityInfo  facilityInfo : highwayInfo.getFacilities()) {
				// 施設までの距離
				if (facilityInfo.getDistance() > 0) {
				}

				// 施設までの所要時間
				if (facilityInfo.getTime() > 0) {
				}

				// 施設名と施設種別
				if (facilityInfo.getInfos() != null) {
				}

				// 施設までの混雑状況
				switch (facilityInfo.getJam()) {
				case JAM:
					break;
				case RUSH:
					break;
				case SMOOTH:
					break;
				default:
					break;
				}

				// サービスのアイコン
				if (facilityInfo.getServices() != null) {
					for (HighwayInfo.FacilityInfo.Service service : facilityInfo.getServices())) {
					}
				}

				// インシデントのアイコン
				if (facilityInfo.getIncidentList() != null) {
					for (HighwayInfo.FacilityInfo.Incident incident : facilityInfo.getIncidentList()) {
					}
				}

				// 駐車場の混雑状況
				if (facilityInfo.getParkingInfo() != null) {
					HighwayInfo.FacilityInfo.Parking parking = facilityInfo.getParkingInfo();
				}
			}

			// 出口情報
			HighwayInfo.ExitInfo exitInfo = highwayInfo.getExitInfo();
			if (exitInfo != null) {
				// 施設までの距離
				if (exitInfo.getDistance() > 0) {
				}

				// 施設までの所要時間
				if (exitInfo.getTime() > 0) {
				}

				// 施設名と施設種別
				if (exitInfo.getInfos() != null) {
				}
			}
		}
	}
});

Location

この章では自車位置がルート上のどこにいるのか把握する方法と、ルート逸脱からの復帰手段を紹介します。

ルートと案内地点、通過交差点の関係

GuidePointとPassPointはルート全体を網羅するよう生成され、それぞれリスト管理されています。

Fig.1はルート全体とGuidePoint、PassPointがどう対応付くのか示したイメージです。
このルートはコンビニを立ち寄り地に設定していて、途中で踏切を通過します。

Fig.1に示したルートには案内地点が4つあります。

• GuidePoint:1 -- ルート開始地点から最初の突き当たり
  ここで右折の案内が必要ですので案内地点になっています。
• GuidePoint:2 -- コンビニに設定された立ち寄り地
  立ち寄り地は接近・到着したことの案内が必要ですので案内地点になっています。
• GuidePoint:3 -- 踏切を超えた先の信号機がある十字路
  ここで左折の案内が必要ですので案内地点になっています。
• GuidePoint:4 -- 目的地
  目的地は接近・到着したことの案内が必要ですので案内地点になっています。

Fig.1に示したルートには通過交差点が8つあります。

• PassPoint:1 -- ルート開始地点から最初の突き当たり (GuidePoint:1)
  案内地点は必ずPassPointが生成されます。
  信号機があるPassPointはisTrafficLight()がtrueを返します。
• PassPoint:2 -- 信号機のある丁字路
  案内が不要な地点にもPassPointは生成されます。
• PassPoint:3 -- コンビニに設定された立ち寄り地 (GuidePoint:2)
  立ち寄り地は必ずPassPointが生成されます。
• PassPoint:4 -- 踏切まえの信号機がある十字路
  
• PassPoint:5 -- 踏切
  踏切があるPassPointはisRailCross()がtrueを返します。
• PassPoint:6 -- 踏切後の信号機がない十字路
  信号機がない交差点もPassPointになり得ます。
• PassPoint:7 -- 踏切後の信号機がある十字路 (GuidePoint:3)
• PassPoint:8 -- 目的地 (GuidePoint:4)
  目的地は必ずPassPointが生成されます。

なお、
Navi.getGuidePointList()で案内地点リストを、
Navi.getPassPointList()で通過交差点リストをそれぞれ取得できます。

自車位置情報(RunInfo)の概要

RunInfoは

• 直近のGuidePointまでの距離や時間といった案内地点情報:GuidePointInfo
• 直近のPassPointまでの距離や時間といった通過交差点情報:PassPointInfo
• 自車走行速度や自車方位、走行中道路の名称や速度制限といった自車位置情報: OwnCarInfo
• 目的地までの距離や時間といった目的地情報:DestinationInfo

から構成されています。

OwnCarInfo、DestinationInfoの詳細はAPI Referenceをご覧ください。

GuidePoint と GuidePointInfoの違いについて

GuidePoint, PassPointは直前の地点からの情報を提供します。これらは自車位置によらず内容は変化しません。

一方、GuidePointInfo, PassPointInfoは自車位置に基づいた次の地点までの情報を提供します。

案内中ルートがない時のRunInfo

案内中ルートがない時にもRunInfoは提供され続けますが、有効なデータは次の２種類のみになります。

• OwnCarInfo
• PassPointInfo

案内中ルートがない場合のPassPointInfoは、予測進路上の通過交差点情報を提供します。
予測進路上の地点情報かどうかは、PassPointInfo.isPredicted()で判断できます。

予測進路上の通過交差点リストはNavi.getDetailPassPointList()で取得できます。

Navi.getPassPointList()とNavi.getDetailPassPointList()の違いについて

Navi.getPassPointList()は案内中ルートがある時だけ取得でき、目的地までのすべての地点が含まれます。
Navi.getDetailPassPointList()は案内中ルートの有無に関わらず取得でき、自車位置から一定距離以内の地点のみ含まれます。

どちらの関数もPassPointのListを返却しますが、Navi.getPassPointList()で得られるオブジェクトには以下のデータが含まれていません。
booleanを返却する関数は全てfalseを、オブジェクトを返却する関数は全てnullを返却します。

• オービス情報(getOrbisGuidanceInfo(), isOrbis())
• 合流案内音声情報(getJoinGuidanceInfo())
• 踏切案内音声情報(getRailCrossGuidanceInfo())
• レーン案内音声情報(getLaneGuidanceInfo())
• 方面案内音声情報(getDistrictSignGuidanceInfo())
• ワークロード情報(getWorkLoadInfo())
• 橋かどうか(isBridgeEntrance(), isBridgeExit(), isBridgeInLink(), isBridgeOutLink())
• 冠水注意地点かどうか(isFloodingZoneEntrance(), isFloodingZoneExit(), isFloodingZoneInLink(), isFloodingZoneOutLink())
• 未舗装路かどうか(isUnpavedRoadEntrance(), isUnpavedRoadExit(), isUnpavedRoadInLink(), isUnpavedRoadOutLink())
• 急カーブ情報(getCurveInfo())
• 事故多発地点かどうか(isAccidentProneEntrance(), isAccidentProneExit(), isAccidentProneInLink(), isAccidentProneOutLink(), isAccidentProneSpot())

特に注意すべき点として、オービスがあるかどうか(isOrbis())はNavi.getPassPointList()で得られるオブジェクトでは必ずfalseになります。

トンネルでの挙動について

SDKはトンネル内走行中は推定速度による走行状態となります。
この走行状態はトンネル内で自車位置を更新できない状態を防ぐための機能です。

この機能により、トンネル内でも

• 音声誘導を提供可能
• 地図上の自車位置アイコンを更新可能

になります。 ただし、この状態では正確に自車位置を更新することができません。

SDKが推定速度による走行状態になっているかどうかは、OwnCarInfo.isUsingEstimatedVelocity()で確認できます。

boolean isUsingEstimatedVelocity = Navi.getInstance().getRunInfo().getOwnCarInfo().isUsingEstimatedVelocity();

オートリルート

SDKがルートを逸れる道路を走行したことを検知すると、自動的にその道路から目的地までのルートを再探索します。 この再探索機能をオートリルートといいます。

再探索開始と完了の検知方法

AutoRerouteListenerにて再探索開始と完了をそれぞれ通知します。
この通知を受けたい場合、Navi.setAutoRerouteListener()でリスナを登録してください。

Navi.getInstance().setAutoRerouteListener(new AutoRerouteListener() {
	@Override
	public void onStarted() {
		// 再探索開始時の処理
	}

	@Override
	public void onFailed(ErrorCode errorCode) {
		// 再探索失敗時の処理
	}

	@Override
	public void onCompleted(ErrorCode errorCode, AutoRerouteResult autoRerouteResult) {
		// 再探索成功時の処理
	}
});

並走道路の判断間違い

SDKは並走道路を走行中、稀に逆の道路を走行中と判断する事があります。
この時、SDKは独力でこの間違いを検出できません。 そのためSDKは走行している道路を切り替える機能Navi.switchAnotherRoad()を提供しています。

道路切り替え処理のサンプルは以下の通りです。

Navi.getInstance().switchAnotherRoad();

実行結果はSwitchAnotherRoadResultListenerで通知されます。 リスナ登録処理のサンプルは以下の通りです。

// リスナ登録
Navi.getInstance().setSwitchAnotherRoadResultListener(new SwitchAnotherRoadResultListener() {
	@Override
	public void onCompleted(ResultCode resultCode) {
		switch (resultCode) {
			case SUCCESS_IC_ENTRANCE: // IC入口への別道路切換を実施して成功した
				break;
			case SUCCESS_IC_EXIT: // IC出口への別道路切換を実施して成功した
				break;
			case SUCCESS_NORMAL: // 一般道への別道路切換を実施して成功した
				break;
			case SUCCESS_TOLL: // 高速・有料道への別道路切換を実施して成功した
				break;
			case FAIL_NORMAL: // 一般道への別道路切換に失敗
				break;
			case FAIL_TOLL: // 高速・有料道への別道路切換に失敗
				break;
			case INVALID:
			case FAIL_UNKNOWN:
			default:
				// 別道路切換に失敗
				break;
		}
	}
});

ナビゲーション以外の案内

目的地へのルートが設定されている場合、目的地へ到着するための案内（ナビゲーション） が行われますが、この章ではその他の案内について解説します。

• 渋滞情報案内

  • 道路や駐車場の渋滞や通行規制に関しての案内です。

• 注意案内

  • ドライバーに運転中の注意を促すための案内です。

詳細は各機能のガイドを参照して下さい。

Traffic Guide

渋滞情報案内機能

渋滞情報案内機能では道路や駐車場の渋滞に関する情報を提供します。以下の機能に大別されます。

• 渋滞・通行規制案内情報提供

  • 道路の渋滞や通行規制についての情報を提供する機能です。

• 渋滞・規制線表示

  • 道路の渋滞や通行規制の状況を地図上に表示する機能です。

• 通行規制アイコン表示

  • 道路の通行規制アイコンを地図上に表示する機能です。

• 駐車場混雑状況アイコン表示

  • 駐車場混雑状況アイコンを地図上に表示する機能です。

詳細は各機能のガイドを参照して下さい。

渋滞情報の更新

地図上に表示する機能（渋滞・規制線表示、通行規制アイコン表示、駐車場混雑状況アイコン表示）は機能をONに設定後、定期的に自動更新されます。

渋滞・通行規制案内情報はアプリの任意のタイミングで最新の情報を取得することができます。

渋滞情報のソース

渋滞情報のソースには以下の２種類があります。

• VICS
  • VICSセンター提供の渋滞情報です。通行規制や駐車場混雑状況はVICS提供の渋滞情報でのみ取得可能です。
• プローブ情報
  • Pioneer Smart Loopを元にしたPioneer独自の渋滞情報です。

Traffic Guidance

この章では渋滞・通行規制案内情報を取得するための方法を紹介します。

取得可能な情報

ルート上の渋滞・通行規制案内情報、または自車位置周辺の通行規制案内情報を取得することができます。

渋滞案内情報

渋滞案内情報ではルート上の渋滞に関する以下のような情報を取得することができます。

• 渋滞の最後尾（渋滞が始まる地点）
• 渋滞の長さ
• 渋滞の通過までにかかる時間
• 音声案内フレーズ
  • 渋滞に関する音声案内情報
  • 例）「およそ500メートル先、400メートルの渋滞が発生しています。通過に5分ほどかかります。」

通行規制案内情報

通行規制案内情報ではルート上の交通規制に関する情報を取得することができます。またルートが無い場合には自車位置周辺の交通規制に関する情報を同様に取得することが可能です。

• 規制の発生地点
• 規制の情報
  • 例："車線規制"
• 規制の原因
  • 例："追突事故"
• 音声案内フレーズ
  • 規制に関する音声案内情報
  • 例）「10キロ以上先、追突事故のため、車線規制です。」

渋滞・通行規制案内情報取得方法

Navi.getTrafficGuideData()を呼び出して下さい。処理が完了すると、Listenerにて渋滞・通行規制案内情報取得結果が通知されます。

状況に応じて取得可能な情報は変わります。

• 案内中のルートがある場合
  ルート上の自車位置から先（一般道なら30km、高速道なら50kmまで）の渋滞・通行規制案内情報が取得できます。

• 案内中のルートがない場合
  自車位置周辺20kmの範囲の通行規制情報のみ取得できます。

Draw Jam Line

この章では渋滞・規制線を地図上に表示するための方法を紹介します。

渋滞・規制線

渋滞・規制線には以下の種類があります。

渋滞・規制線の表示方法

Map.setValidationTrafficLine()にtrueを渡すことで地図上に渋滞線の表示を行うことができます。

また、渋滞線の種類ごとに表示、非表示関数が用意されています。

個別に表示、非表示を切り替えたい場合に使用して下さい。

渋滞線の矢印表示

渋滞線の矢印部分はMap.setDisplayTrafficLineArrow()で表示有無を切り替えることができます。

渋滞情報更新時刻の取得

Map.addTrafficTimestampListener()でリスナーを追加することで地図上の渋滞情報（渋滞・規制線、通行規制アイコン、駐車場混雑状況アイコンいずれか）が更新された時刻を取得することができます。

リスナーを追加せずアプリの任意のタイミングで更新時刻を取得した場合はMap.getTrafficTimestamp()を使用して下さい。

Navi.getTrafficTimestamp()はルート探索時に使う渋滞情報の更新時刻のため、地図上の渋滞情報の更新時刻とは異なります。

Display Incident Spot

この章では通行規制アイコンを地図上に表示するための方法を紹介します。

通行規制アイコンの表示方法

Map.setValidationTrafficIncident()にtrueを渡すことで地図上に通行規制アイコンの表示を行うことができます。

規制の種別に応じたアイコンが自動的に表示されるため、アプリで特別な制御をする必要はありません。

通行規制アイコンの大きさ変更

Map.setTrafficIncidentIconSize()でアイコンの元画像に対する拡大比率を設定することができます。

詳細な規制情報の取得

通行規制アイコンが表示されている場所の詳細な規制情報（規制の内容、原因等）を取得することができます。

詳細な規制情報取得の流れは以下の通りです。

1. アイコンクリック通知リスナーで通行規制アイコンのクリックを検知します。
2. アイコンのIDを取得します。
3. 取得したIDを引数にMap.getTrafficIncidentInfo()を呼び出します。

map.addOnIconClickListener(new OnIconClickListener() {
    @Override
    public void onIconClick(IconKind kind, MapIcon maker) {
        if (kind == IconKind.INCIDENT) {
            TrafficIncidentInfo info = map.getTrafficIncidentInfo(maker.getID());
            // infoに規制情報が格納されています
        }
    }
});

全てのアイコンの詳細な規制情報を取得する場合はMap.getTrafficIncidentInfoAll()を呼び出して下さい。

Display Parking Status

この章では駐車場混雑状況アイコンを地図上に表示するための方法を紹介します。

駐車場混雑状況アイコンの表示方法

Map.setValidationTrafficParking()にtrueを渡すことで地図上に駐車場混雑状況アイコンの表示を行うことができます。

駐車場の混雑状況に応じたアイコンが自動的に表示されるため、アプリで特別な制御をする必要はありません。

駐車場混雑状況アイコンの大きさ変更

Map.setTrafficParkingIconSize()でアイコンの元画像に対する拡大比率を設定することができます。デフォルトは0.7となっているため、デフォルより大きくアイコンを表示したい場合は0.7より大きい値を指定して下さい。

詳細な駐車場情報の取得

駐車場混雑状況アイコンが表示されている駐車場の詳細な情報（混雑状況、収容台数等）を取得することができます。

詳細な駐車場情報取得の流れは以下の通りです。

1. アイコンクリック通知リスナーで駐車場混雑状況アイコンのクリックを検知します。
2. アイコンのIDを取得します。
3. 取得したIDを引数にMap.getTrafficParkingInfo()を呼び出します。

map.addOnIconClickListener(new OnIconClickListener() {
    @Override
    public void onIconClick(IconKind kind, MapIcon icon) {
        if (kind == IconKind.PARKING) {
            TrafficParkingInfo info = map.getTrafficParkingInfo(icon.getID());
            // infoに駐車場情報が格納されています
        }
    }
});

全てのアイコンの詳細な駐車場情報を取得する場合はMap.getTrafficParkingInfoAll()を呼び出して下さい。

Caution Guide

この章では注意案内情報を取得するための方法を紹介します。

注意案内

目的地へのルートが設定されている場合、目的地へ到着するための案内が行われますが、それ以外にもドライバーに運転中の注意を促すための案内（注意案内）が行われる場合があります。

注意案内情報は目的地への案内情報と同じくGuideEventListenerを通じてアプリに通知されます。 一時停止案内以外は音声案内用の案内フレーズ情報も一緒に通知され、Navi.startVoiceEngine()により音声案内エンジンの初期化が完了している場合はフレーズが効果音と共に音声再生されます。

踏切案内

走行中の道路の前方に踏切がある場合、アプリに踏切に関する案内情報が通知されます。

例）「この先踏切です。ご注意下さい」

合流案内

走行中の道路の前方に合流がある場合、アプリに合流に関する案内情報が通知されます。

例）「この先、左からの合流があります。ご注意下さい」

右左折専用レーン案内

走行中の道路の前方に右折、または左折用の専用レーンがある場合、アプリにレーンに関する案内情報が通知されます。

例）「およそ300m先、左折専用レーンがあります。ご注意ください。」

一時停止案内

走行中の道路の前方に一時停止がある場合、アプリに一時停止に関する案内情報が通知されます。

他の注意案内と異なり案内フレーズ情報はありませんが、Navi.startVoiceEngine()により音声案内エンジンの初期化が完了している場合は専用の通知音が再生されます。他の注意案内のような効果音の再生は行われません。

オービス案内

走行中の道路の前方にオービスがある場合、アプリにオービスに関する案内情報が通知されます。

例）「この先、速度取り締まり機が設置されています。」

案内情報の取得方法

GuideEventListenerで注意案内情報を取得するサンプルコードは以下の通りです。

Navi.getInstance().setGuideEventListener(new GuideEventListener() {
    @Override
    public void onGuide(Common.GuideEventKind guideEvent, String guidancePhrase, Common.GuideLanguageKind guidanceLanguage) {
        switch (guideEvent) {
            case RAIL_CROSS:
            case STOP_SIGN:
            case JOIN_NONE:
            case JOIN_FROM_RIGHT:
            case JOIN_FROM_LEFT:
            case EXPERT_LANE:
            case ORBIS:
                // 注意案内のイベント受信処理
                break;
            default:
                break;
        }
    }
}

GuideEventKindでが注意案内に該当する通知かどうかを判別することができます。

guidacePhraseはSDKにより自動的に音声再生されますが、音声が不要な場合はNavi.startVoiceEngineを呼び出さないか、Navi.stopVoiceEngineにより音声再生エンジンを停止して下さい。

注意案内の有効、無効切り替え方法

以下の関数で注意案内の有効、無効を個別に切り替えることができます。

Map Version

この章はSDKで使用する地図データのバージョンとその更新方法を紹介します。

• 使用地図データバージョン情報取得方法

  • 使用地図データのバージョンとその取得方法の紹介です。

• 使用地図データ更新方法

  • 使用地図データの更新方法の紹介です。

詳細は各機能のガイドを参照して下さい。

地図データの種類について

地図データはルートの探索・案内など、ナビゲーション動作に必要なデータと表示用のデータに分かれています。 表示用のデータはアプリで特別な更新処理を行う必要はなく自動的に更新されますが、ナビゲーション用データに関してはアプリ側で更新処理を行う必要があります。

以降「地図データ」は表示用データではなくナビゲーション用のデータのことを指します。

Get Map Version

この章は地図データのバージョン情報を取得する方法を紹介します

地図データバージョン情報の取得方法

サーバ上の地図データは定期的に最新のデータに更新され、それぞれ個別のバージョン情報が付与されています。

サーバ上の地図データのバージョンはVersion.getMapVersion()で取得することができます。VersionはNavi.getVersion()で取得することが可能です。

Navi.getInstance().getVersion(new GetVersionListener() {
    @Override
    public void onCompleted(ErrorCode errorCode, Version versionResult) {
        // versionResult.getMapVersion()で地図データバージョン情報の取得が可能
        String mapVersion = versionResul.getMapVersion();
    }
}

versionResultからはSDKのバージョン情報等も取得することができます。

Data Update

この章では使用する地図データを更新するための方法を紹介します。

最新地図データ利用可能通知

サーバ上の地図データは定期的に最新のデータに更新されますが、古いデータも１つだけ保持されており、最新とその１つ前のデータが利用可能です。

使用中の地図データより新しいバージョンの地図データを検出した場合、DataUpdateListenerを通じてアプリに通知されますが、検出されたデータバージョンのパターンによりそれぞれ以下の関数を通じて通知されます。

• dataUpdated()

  • 使用中の地図データバージョンが最新ではないが、サーバ上に地図データが存在し動作が可能な場合に通知
  • 例）
    • SDKが使用中のバージョン："1"
    • 最新のバージョン："2"
    • サーバ上で保持されている地図バージョン："1", "2"
      • SDKが使用中のバージョン"1"が保持されているため動作可能

• dataDeleted()

  • 使用中の地図データバージョンが最新でなく、サーバ上に地図データが存在せず動作が不可能な場合に通知
  • 例）
    • SDKが使用中のバージョン："1"
    • 最新のバージョン："3"
    • サーバ上で保持されている地図バージョン："2", "3"
      • SDKが使用中のバージョン"1"が保持されていないため動作不可能

通知を受信するためのサンプルコードは以下の通りです。

NaviInitInfo initInfo = new NaviInitInfo(this);

initInfo.setDataUpdateListener(new DataUpdateListener() {
    @Override
    public void dataUpdated(boolean hasRoute, NaviInitInfo.DataHandlingProcess dataHandlingProcess) {
    }

    @Override
    public void dataDeleted(boolean hasRoute, NaviInitInfo.DataHandlingProcess dataHandlingProcess) {
    }
}

使用地図データ更新処理

SDKではサーバ上のどの地図データを使用するかという情報を保持しています。DataUpdateListenerは最新の地図データの検出を通知するのみで、使用する地図データそのものは更新されません。地図データの更新はアプリの再起動後のSDK初期化処理中に行われます。

アプリ動作中の更新処理

dataUpdate()受信時

地図データ更新はアプリの再起動後のSDK初期化処理中に行われるため、アプリ動作中に最新地図データ利用可能通知を受信し、使用中の地図データを更新する場合はアプリの再起動が必要です。 ただしDataUpdateListener.dataUpdated()通知ではサーバ上に現在使用中の地図データが保持されているため、再起動せずそのまま動作を継続することも可能です。

dataDeleted()受信時

DataUpdateListener.dataDeleted()通知ではサーバ上に現在使用中の地図データが存在しないため、そのまま動作を継続することができません。再起動を行い、使用中の地図データの更新を行う必要があります。

SDK初期化中の更新処理

アプリ起動中のSDK初期化処理時に、SDKでは現在使用中の地図データより新しい地図データがサーバ上で利用可能かどうかのチェックを行なっており、利用可能な場合は使用する地図データを最新のものに更新します。

また前回動作中にルートが引かれておりそのルートの案内中だった場合、そのルートは古い地図データ用のルートであるため削除され、自動的に最新の地図データ用のルートが再探索され地図上に反映されます。

SDK初期化中の地図データ更新処理中にもDataUpdateListener.dataUpdated(), DataUpdateListener.dataDeleted()通知は行われます。SDK初期化中の通知とアプリ動作中の通知は通知時のdataHandlingProcessで以下のように判別可能です。

• SDK初期化中の場合
  • DataHandlingProcess.UPDATE_WITH_ROUTE
• アプリ動作中の場合
  • DataHandlingProcess.STAY

NaviInitInfo initInfo = new NaviInitInfo(this);

initInfo.setDataUpdateListener(new DataUpdateListener() {
    @Override
    public void dataUpdated(boolean hasRoute, NaviInitInfo.DataHandlingProcess dataHandlingProcess) {
        if (dataHandlingProcess == NaviInitInfo.DataHandlingProcess.STAY) {
            // アプリ動作中の場合。データ更新する場合はアプリの再起動が必要
        }
        else if (dataHandlingProcess == NaviInitInfo.DataHandlingProcess.UPDATE_WITH_ROUTE) {
            // SDK初期化中の場合。再起動してはいけない
        }
        else {
            // エラー処理
        }
    }

    @Override
    public void dataDeleted(boolean hasRoute, NaviInitInfo.DataHandlingProcess dataHandlingProcess) {
        if (dataHandlingProcess == NaviInitInfo.DataHandlingProcess.STAY) {
            // アプリ動作中の場合。アプリの再起動が必要
        }
        else if (dataHandlingProcess == NaviInitInfo.DataHandlingProcess.UPDATE_WITH_ROUTE) {
            // SDK初期化中の場合。再起動してはいけない
        }
        else {
            // エラー処理
        }
    }
}

使用地図データ更新完了通知

地図データの更新はアプリの再起動後のSDK初期化処理中に行われ、更新完了時にDataUpdateListener.dataUpdateCompleted()によって通知されます。

NaviInitInfo initInfo = new NaviInitInfo(this);

initInfo.setDataUpdateListener(new DataUpdateListener() {
    @Override
    public void dataUpdateCompleted(DataUpdateCompleteListener.ErrorCode dataUpdateErrorCode, CalcRouteListener.ErrorCode routeErrorCode, CalcRouteResult calcRouteResult) {
        // ルートが再探索された場合はcalcRouteResultに結果が格納される
    }
}

この通知を受け取ることでアプリはナビゲーション用の地図データの更新をユーザーに知らせることができます。

Android Auto

この章ではAndroidAutoを使用するための方法を紹介します。

AndroidAutoの起動処理

AndroidAutoの起動検出からinitializeまでは詳しくはAndroidAuto用地図表示機能(CarMap)を参照して下さい。

AndroidAuto画面操作の通知

initialize時にsetGestureHandlerでCarMapGestureHandlerの設定をしているため、地図の移動、スケールの変更が機能する状態になっています。

操作に対応する関数と動作は以下の通りです。

AndroidAuto画面の監視

initialize時に設定したオブザーバー(CarMapObserver)でAndroidAuto画面の監視が可能です。

ウィジェット

現在の地図の向きを表すコンパスウィジェットとMapBoxのロゴウィジェットをSDKで用意しているので配置可能です。

// Compass追加
CompassWidget compassWidget = new CompassWidget(getCarContext());
WidgetPosition compassPosition = new WidgetPosition();
compassPosition.setHorizontalAlignment(WidgetPosition.Horizontal.RIGHT);
compassPosition.setVerticalAlignment(WidgetPosition.Vertical.TOP);
compassPosition.setOffsetX(surfaceContainer.getWidth() * -0.025f);
compassPosition.setOffsetY(surfaceContainer.getHeight() * 0.25f);
compassWidget.setPosition(compassPosition);
carMap.addWidget(compassWidget);

// 回転角に応じてコンパスを回転
map.setOnMapRotateChangeListener(new OnMapRotateChangeListener() {
    @Override
    public void onRotateChanged() {
        compassWidget.setRotation(m_map.getOrientation() * -1);
    }
});

// MapBoxLogo追加
LogoWidget logoWidget = new LogoWidget(getCarContext());
carMap.addWidget(logoWidget);

アプリで好きなウィジェットを表示する場合はBitmapWidgetでアイコンの設定をしCarMap.addWidget()で配置が可能です。

また、追加したウィジェットはCarMap.removeWidget()で削除が可能です。

// 任意のウィジェット追加
BitmapWidget bitmapWidget = new BitmapWidget(BitmapFactory.decodeResource(m_carMap.getCarContext().getResources(), R.drawable.widget));     // 表示するウィジェットの設定
WidgetPosition bitmapPosition = new WidgetPosition();
bitmapPosition.setHorizontalAlignment(WidgetPosition.Horizontal.CENTER);
bitmapPosition.setVerticalAlignment(WidgetPosition.Vertical.BOTTOM);
bitmapWidget.setPosition(bitmapPosition);   // 配置する場所の設定
carMap.addWidget(bitmapWidget);     // CarMapに配置

// 任意のウィジェット削除
carMap.removeWidget(bitmapWidget);

終了処理

AndroidAuto終了時、CarMapの終了処理CarMap.exit()とAndroidAuto用のLifeCycle削除Navi.clearAndroidAutoLifecycle()を実行し正常に終了させてください。

Testing

この章ではアプリのテストを行う際に役に立つ機能を紹介します。

• デモ走行

  • デモ走行によるテスト方法の紹介です。

• ログ走行

  • デモ走行ではテストが難しい機能をログ走行でテストする方法の紹介です。

詳細は各機能のガイドを参照して下さい。

Demo run

デモ走行は実際に道路を走行することなく、自車をルート上を出発地から目的地まで擬似的に走行させる機能です。

音声や画面による誘導機能が正しく動作していることを確認するためにはルート探索を行い、実際にその道路を車で走行する必要がありますが、デモ走行では実際に道路を走行することなく誘導機能の確認を行うことができます。

デモ走行の開始・終了

DemoRunSettingのオブジェクトを作成しデモ走行の設定を行い、 Navi.startDemoRun()を呼び出すことでデモ走行を開始することができます。

デモ走行による自車位置の更新周期、デモ走行終了時の繰り返し設定等も設定することが可能です。

// 予めルートを引いておく

// デモ走行設定
DemoRunSetting demoRunSetting = new DemoRunSetting();
demoRunSetting.setDemoType(Common.DemoType.AUTO);
demoRunSetting.setDemoUpdateCycle(Common.DemoUpdateCycle.DEMO_UPDATE_CYCLE_1HZ); // 自車位置の更新周期
demoRunSetting.setAutoRepeat(true); // デモ走行終了時の繰り返し設定

// デモ走行開始
Navi.getInstance().startDemoRun(demoRunSetting);

デモ走行を終了するにはNavi.stopDemoRun()を呼び出します。

// デモ走行終了
Navi.getInstance().stopDemoRun(new StopDemoRunListener() {
    @Override
    public void onCompleted(ErrorCode errorCode) {
    }
});

デモ走行の速度変更

DemoRunSettingでデモ走行種別がCommon.DemoType.MANUALに設定されていた場合、Navi.setDemoSpeed()でデモ走行時の自車速度を変更することが可能です。

// 予めルートを引いておく

// デモ走行設定
DemoRunSetting demoRunSetting = new DemoRunSetting();
demoRunSetting.setDemoType(Common.DemoType.MANUAL);

// デモ走行開始
Navi.getInstance().startDemoRun(demoRunSetting);

// デモ走行速度変更（65km/h）
Navi.getInstance().setDemoSpeed(Common.DemoSpeed.DEMO_SPEED_65);

Log run

ログ走行は実際の走行時の走行データをログ走行ファイルとして保存し、保存したログ走行ファイルから走行を再現する機能です。

ログ走行の用途

ログ走行ファイルによる走行の再現は様々なケースで役立ちます。

テスト走行時の不具合の再現

テスト走行時のログ走行ファイルを保存しておくことで走行時に発生した不具合を後日改めて再現、解析することができます。

オートリルートの確認

デモ走行ではルート通りに走行してしまうためリルートが行われません。ログ走行によりルートを外れることでリルート動作を確認することができます。

踏切案内、一時停止案内、合流案内、右左折専用レーン案内、オービス案内

ルートがない場合にも行われる案内のため、デモ走行では確認ができない場合がありますが、ログ走行により対象道路を走行することで確認することができます。

並走道路の切り替え確認

デモ走行ではルート通りに走行してしまうため並走道路の切り替えを行うことができません。並走道路がある道路をログ走行することで確認することができます。

トンネルモードの確認

デモ走行ではトンネル内でもルート通り走行してしまうためトンネルモードの確認ができません。ログ走行によりトンネルモードの動作を確認することができます。

ルートアドバイザー

デモ走行ではルートを変更することがないためルートアドバイザーによる新ルート情報は提供されません。ログ走行によりルートアドバイザーの動作を確認することができます。

ログ走行ファイルの作成方法

Navi.setLogSaveEnabledにtrueを渡すことで以後の走行データがログ走行ファイルに保存されます。これから走る道路の走行ログを作成したい場合は出発前に走行ログの保存を開始して下さい。

ログ走行ファイルは端末のアプリ固有ストレージ領域に保存され、保存場所は以下の通りです。

/storage/emulated/0/Android/data/アプリのパッケージ名/files

ログ走行ファイルはNavi.setLogSaveEnabledをtrueにした時点の時刻を含んだファイル名で作成されるため、falseからtrueに変更する度に別のファイルが新たに作成されます。

ログ走行の開始・終了

保存されたログ走行ファイルをNavi.startLogRunで読み込むことでログ走行を行うことができます。 Navi.stopLogRunでログ走行を停止します。

Navi.startLogRunの引数でログ走行ファイルのパスを渡すため、ファイルを置く場所は任意です。

ログ走行ファイルのサンプル

各種動作確認用のログ走行ファイルのサンプルです。

・踏切案内
・一時停止案内
・合流案内
・右左折専用レーン案内
・オービス案内
・トンネルモードの確認

ルートアドバイザーの動作確認

SDKでは5分間隔でルートアドバイザーでの推奨ルート有無の確認を行なっており、また一定の走行条件を満たす必要があるため、ルートアドバイザーによる推奨ルートの提案はそれほど頻度高く発生するものではありません。

このようにルートアドバイザーの動作を確認するためには時間が掛かってしまうため、SDKでは以下のようなルートアドバイザーのテスト用機能を提供しています。

• 推奨ルート有無の確認周期（デフォルト5分）の変更
• 推奨ルートの探索条件設定

これらの機能を利用して効率的にルートアドバイザーの動作を確認することが可能です。

ルートアドバイザー動作確認手順

大まかなルートアドバイザー動作の確認手順は以下の通りとなります。

1. 有料道を含むルートを探索し案内を開始します。
2. Navi.command()で推奨ルート有無の確認周期と推奨ルートの探索条件設定を変更します。
   • 確認周期を短くすることで推奨ルートが提案されやすくなります。
   • 探索条件を一般道のみとすることで推奨ルートが提案されやすくなります。
3. ログ走行を開始します
   • ログ走行ファイル
     

サンプルコードは以下の通りです。

RoutePlan routePlan = new RoutePlan();
routePlan.setStartPoint(new GeoCoordinate(35.932524, 139.471761)); // パイオニア川越工場
routePlan.setEndPoint(new GeoCoordinate(35.748514, 139.615793)); // 練馬IC出口付近

RouteOptions options = new RouteOptions();
options.setRouteID(1);

List<RouteOptions> optionList = new ArrayList<>();
optionList.add(options);
routePlan.setMultiRouteOptions(optionList);

// ルート探索
Navi.getInstance().calculateRoute(routePlan, new CalcRouteListener() {
    @Override
    public void onCompleted(ErrorCode errorCode, CalcRouteResult calcRouteResult) {

        if (errorCode == CalcRouteListener.ErrorCode.NONE) {
            Navi.getInstance().startGuidance(new StartGuidanceListener() {
                @Override
                public void onCompleted(ErrorCode errorCodeOfStartGuidance, GuidePointResult guidePointResult) {
                    if (errorCodeOfStartGuidance == StartGuidanceListener.ErrorCode.NONE) {
                    }
                }
            });
        } else {
            // ルート探索失敗
        }
    }
});

// 推奨ルート有無の確認周期を5分から1分に変更
Integer[] args1 = new Integer[]{60};
if (Navi.getInstance().command("setRouteAdvisorInterval", args1) == false) {
    // 実行失敗
}
// 推奨ルートの探索条件設定(有料道を使わないルートを推奨)
Boolean[] args2 = new Boolean[]{false};
if (Navi.getInstance().command("setRouteAdvisorUseToll", args2) == false) {
    // 実行失敗
}

String path = getApplicationContext().getExternalFilesDir(null).getAbsolutePath() + "/RouteAdvisorTest.json"; // 走行ログファイルを置いたパス
if (Navi.getInstance().startLogRun(path)) {
    // ログ走行開始成功
}
else {
    // ログ走行開始失敗
}

API Reference

こちらをクリックすると新しいタブで開きます。

Troubleshooting

オートリルートが繰り返されて終わらないのですが、回避方法はありますか？

SDKはオートリルートに失敗すると、成功するまでルート再探索を繰り返します。 この時、失敗要因が時間規制(曜日・季節）の為探索不可(ErrorCode.AUTO_REROUTE_TIME_REGULATION) の場合、 ユーザー設定情報のルート探索における時間規制考慮有無を「考慮しない」に変更することでオートリルートを完了させられます。

ただしルート探索時点で通行不能な道を通るため、道路交通法違反にならないようドライバーに注意を促す必要があります。

Navi.getInstance().setAutoRerouteListener(new AutoRerouteListener() {
	@Override
	public void onStarted() {
		// 再探索開始時の処理
	}

	@Override
	public void onFailed(ErrorCode errorCode) {
		if (errorCode == AutoRerouteListener.ErrorCode.AUTO_REROUTE_TIME_REGULATION) {
			SetupInfo setupInfo = new SetupInfo();
			setupInfo.setCareTimeRegulation(Common.CareTimeRegulation.NOT_CONSIDER);
			Navi.getInstance().setSetupInfo(setupInfo, new UserSettingResultListener() {
				@Override
				public void onCompleted(ErrorCode errorCode) {
				}
			});
		}
	}

	@Override
	public void onCompleted(ErrorCode errorCode, AutoRerouteResult autoRerouteResult) {
		// 再探索成功時の処理
	}
});