OfflineSearchEngine

public class OfflineSearchEngine : SearchInterface
extension OfflineSearchEngine: NativeBase
extension OfflineSearchEngine: Hashable

The OfflineSearchEngine works without internet and unlocks the search and geocoding capabilities of HERE services to provide developers with unmatched flexibility to create differentiating location-enabled applications.

It provides the same interfaces as the SearchEngine, but the results may slightly differ as the results are taken from already downloaded map data instead of initiating a new request to a HERE backend service. This way the data may be, for example, older compared to the data you may receive when using the SearchEngine. On the other hand, this class provides results faster as no online connection is necessary.

In comparison to the SearchEngine, there are a few limitations:

  • The IDs of POIs are different and may differ among different map versions.
  • The implementation is different and the resources are limited, so the results can differ.
  • OfflineSearchEngine sometimes doesn’t return the requested number of results.

Note: You can search only within persistent map data (downloaded via MapDownloader) or existing cached data. However, cached data may be incomplete, which can result in searches returning partial or incomplete information. Therefore, it is recommended to use persistent map data. Make sure that at least LayerConfiguration.Feature.offlineSearch is enabled. For EV rich attributes also enable LayerConfiguration.Feature.ev, for truck rich attributes also enable LayerConfiguration.Feature.truckServiceAttributes, for fuel station rich attributes also enable LayerConfiguration.Feature.fuelStationAttributes in SDKOptions.layerConfiguration.

  • Creates a new instance of this class.

    Throws

    InstantiationError Indicates what went wrong when the instantiation was attempted.

    Declaration

    Swift

    public init() throws

  • Creates a new instance of this class.

    Throws

    InstantiationError Indicates what went wrong when the instantiation was attempted.

    Declaration

    Swift

    public init(_ sdkEngine: SDKNativeEngine) throws

    Parameters

    sdkEngine

    Instance of an existing SDKEngine.

  • Performs an asynchronous text query search for Place instances within a given TextQuery.Area. The returned places are sorted by relevance.

    Declaration

    Swift

    @discardableResult
public func searchByText(_ query: TextQuery, options: SearchOptions, completion: @escaping SearchCompletionHandler) -> TaskHandle

    Parameters

    query

    Desired free-form text query to search.
    options

    Search options.
    completion

    Callback which receives the result on the main thread.

    Return Value

    Handle that will be used to manipulate the execution of the task.

  • Performs an asynchronous address query search for Place instances. This is the same type of search as forward geocoding, except that more data is returned than just the geographic coordinates of a given address. Note that an address can belong to more than one Place result, although all found places will share the same geographic coordinates. The returned places are sorted by relevance.

    Declaration

    Swift

    @discardableResult
public func searchByAddress(_ query: AddressQuery, options: SearchOptions, completion: @escaping SearchCompletionHandler) -> TaskHandle

    Parameters

    query

    Desired free-form address query text to search.
    options

    Search options.
    completion

    Callback which receives the result on the main thread.

    Return Value

    Handle that will be used to manipulate the execution of the task.

  • Performs an asynchronous category search for Place instances. A list containing at least one PlaceCategory must be provided as part of the searchByCategory(...).query.

    Declaration

    Swift

    @discardableResult
public func searchByCategory(_ query: CategoryQuery, options: SearchOptions, completion: @escaping SearchCompletionHandler) -> TaskHandle

    Parameters

    query

    Query with list of desired categories.
    options

    Search options.
    completion

    Callback which receives the result on the main thread.

    Return Value

    Handle that will be used to manipulate the execution of the task.

  • Performs an asynchronous search for Place instances based on the given geographic coordinates. This is the same search type as reverse geocoding, except that more data is returned than just the Address related to the given coordinates. Note that more than one Place can be related to the given coordinates. The returned places are sorted by relevance.

    Declaration

    Swift

    @discardableResult
public func searchByCoordinates(_ coordinates: GeoCoordinates, options: SearchOptions, completion: @escaping SearchCompletionHandler) -> TaskHandle

    Parameters

    coordinates

    The coordinates where to search.
    options

    Search options.
    completion

    Callback which receives result on the main thread.

    Return Value

    Handle that will be used to manipulate execution of the task.

  • Performs an asynchronous search for a Place based on its ID and LanguageCode.

    Declaration

    Swift

    @discardableResult
public func searchByPlaceId(_ query: PlaceIdQuery, languageCode: LanguageCode?, completion: @escaping PlaceIdSearchCompletionHandler) -> TaskHandle

    Parameters

    query

    The id of place to search.
    languageCode

    The preferred language for the search results. When unset or unsupported language is chosen, results will be returned in their local language.
    completion

    Callback which receives the result on the main thread.

    Return Value

    Handle that will be used to manipulate the execution of the task.

  • Performs an asynchronous search for a Place based on the content found in PickedPlace. If PickedPlace data is obtained from the offline map, it may happen that the newer version that is used by the online service represented by SearchEngine no longer contains the related POI. In that case, SearchError.noResultsFound error is reported. When that happens, you may try to obtain the POI from the offline map by calling OfflineSearchEngine.searchByPickedPlace, only available for the Navigate license.

    Declaration

    Swift

    @discardableResult
public func searchByPickedPlace(_ pickedPlace: PickedPlace, languageCode: LanguageCode?, completion: @escaping PlaceIdSearchCompletionHandler) -> TaskHandle

    Parameters

    pickedPlace

    The content picked from map.
    languageCode

    The preferred language for the search result. When unset or unsupported language is chosen, result will be returned in the local language.
    completion

    Callback which receives the result on the main thread.

    Return Value

    Handle that will be used to manipulate the execution of the task.

  • Performs an asynchronous request to suggest places for text queries and returns suggestions sorted by relevance.

    Note that while OfflineSearchEngine includes as many details as are available, SearchEngine includes only the information that is relevant for autosuggest use cases. Complete details can be obtained by searching with PlaceIdQuery.

    Declaration

    Swift

    @discardableResult
public func suggestByText(_ query: TextQuery, options: SearchOptions, completion: @escaping SuggestCompletionHandler) -> TaskHandle

    Parameters

    query

    Desired text query to search.
    options

    Search options.
    completion

    Callback which receives the result on the main thread.

    Return Value

    Handle that will be used to manipulate the execution of the task.

  • Attach data source into SearchEngine instance. Places from MyPlaces ranked the same way as places from default source. New data source replaces old one. Note: Only OfflineSearchEngine supports search over MyPlaces.

    Declaration

    Swift

    public func attach(dataSource: MyPlaces, callback: @escaping TaskCompletionHandler) -> TaskHandle

    Parameters

    dataSource

    The data source.
    callback

    The callback to be called when task is completed.

    Return Value

    Handle that will be used to manipulate the execution of the task.

  • Performs an asynchronous request to search for places. The user submits a StructuredQuery that returns places adhering to the constraints provided in StructuredQuery. For example, when user wants results of type street for a text query Invalidenstraße in Berlin, it can be searched by preparing StructuredQuery providing StructuredQuery.query as Invalidenstraße, StructuredQuery.areaCenter, StructuredQuery.AddressElements.country as Germany, StructuredQuery.AddressElements.city as Berlin and StructuredQuery.ResultType as STREET. The results will be presented only from the given geographical area.

    Note: This is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

    Declaration

    Swift

    @discardableResult
public func search(structQuery query: StructuredQuery, options: SearchOptions, completion: @escaping SearchCompletionHandler) -> TaskHandle

    Parameters

    query

    Desired structured query to search.
    options

    Search options.
    completion

    Callback which receives the result on the main thread.

    Return Value

    Handle that will be used to manipulate the execution of the task.

  • Performs an asynchronous request to suggest places for a StructuredQuery built with address elements and returns candidate suggestions sorted by relevance. For example, when user wants suggestions of type street for a text query Invalidenstraße in Berlin, it can be searched by preparing StructuredQuery providing StructuredQuery.query as Invalidenstraße, StructuredQuery.areaCenter, StructuredQuery.AddressElements.country as Germany, StructuredQuery.AddressElements.city as Berlin and StructuredQuery.ResultType as STREET. The suggestions will be presented only from the given geographical area.

    Note: This is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

    Declaration

    Swift

    @discardableResult
public func suggest(structQuery query: StructuredQuery, options: SearchOptions, completion: @escaping SuggestCompletionHandler) -> TaskHandle

    Parameters

    query

    Desired structured query to search.
    options

    Search options.
    completion

    Callback which receives the result on the main thread.

    Return Value

    Handle that will be used to manipulate the execution of the task.

  • Enables or disables indexing. When indexing is enabled, HERE SDK will create a detailed index over persistent map data and update it as needed. A detailed index enables finding data faster and over entire persistent map. Creating an index takes time, but usually no more than a few seconds up to a couple of minutes, depending on persistent map size. As the feature is improved, the indexing time will improve. Also please note that this is a heavy processing task. The stored index increases the space taken by offline maps by around 2-5%. This may also improve in future versions.

    Indexing is disabled by default. If you want it enabled, make sure to call setIndexOptions with OfflineSearchIndex.Options.enabled as true before any operations in MapDownloader or MapUpdater that modify the persistent map. Calling setIndexOptions may also create or remove map index to match the previously installed map regions. If the matching index for installed map regions is found, then indexing is skipped. While a new index is being created, OfflineSearchEngine functionality can still be used. However, without a valid index in place yet, it operates as though indexing is disabled. If SDKNativeEngine is disposed during indexing (for example, by closing the app), the indexing is cancelled. Recreating SDKNativeEngine and enabling indexing will ensure that index is created.

    Note: This is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

    Declaration

    Swift

    public static func setIndexOptions(sdkEngine: SDKNativeEngine, options: OfflineSearchIndex.Options, listener: OfflineSearchIndexListener) -> OfflineSearchIndex.Error?

    Parameters

    sdkEngine

    Indexing is enabled and disabled per SDKNativeEngine instance. The index is created inside the related SDKOptions.persistentMapStoragePath.
    options

    Sets indexing options.
    listener

    The listener that will receive updates about indexing process. When OfflineSearchIndex.Options.enabled is true, SDK would store listener and the listener will receive updates about indexing progress every time it is performed. When OfflineSearchIndex.Options.enabled is false, SDK would report indexing removal progress to the listener one last time and remove storage of listener.

    Return Value

    An error in case there was one. It’s nil if the indexing listener could be configured successfully.