Package com.here.sdk.search

Class OfflineSearchEngine

java.lang.Object
com.here.NativeBase
com.here.sdk.search.OfflineSearchEngine
All Implemented Interfaces:
SearchInterface
public final class OfflineSearchEngine extends NativeBase implements SearchInterface

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.OFFLINE_SEARCH is enabled. For EV rich attributes also enable LayerConfiguration.Feature.EV, for truck rich attributes also enable LayerConfiguration.Feature.TRUCK_SERVICE_ATTRIBUTES, for fuel station rich attributes also enable LayerConfiguration.Feature.FUEL_STATION_ATTRIBUTES in SDKOptions.layerConfiguration.

  • Constructor Details

  • Method Details

    • attach

      @NonNull public TaskHandle attach(@NonNull MyPlaces dataSource, @NonNull OnTaskCompleted callback)

      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.

      Parameters:
      dataSource -

      The data source.

      callback -

      The callback to be called when task is completed.

      Returns:

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

    • search

      @NonNull public TaskHandle search(@NonNull StructuredQuery query, @NonNull SearchOptions options, @NonNull SearchCallback callback)

      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.

      Parameters:
      query -

      Desired structured query to search.

      options -

      Search options.

      callback -

      Callback which receives the result on the main thread.

      Returns:

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

    • suggest

      @NonNull public TaskHandle suggest(@NonNull StructuredQuery query, @NonNull SearchOptions options, @NonNull SuggestCallback callback)

      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.

      Parameters:
      query -

      Desired structured query to search.

      options -

      Search options.

      callback -

      Callback which receives the result on the main thread.

      Returns:

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

    • setIndexOptions

      @Nullable public static OfflineSearchIndex.Error setIndexOptions(@NonNull SDKNativeEngine sdkEngine, @NonNull OfflineSearchIndex.Options options, @NonNull OfflineSearchIndexListener listener)

      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.

      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.

      Returns:

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

    • searchByText

      @NonNull public TaskHandle searchByText(@NonNull TextQuery query, @NonNull SearchOptions options, @NonNull SearchCallback callback)

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

      Specified by:
      searchByText in interface SearchInterface
      Parameters:
      query -

      Desired free-form text query to search.

      options -

      Search options.

      callback -

      Callback which receives the result on the main thread.

      Returns:

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

    • searchByAddress

      @NonNull public TaskHandle searchByAddress(@NonNull AddressQuery query, @NonNull SearchOptions options, @NonNull SearchCallback callback)

      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.

      Specified by:
      searchByAddress in interface SearchInterface
      Parameters:
      query -

      Desired free-form address query text to search.

      options -

      Search options.

      callback -

      Callback which receives the result on the main thread.

      Returns:

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

    • searchByCategory

      @NonNull public TaskHandle searchByCategory(@NonNull CategoryQuery query, @NonNull SearchOptions options, @NonNull SearchCallback callback)

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

      Specified by:
      searchByCategory in interface SearchInterface
      Parameters:
      query -

      Query with list of desired categories.

      options -

      Search options.

      callback -

      Callback which receives the result on the main thread.

      Returns:

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

    • searchByCoordinates

      @NonNull public TaskHandle searchByCoordinates(@NonNull GeoCoordinates coordinates, @NonNull SearchOptions options, @NonNull SearchCallback callback)

      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.

      Specified by:
      searchByCoordinates in interface SearchInterface
      Parameters:
      coordinates -

      The coordinates where to search.

      options -

      Search options.

      callback -

      Callback which receives result on the main thread.

      Returns:

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

    • searchByPlaceId

      @NonNull public TaskHandle searchByPlaceId(@NonNull PlaceIdQuery query, @Nullable LanguageCode languageCode, @NonNull PlaceIdSearchCallback callback)

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

      Specified by:
      searchByPlaceId in interface SearchInterface
      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.

      callback -

      Callback which receives the result on the main thread.

      Returns:

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

    • searchByPickedPlace

      @NonNull public TaskHandle searchByPickedPlace(@NonNull PickedPlace pickedPlace, @Nullable LanguageCode languageCode, @NonNull PlaceIdSearchCallback callback)

      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.NO_RESULTS_FOUND 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.

      Specified by:
      searchByPickedPlace in interface SearchInterface
      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.

      callback -

      Callback which receives the result on the main thread.

      Returns:

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

    • suggestByText

      @NonNull public TaskHandle suggestByText(@NonNull TextQuery query, @NonNull SearchOptions options, @NonNull SuggestCallback callback)

      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.

      Specified by:
      suggestByText in interface SearchInterface
      Parameters:
      query -

      Desired text query to search.

      options -

      Search options.

      callback -

      Callback which receives the result on the main thread.

      Returns:

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