オフライン検索機能

インターネットに接続されているか、オフライン環境で作業しているかにかかわらず、効率的に場所を検索する機能は重要です。両方のユースケースに対応するために、HERE SDK では 2 つの汎用性の高い検索ソリューションを提供しており、オンラインのみの SearchEngine とオフラインでそれに相当する OfflineSearchEngine を利用できます。OfflineSearchEngine は、オンライン版と同様の強固な検索機能を提供するように作られており、インターネットに接続していなくてもシームレスに情報を取得できます。SearchEngine と同様に、OfflineSearchEngine は次のように簡単に構築してアプリケーションに統合できます。

try {
    // Allows to search on already downloaded or cached map data.
    offlineSearchEngine = new OfflineSearchEngine();
} catch (InstantiationErrorException e) {
    throw new RuntimeException("Initialization of OfflineSearchEngine failed: " + e.error.name());
}

try {
    // Allows to search on already downloaded or cached map data.
    offlineSearchEngine = OfflineSearchEngine()
} catch (e: InstantiationErrorException) {
    throw RuntimeException("Initialization of OfflineSearchEngine failed: " + e.error.name)
}

OfflineSearchEngine は SearchEngine とほぼ同じインターフェースを備えていますが、HERE バックエンドサービスへの新しいリクエストを開始するのではなく、すでにダウンロードまたはキャッシュに保存されたマップデータから結果が取得されるため、結果は若干異なる場合があります。

この方法では、たとえば、SearchEngine の使用時に受信するデータと比較してデータが古い可能性があります。一方、このクラスではオンライン接続が必要ないため、より速く結果が得られる場合があります。

注

検索できるのは、すでにキャッシュに保存されているかプリロードされているオフラインマップデータのみです。キャッシュに保存されたマップデータのみを使用する場合、一部のタイルが読み込まれない場合があります。その場合、これらのタイルも読み込まれるまで結果は見つかりません。オフラインマップではこのようなことは起こり得ず、ダウンロードした地域で必要なマップデータが利用できることが保証されます。したがって、キャッシュに保存されたマップデータに依存しないことをお勧めします。

使用可能な OfflineSearchEngine インターフェースのほとんどは SearchEngine でも使用できますが、その逆は当てはまりません。すべてのオンライン機能がオフラインデータからアクセスできるわけではないためです。

さらに、HERE Places API で場所を識別する場所 ID は、オフラインの検索結果では異なります。

通常、自由形式の TextQuery を使用すると、少なくとも半径 62.5 km 以内で場所をオフラインで見つけることができます。首都は世界中のどこからでも見つけることができます。都市名などの専用の場所をクエリ文字列に追加すると、その場所の近くが検索されます。

以下に、OfflineSearchEngineの考えられるユースケースを1つ示します。たとえば、外出中に接続が一時的に失われることがあります。このような場合はダウンロード済みのマップデータを検索するのが合理的です。

これを行うには、まずデバイスの接続が失われたかどうかを確認する必要があります。2 番目のステップとして、優先検索エンジンを使用できます。

private boolean isDeviceConnected() {
  // An application may define here a logic to determine whether a device is connected or not.
  return isDeviceConnected;
}

...

if (isDeviceConnected()) {
    searchEngine.searchByText(query, searchOptions, querySearchCallback);
} else {
    offlineSearchEngine.searchByText(query, searchOptions, querySearchCallback);
}

// An application may define here a logic to determine whether a device is connected or not.
// For this example app, the flag is set from UI.
private var isDeviceConnected = true

...

if (isDeviceConnected) {
    searchEngine.searchByText(query, searchOptions, querySearchCallback)
} else {
    offlineSearchEngine.searchByText(query, searchOptions, querySearchCallback)
}

検索結果を処理するには、(すでに上で示したように) 同じ querySearchCallback を設定します。

同様の方法で、住所をリバースジオコーディングすることもできます。

if (isDeviceConnected()) {
    searchEngine.searchByCoordinates(geoCoordinates, reverseGeocodingOptions, addressSearchCallback);
} else {
    offlineSearchEngine.searchByCoordinates(geoCoordinates, reverseGeocodingOptions, addressSearchCallback);
}

if (isDeviceConnected) {
    searchEngine.searchByCoordinates(
        geoCoordinates,
        reverseGeocodingOptions,
        addressSearchCallback
    )
} else {
    offlineSearchEngine.searchByCoordinates(
        geoCoordinates,
        reverseGeocodingOptions,
        addressSearchCallback
    )
}

次のようにして住所を地理座標にジオコーディングすることもできます。

if (isDeviceConnected()) {
    searchEngine.searchByAddress(query, options, geocodeAddressSearchCallback);
} else {
    offlineSearchEngine.searchByAddress(query, options, geocodeAddressSearchCallback);
}

if (isDeviceConnected) {
    searchEngine.searchByAddress(query, options, geocodeAddressSearchCallback)
} else {
    offlineSearchEngine.searchByAddress(query, options, geocodeAddressSearchCallback)
}

デバイスの接続を確認できる解決策は、最初に実際の接続を試みて実装することができます。これに失敗した場合は、OfflineSearchEngine に切り替えるか、その逆を行うことができます。最初にオフラインでの検索を試すこともできますが、マップデータが利用できない場合は、オンラインで試すことができます。

注

このセクションの完全なコードは、GitHub の SearchHybrid サンプルアプリに含まれています。

インデックス作成でオフライン検索を使用する

OfflineSearchEngine の検索結果を改善するには、OfflineSearchIndex.Options を設定します。デフォルトでは、インデックス作成は無効になっています。

インデックス作成は、提供された検索センターから遠く離れている場合でも、インストールされた Region データ内の場所を検索するメカニズムを提供します。これは、オンラインでのみ動作するため、検索インデックスを作成する必要がなく、デフォルトでこれを行う SearchEngine の動作と一致させるのに役立ちます。

OfflineSearchIndexListener を設定して、インデックス作成プロセスを追跡できます。

注

これはこの機能のベータリリースであるため、いくつかのバグや予期しない動作が発生する可能性があります。API は、非推奨のプロセスを経ずに、新しいリリースに変更される可能性があります。

内部的には、インデックス作成によってデバイス上に追加データが作成され、インストールされているすべての地図情報が検索可能になります。

インデックス作成が有効になっている場合は永続ストレージのコンテンツを変更するすべての操作に影響します。

mapDownloader.downloadRegions(..)
mapDownloader.deleteRegions(..)
mapDownloader.clearPersistentMapStorage(..)
mapDownloader.repairPersistentMap(..)
mapUpdater.performMapUpdate(..)
mapUpdater.updateCatalog(..)

これらのメソッドにより、永続ストレージにインストールされている Region データのエントリーを含むようにインデックスが作成、削除、更新されることが保証されます。

インデックスの作成には時間がかかるため、オフラインマップのダウンロードや更新を行うすべての操作により長い時間がかかりますが、通常は数秒から数分程度です (インストールされているオフラインマップデータの量によって異なります)。また、保存されたインデックスにより、オフラインマップが占有する容量が約 5% 増加します。

enableOfflineSearchIndexing(...)メソッドは、OfflineSearchEngineのインデックス作成を有効にする方法と、IndexListenerを実装してインデックス作成プロセスをモニタリングする方法を示します。

private void enableOfflineSearchIndexing(SDKNativeEngine sdkNativeEngine) {
    offlineSearchIndexOptions = new OfflineSearchIndex.Options();
    offlineSearchIndexOptions.enabled = true;

    offlineSearchIndexListener = new OfflineSearchIndexListener() {
        @Override
        public void onStarted(@NonNull OfflineSearchIndex.Operation operation) {
            Log.d("OfflineSearchIndexListener", "Indexing started. Operation: " + operation);
            snackbar.setText("Indexing started: " + operation).show();
        }

        @Override
        public void onProgress(int percentage) {
            Log.d("OfflineSearchIndexListener", "Indexing progress: " + percentage + "%");
            snackbar.setText("Indexing progress: " + percentage + "%").show();
        }

        @Override
        public void onComplete(@Nullable OfflineSearchIndex.Error error) {
            if (error == null) {
                Log.d("OfflineSearchIndexListener", "Indexing completed successfully.");
                snackbar.setText("Indexing completed successfully.").show();
            } else {
                Log.e("OfflineSearchIndexListener", "Indexing failed: " + error.name());
                snackbar.setText("Indexing failed: " + error.name()).show();
            }
        }
    };

    offlineSearchEngine.setIndexOptions(sdkNativeEngine, offlineSearchIndexOptions, offlineSearchIndexListener);
}

private fun enableOfflineSearchIndexing(sdkNativeEngine: SDKNativeEngine) {
    offlineSearchIndexOptions = OfflineSearchIndex.Options()
    offlineSearchIndexOptions!!.enabled = true

    offlineSearchIndexListener = object : OfflineSearchIndexListener {
        override fun onStarted(operation: OfflineSearchIndex.Operation) {
            Log.d(
                "OfflineSearchIndexListener",
                "Indexing started. Operation: $operation"
            )
            snackbar.show("Indexing started: $operation")
        }

        override fun onProgress(percentage: Int) {
            Log.d("OfflineSearchIndexListener", "Indexing progress: $percentage%")
            snackbar.show("Indexing progress: $percentage%")
        }

        override fun onComplete(error: OfflineSearchIndex.Error?) {
            if (error == null) {
                Log.d("OfflineSearchIndexListener", "Indexing completed successfully.")
                snackbar.show("Indexing completed successfully.")
            } else {
                Log.e("OfflineSearchIndexListener", "Indexing failed: " + error.name)
                snackbar.show("Indexing failed: " + error.name)
            }
        }
    }

    OfflineSearchEngine.setIndexOptions(
        sdkNativeEngine,
        offlineSearchIndexOptions, offlineSearchIndexListener
    )
}

上記では、インデックス作成プロセスを追跡するためにOfflineSearchIndexListenerが実装されています。このリスナーにより、インデックス作成のステータスをモニタリングするための3つのコールバックが提供されます。onStarted()コールバックはインデックス作成が開始されると呼び出されます。これは、マップデータが変更された場合や、OfflineSearchEngine.setIndexOptions()が呼び出された場合に行われます。既存のインデックスがインストール済みのマップリージョンと一致している場合は、何も実行されません。インデックス作成が進行すると、onProgress()コールバックが現在の進行状況をパーセンテージで報告し、インデックスの作成または削除の進行状況を示します。インデックス作成が完了すると、onComplete()コールバックが呼び出されます。成功した場合、エラーはnullになります。失敗した場合は、エラーによって問題の詳細が表示されます。通知は、インデックスの再構築が必要な場合にのみ送信されます。

オフラインで独自の場所を使用する

HERE SDK では、オフラインで場所を検索する場合、実行時に独自の場所を使用できます。

OfflineSearchEngine を使用すると、オフラインで検索できる場所のカスタムデータを挿入できます。このような個人的な場所は通常のクエリによって見つけることができます。結果は、HERE から直接取得された他の場所と同様にランク付けされます。

カスタム場所データを含めることができる複数の GeoPlace インスタンスを作成できます。これらのインスタンスはその後 MyPlaces データソースに追加できます。

List<GeoPlace> geoPlaces = Arrays.asList (
          GeoPlace.makeMyPlace("Pizza Pino", new GeoCoordinates(52.518032, 13.420632)),
          GeoPlace.makeMyPlace("PVR mdh", new GeoCoordinates(52.51772, 13.42038)),
          GeoPlace.makeMyPlace("Harley's bar", new GeoCoordinates(52.51764, 13.42062))
  );

  myPlaces.addPlaces(geoPlaces, new OnTaskCompleted() {
      @Override
      public void onTaskCompleted(@NonNull TaskOutcome taskOutcome) {
          if (taskOutcome == TaskOutcome.COMPLETED) {
              // Task completed
          } else {
              // Task cancelled
          }
      }
  });

このデータソースは OfflineSearchEngine に添付できます。

offlineSearchEngine.attach(myPlaces, new OnTaskCompleted() {
    @Override
    public void onTaskCompleted(@NonNull TaskOutcome taskOutcome) {
        if (taskOutcome == TaskOutcome.COMPLETED){
                // Task completed
        } else {
                // Task cancelled
        }
    }
});

アプリケーションによって一度に数千の場所が追加される可能性があるため、addPlaces() と attach() は非同期で動作します。どちらのメソッドも TaskHandle を返すため、操作をキャンセルできます。TaskOutcome イベントは操作がいつ終了したかを通知します。

以下は、そのような場所を見つける方法の一例です。

int radiusInMeters = 100;
TextQuery.Area queryArea = new TextQuery.Area(new GeoCircle(new GeoCoordinates(52.518032, 13.420632), radiusInMeters));
TextQuery textQuery = new TextQuery("Pizza Pino", queryArea);
offlineSearchEngine.searchByText(textQuery, new SearchOptions(), new SearchCallback() {
    @Override
    public void onSearchCompleted(@Nullable SearchError searchError, @Nullable List<Place> list) {
        // ...
    }
});

追加された場所は、offlineSearchEngineインスタンスが有効な限りメモリ内に残ることに注意してください。

軌道に沿って分散された結果

OfflineSearchEngineでは、検索結果がルートの軌道に沿って適切に分散されるようにする、distributedResultsという検索機能をサポートしています。すべての結果を1つの領域にまとめるのではなく、移動ルートに沿って等間隔に配置された施設情報を検索する場合にこの機能が特に便利です。distributedResults機能を使用するには、SearchOptionsでdistributedResults = trueを設定し、複数の座標ポイントがあるGeoCorridorを使用して軌道エリアを作成する必要があります。この機能では並列化を使用しており、次の場合にのみサポートされます。

searchByCategory (CategoryQuery.Area.corridorAreaが指定されている場合)
searchByText (TextQuery.Area.corridorAreaが指定されている場合)

注

distributedResults機能はOfflineSearchEngineでのみ使用可能で、軌道エリアでオフラインマップデータを使用できるようにする必要があります。

void testDistributedResultsWithCorridor() {
    // Create a corridor area for the search - this is required for distributedResults to work
    List<GeoCoordinates> corridorPoints = Arrays.asList(
            new GeoCoordinates(52.520798, 13.409408), // Start point (Berlin)
            new GeoCoordinates(52.518032, 13.420632), // Middle point
            new GeoCoordinates(52.515597, 13.377704), // End point
            new GeoCoordinates(52.512000, 13.390000)  // Additional point for more complex corridor
    );

    CategoryQuery.Area queryArea = new CategoryQuery.Area(new GeoCorridor(corridorPoints), new GeoCoordinates(52.518032, 13.420632));

    List<PlaceCategory> categoryList = new ArrayList<>();
    categoryList.add(new PlaceCategory(PlaceCategory.EAT_AND_DRINK));
    categoryList.add(new PlaceCategory(PlaceCategory.SHOPPING_ELECTRONICS));

    CategoryQuery categoryQuery = new CategoryQuery(categoryList, queryArea);

    SearchOptions searchOptions = new SearchOptions();
    searchOptions.languageCode = LanguageCode.EN_US;
    searchOptions.maxItems = 50;

    searchOptions.distributedResults = true;

    offlineSearchEngine.searchByCategory(categoryQuery, searchOptions, new SearchCallback() {
        @Override
        public void onSearchCompleted(SearchError searchError, List<Place> list) {
            if (searchError != null) {
                // Handle error.
                return;
            }

            // If error is null, list is guaranteed to be not empty.
            String numberOfResults = "Search results: " + list.size() + ". See log for details.";

            for (int i = 0; i < list.size(); i++) {
                Place searchResult = list.get(i);
                String name = searchResult.getTitle();
                String address = searchResult.getAddress().addressText;
                GeoCoordinates coords = searchResult.getGeoCoordinates();

                Log.d("DistributedSearch", String.format(
                        "Result %d/%d: %s at %s (%.6f, %.6f)",
                        i+1, list.size(), name, address, coords.latitude, coords.longitude
                ));
            }
        }
    });
  }

オフライン検索機能

注

注

インデックス作成でオフライン検索を使用する

注

オフラインで独自の場所を使用する

軌道に沿って分散された結果

注

HERE documentation

Documentation

Dynamic map content

Maps & data

Location services

Development enablers

Platform tools

Platform policies

What's new

Platform release notes

Developer blog posts

Videos

HERE ドキュメント

ドキュメント

ダイナミックマップ

地図とデータ

ロケーションサービス

開発支援ツール

プラットフォーム管理

プラットフォームポリシー

最新情報

プラットフォームリリースノート

開発者向けリソース

動画

注

注

インデックス作成でオフライン検索を使用する

注

オフラインで独自の場所を使用する

軌道に沿って分散された結果

注

HERE documentation

Documentation

Dynamic map content

Maps & data

Location services

Development enablers

Platform tools

Platform policies

What's new

Platform release notes

Developer blog posts

Videos

HERE ドキュメント

ドキュメント

ダイナミックマップ

地図とデータ

ロケーションサービス

開発支援ツール

プラットフォーム管理

プラットフォーム ポリシー

最新情報

プラットフォーム リリースノート

開発者向けリソース

動画

プラットフォームポリシー

プラットフォームリリースノート