オフライン検索機能

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

do {
    // Allows to search on already downloaded or cached map data.
    try offlineSearchEngine = OfflineSearchEngine()
} catch let engineInstantiationError {
    fatalError("Failed to initialize OfflineSearchEngine. Cause: \(engineInstantiationError)")
}

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

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

注

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

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

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

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

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

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

if isDeviceConnected {
    _ = searchEngine.searchByText(textQuery,
                            options: searchOptions,
                            completion: onSearchCompleted)
} else {
    _ = offlineSearchEngine.searchByText(textQuery,
                                   options: searchOptions,
                                   completion: onSearchCompleted)
}

検索結果を処理するには、(上記のように) 同じ onSearchCompleted ハンドラーを設定します。

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

if isDeviceConnected {
    _ = searchEngine.searchByCoordinates(geoCoordinates,
                            options: reverseGeocodingOptions,
                            completion: onReverseGeocodingCompleted)
} else {
    _ = offlineSearchEngine.searchByCoordinates(geoCoordinates,
                                   options: reverseGeocodingOptions,
                                   completion: onReverseGeocodingCompleted)
}

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

if isDeviceConnected {
    _ = searchEngine.searchByAddress(query,
                            options: geocodingOptions,
                            completion: onGeocodingCompleted)
} else {
    _ = offlineSearchEngine.searchByAddress(query,
                                   options: geocodingOptions,
                                   completion: onGeocodingCompleted)
}

デバイスの接続を確認できる解決策は、最初に実際の接続を試みて実装することができます。これに失敗した場合は、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を実装してインデックス作成プロセスをモニタリングする方法を示します。

func enableOfflineSearchIndexing(sdkNativeEngine: SDKNativeEngine) {
    var offlineSearchIndexOptions = OfflineSearchIndex.Options()
    offlineSearchIndexOptions.enabled = true

    offlineSearchIndexListener = OfflineSearchIndexListenerImpl()

    let error = OfflineSearchEngine.setIndexOptions(sdkEngine: sdkNativeEngine,
                                                    options: offlineSearchIndexOptions,
                                                    listener: offlineSearchIndexListener)
    if let error = error {
        print("Failed to set index options: \(error)")
        showMessage("Failed to set index options: \(error)")
    }
}

class OfflineSearchIndexListenerImpl: OfflineSearchIndexListener {

    func onStarted(operation: OfflineSearchIndex.Operation) {
        print("Indexing started. Operation: \(operation)")
    }

    func onProgress(percentage: Int32) {
        print("Indexing progress: \(percentage)%")
    }

    func onComplete(error: OfflineSearchIndex.Error?) {
        if let error = error {
            print("Indexing failed: \(error)")
        } else {
            print("Indexing completed successfully.")
        }
    }
}

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

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

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

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

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

let geoPlaces = [
    GeoPlace.makeMyPlace(title: "Pizza Pino", coordinates: GeoCoordinates(latitude: 52.518032, longitude: 13.420632)),
    GeoPlace.makeMyPlace(title: "PVR mdh", coordinates: GeoCoordinates(latitude: 52.51772, longitude: 13.42038)),
    GeoPlace.makeMyPlace(title: "Harley's bar", coordinates: GeoCoordinates(latitude: 52.51764, longitude: 13.42062))
]

myPlaces.addPlaces(places: geoPlaces) { taskOutcome in
    if (taskOutcome == TaskOutcome.completed) {
      // Task completed.
    } else {
      // Task cancelled.
    }
}

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

offlineSearchEngine.attach(dataSource: myPlaces) { taskOutcome in
    if (taskOutcome == TaskOutcome.completed) {
      // Task completed.
    } else {
      // Task cancelled.
    }
}

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

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

let queryArea = TextQuery.Area(inCircle: GeoCircle(center: GeoCoordinates(latitude: 52.518032, longitude: 13.420632),
                                                   radiusInMeters: 100.0))
let textQuery = TextQuery("Pizza Pino", area: queryArea)
offlineSearchEngine.searchByText(textQuery: textQuery, options: SearchOptions()) { (searchError, placeList) in
    // ...
}

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

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

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

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

注

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

public func testDistributedResultsWithCorridor() {
    let categoryList = [PlaceCategory(id: PlaceCategory.eatAndDrink),
                        PlaceCategory(id: PlaceCategory.shoppingElectronics)]

    // Create a corridor area for the search - this is required for distributedResults to work
    let corridorPoints = [GeoCoordinates(latitude: 52.520798, longitude: 13.409408), // Start point (Berlin)
                          GeoCoordinates(latitude: 52.518032, longitude: 13.420632), // Middle point
                          GeoCoordinates(latitude: 52.515597, longitude: 13.377704), // End point
                          GeoCoordinates(latitude: 52.512000, longitude: 13.390000)] // Additional point for more complex corridor

    let queryArea = CategoryQuery.Area(
        inCorridor: GeoCorridor(polyline: corridorPoints),
        near: GeoCoordinates(latitude: 52.518032, longitude: 13.420632)
    )

    let categoryQuery = CategoryQuery(categoryList, area: queryArea)

    var searchOptions = SearchOptions(languageCode: LanguageCode.enUs, maxItems: 50, distributedResults: true)

    _ = offlineSearchEngine.searchByCategory(categoryQuery, options: searchOptions, completion: onDistributedSearchCompleted)
}

public func onDistributedSearchCompleted(error: SearchError?, items: [Place]?) {
    if let searchError = error {
        print("Search Error: \(searchError)")
        return
    }

    for (index, searchResult) in items!.enumerated() {
        let name = searchResult.title
        let address = searchResult.address.addressText
        let coords = searchResult.geoCoordinates

        print(String(
            format: "Result %d/%d: %@ at %@ (%.6f, %.6f)",
            index + 1, items!.count, name, address,
            coords!.latitude, coords!.longitude
        ))
    }
}