HERE Android SDK Developer's Guide

Advanced Positioning by HERE

In addition to the basic platform positioning, HERE Android SDK provides advanced HERE Positioning with the following key features:
  • Cellular network positioning in GSM, CDMA, WCDMA, TD-SCDMA and LTE networks
  • Wifi network positioning
  • High accuracy indoor positioning with building and floor detection using wifi and Bluetooth radios
  • Automatic, on-demand download of radio positioning data for positioning without network connection (offline)
    Note: Offline functionality is not supported for CDMA positioning.
  • Automatic positioning method switching between satellite-based (GNSS), wifi, Bluetooth, and cellular network positioning, providing the best possible position information using the available methods.
  • HERE Indoor Positioning supports both private and public data. You can have a private venue that is mapped through HERE Private Venues or your own custom indoor map, with the indoor location information being only available for your applications. In contrast, indoor location information for public venues is available for all HERE SDK users with an appropriate license.
  • Global positioning coverage and data hosting infrastructure for the optimal availability, reliability, and user experience.
Note: Access to the indoor positioning feature is restricted. Please contact a HERE representative (https://developer.here.com/contact-us?interest=mobile-sdk#contact-sales) for more information.

HERE Positioning Feature Groups

HERE Positioning is split into features groups. Depending on your business plan, you may have access to one or more of the following:
  • Online Positioning

    This feature group provides online positioning by sending anonymous network measurements (cellular and wifi) to the HERE Positioning servers to resolve the device location based on the provided measurements. Online positioning offers limited offline positioning capabilities through caching: measurements and resolved positions are stored into a local cache from which they can be later used without network connection.

  • Offline Positioning

    This feature group provides offline network positioning (cellular and wifi) by utilizing downloaded positioning assistance data, i.e. radiomaps, for the position estimation within the device. In this context offline means that network connectivity is only required for the radiomap download after which no connectivity is needed unless further radiomap tiles are needed. This may happen due to the device movement or radiomap expiration.

    Radiomap download is handled by the on-demand downloader, which automatically downloads radiomap tiles in the vicinity of the device. The downloader also handles the maintenance of the radiomaps in the device by updating the radiomap tiles at regular intervals as needed, and by removing the oldest radiomap tiles in case the storage consumed by the radiomap tiles exceed the quota. This quota is defined per technology and is configured as speficied in the table below. The table also defines, how often the HERE Android SDK attempts to update the radiomaps.

  • Public Indoor

    This feature group provides high accuracy indoor positioning for public venues from which indoor radio data (wifi or Bluetooth) has been collected using the HERE Indoor Radio Mapper tool. The feature uses HERE Indoor Positioning community radiomaps that are accessible by all HERE Android SDK users having access to this feature. Further details can be found in the HERE Indoor Positioning Installation Guide.

    Similarly to Offline Positioning, HERE Public Indoor Positioning works in offline mode. The storage quota and the radiomap tile update interval is specified in the table below.

  • Private Indoor

    This feature group provides high accuracy indoor positioning for private venues from which indoor radio data (wifi or Bluetooth) has been collected using the HERE Indoor Radio Mapper tool. In contrast to the Public Indoor feature, the Private Indoor feature provides indoor positioning capability that is accessible only by the owner of the radiomap. Further details can be found in the HERE Indoor Positioning Installation Guide.

    Similarly to the Offline Positioning, also HERE Private Indoor Positioning works in the offline mode. The storage quota and the radiomap tile update interval is specified in the table below.

Table 1. Maximum Storage Consumption and Update Interval Per Technology
Technology Quota Update interval Description
Offline cellular 32MB 23 days Radiomaps for cellular network positioning (all network technologies).
Offline wifi 32MB 23 days Radiomaps for wifi network positioning.
Indoor wifi and Bluetooth 32MB 7 days Radiomaps (private and community) for high accuracy indoor wifi and Bluetooth positioning.

Using HERE Positioning

To start using HERE Positioning in the Android applications, complete the following steps:

  1. Embed the HERE Positioning service in your application
  2. Add the required Android permissions to your application
  3. Set the positioning data source to HERE Positioning and start the Positioning Manager
  4. Receive and handle location updates

In detail, the following actions need to be taken:

1) Embedding the HERE Positioning service

To embed the HERE Positioning service, add the following lines to the <application></application> section in AndroidManifest.xml:

<!-- HERE Positioning Service definition. -->
<service
  android:name="com.here.services.internal.LocationService"
  android:enabled="true"
  android:exported="false"
  android:process=":remote">
</service>

2) Add the Android permissions to your application

Add the following permissions to AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" android:maxSdkVersion="22" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
Note: If your application uses Android target SDK version level 23 or above, you must add code to request permissions at runtime. For more detailed instructions and example code, see Requesting Android Permissions.

3) Change the positioning data source and start PositioningManager

After completing the previous configuration steps, change the Positioning Manager data source to HERE Positioning and start the Positioning Manager with the suitable location method to start receiving HERE Positioning location updates:
m_hereDataSource = LocationDataSourceHERE.getInstance();
if (m_hereDataSource != null) {
  PositioningManager pm = PositioningManager.getInstance();

  pm.setDataSource(m_hereDataSource);
  pm.addListener(new WeakReference<PositioningManager.OnPositionChangedListener>(this));
  if (pm.start(PositioningManager.LocationMethod.GPS_NETWORK_INDOOR)) {
    // Position updates started successfully.
  }
}
For detailed description of the location methods available for the HERE Positioning location data source, please see the section Location Methods.
Note:
  • LocationDataSourceHERE.getInstance() cannot be instantiated if no HERE Positioning features are enabled in the SDK license.
  • You cannot start PositioningManager with a location method containing indoor positioning without first setting location data source to HERE
  • You can only start PositioningManager with a location method that is enabled by your business plan.
  • When using a location method containing indoor positioning, the indoor positioning mode can be controlled. Please see the section Indoor Positioning Mode below for further information.

4) Receive and handle location updates

The location updates are handled by onPositionUpdated() (when the device location changes) and onPositionFixChanged() (when location method changes) methods from OnPositionChangedListener:

@Override public void onPositionUpdated(final PositioningManager.LocationMethod locationMethod, final GeoPosition geoPosition, final boolean mapMatched) {
  // new position update received
}
                  
@Override public void onPositionFixChanged(PositioningManager.LocationMethod locationMethod, PositioningManager.LocationStatus locationStatus) {
  // positioning method changed
}
Note:
  • PositioningManager.OnPositionChangedListener represents an interface for the position update listeners.
  • GeoPosition carries GeoCoordinate that contains the device WGS84 Latitude/Longitude coordinates and altitude with double precision. In addition, GeoPosition carries location uncertainty estimate as well as speed and heading information.
  • For indoor positioning, GeoPosition carries building information (building name and building ID) as well as floor level information.

Location Methods

The Location methods refers to the set of technologies used in the location determination. HERE Positioning supports a plethora of location methods. The following table introduces the location methods that the PositioningManager can be started with, when the location data source is LocationDataSourceHERE.

Table 2. Supported Location Methods
Method Description
GPS Uses the satellite-based positioning (GNSS) as provided by the Android platform.
NETWORK Uses the online or offline wifi or cellular network positioning methods, depending upon the device capabilities, always selecting the best radio technology for location estimation.
INDOOR Uses either wifi or Bluetooth radio to provide indoor location estimates, with building and floor information, always selecting the best radio technology in case both are available.
GPS_NETWORK Uses satellite-based positioning and network positioning, always selecting the best technology for optimal location estimation.
GPS_NETWORK_INDOOR Uses satellite-based positioning, network positioning and indoor positioning, always selecting the best technology for optimal location estimation.

Pre-downloading radiomaps to the device

The RadioMapLoader interface provides a mechanism to pre-download radiomaps surrounding a specified center point to the device. Having pre-downloaded radiomaps to the device, the device can be located without data connectivity. In addition to the center point, the interface needs to be provided with the type of the radiomap to be downloaded. The available types are:

Table 3. Radiomap types available for pre-download
Mode Description
SPARSE Configures the download of the cellular radiomaps for coarse positioning (accuracy hundreds of meters) within 15 kilometers from the center point.
COARSE Configures the download of the cellular radiomaps and the highly compressed wifi radiomaps to balance data consumption and positioning accuracy. Radiomaps are downloaded within 5 km from the center point.
DETAILED Configures the download of the cellular radiomaps and the less compressed wifi radiomaps to favor accuracy over data consumption. Radiomaps are downloaded within one km from the center point.
INDOOR Configures the download of the radiomaps necessary for indoor positioning. Radiomaps are downloaded within 500 m from the center point.

Instead of defining the center point and the radiomap type to the interface, it is also possible to provide the Venue Map information as com.here.android.mpa.venues3d.Venue to the interface. In this case the job downloads the radiomaps necessary for indoor positioning at that particular venue.

The interface also provides a mechanism to delete all the downloaded radiomaps as well as to observe the status and the progress of the download job.

Indoor Positioning Mode

The indoor positioning mode refers to the set of radiomaps used by the indoor positioning engine. For detailed discussion on the different radiomaps, please refer to HERE Indoor Positioning Installation Guide.

Indoor positioning can be configured to run in four different modes, which are defined by the LocationDataSourceHERE.IndoorPositioningMode enumeration. Use the method setIndoorPositioningMode() from the LocationDataSourceHERE class to change the indoor positioning mode. Use the method getIndoorPositioningMode() from the same class to check the current mode.

The following table introduces the four indoor positioning modes.

Table 4. Indoor Positioning Modes Supported by the HERE Positioning
Mode Description
AUTOMATIC HERE Positioning automatically chooses which mode to apply. Requires that the SDK license has both public and private indoor positioning features enabled. If both features are enabled in the SDK license, then this positioning mode is set as the default.
Note: When using the automatic mode, if both public and private indoor positioning are enabled, the private one is always selected.
COMMUNITY Community indoor radiomap is used by the indoor positioning engine. Requires that the SDK license has the public indoor positioning feature enabled. If only the public indoor positioning feature is enabled in the SDK license, then this indoor positioning mode is set as the default.
PRIVATE The customer's private indoor radiomap is used by the indoor positioning engine. Requires that the SDK license has private indoor positioning feature enabled. If only the private indoor positioning feature is enabled in the SDK license, then this indoor positioning mode is set as the default.
DRAFT Mode used for testing the draft indoor radiomap before publishing the draft to production servers. Requires that either public or private indoor feature is enabled in the SDK license. Please see the Using the Draft Indoor Positioning Mode section below for further details.

Using the Draft Indoor Positioning Mode

A Draft Radiomap is a sandbox for the system operators and developers to test and try out positioning without affecting the applications using HERE Indoor Positioning. When radio data is collected and tested in the HERE Indoor Radio Mapper, the tool always uses a Draft Radiomap. Once the Draft Radiomap shows good performance, the radio data is published to the production radiomap (private or public one, depending upon the venue type) for the use by HERE Android SDK.

In the production configuration, HERE Android SDK fetches positioning data from the production radiomaps. However, for R&D purposes, HERE Android SDK can be configured to use a draft radiomap. The DRAFT indoor positioning mode allows testing the unpublished draft indoor radiomap in the actual application (as opposed to testing only in the HERE Indoor Radio Mapper) before publishing the Draft Radiomap to production. However, since this is an R&D feature, this mode is limited to a maximum of ten devices that have to be defined before compiling the application.

For detailed discussion on the radiomaps and data flows, please refer to HERE Indoor Positioning Installation Guide.

To enable the DRAFT indoor positioning mode for a specific device, do the following:

  1. Find out the Android ID of the device that you want to enable the DRAFT indoor positioning mode for.
    1. Run command adb shell getprop | grep net.hostname via the Android debug bridge
    2. Inspect the command output. For example:
      [net.hostname]: [android-1234567812345678]
      The Android ID is what appears after the string "android-".
    3. Please note that the Android ID may change when the device factory settings are returned or when switching the user profile in a device with multi-user support
  2. Add a new XML resource to your project using the Android Studio and name it, for example, as draft_enabled_devices.xml
  3. Add the Android ID to the string-array within resources as follows in draft_enabled_devices.xml:
    <?xml version="1.0" encoding="utf-8"?>
      <resources>
      <string-array name="draft_enabled_devices">
        <!—My Android device -->
        <item>1234567812345678</item>
      </string-array>
    </resources>
    Note: Up to ten Android IDs can be defined in the string-array. If more than ten Android IDs are defined, none of them will work.
  4. Add a new metadata element defining the draft-enabled devices to your AndroidManifest.xml:
    <meta-data android:name="com.here.location.indoor_draft_access" 
                      android:resource="@array/draft_enabled_devices" />
    Note: This field must be added at the same level with the HERE Application ID, Application Code and the SDK License.
    Note: The resource name must match to the string-array name created in the step 3.

Indoor Positioning-specific Methods

HERE Positioning has three indoor positioning-specific methods:

  • String getBuildingName()

    Returns the BuildingName, if known. If the BuildingName is not present, null is returned.

    For HERE Venue Maps the BuildingName is assigned by HERE, when creating the Venue Map. This method returns that name.

    For custom indoor maps, the BuildingName is the one given when the indoor map was imported using HERE Indoor Radio Mapper. However, illegal characters are removed from the name.

  • String getBuildingId()

    Returns the BuildingID, if known. If the BuildingID is not present, null is returned.

    For HERE Venue Maps, the BuildingID is the globally unique ID assigned by HERE, when creating the Venue Map. An example of a HERE Venue Map BuildingID is DM_8213.

    For custom indoor maps, the BuildingID is the customer-defined BuildingName, prefixed with BM_.

    If the position estimate is outdoors, but indoor positioning is used for producing the location estimate, the string OUTDOOR is returned.

  • Integer getFloorId()

    Returns the floor level. If the FloorId is not present, null is returned.

    For HERE Venue Maps, the floor levels are returned as defined for the particular the HERE Venue Map.

    For custom indoor maps, the FloodId follows the customer-defined floor levels specified in HERE Indoor Radio Mapper, when the indoor maps were imported.

Receiving Detailed Status Reports and Diagnostics

Status Listener

StatusListener provides information on the few most typical issues that prevent the usage of HERE Indoor Positioning. An instance of StatusListener is given as an input parameter, when creating an instance of HERE Positioning: LocationDataSourceHERE.getInstance(StatusListener).

The following table details the return codes as defined in StatusListener.PositioningError.
Table 5. Status messages provided by StatusListener
Status message Description
INJECT ERROR Coarse location could not be resolved. HERE Indoor Positioning requires coarse location to retrieve the correct positioning data from the HERE positioning servers.
NO COVERAGE No radiomaps were found in the vicinity of the resolved coarse location. Please ensure you have created indoor positioning coverage with HERE Indoor Radio Mapper and that the data has been published for use.
NOT FOUND HERE Indoor Positioning coverage exists for the area, but resolving position failed. Please make sure that your latest data has been published in HERE Indoor Radio Mapper.

Diagnostics Listener

DiagnosticsListener provides more detailed information on the most typical issues preventing the usage of HERE Indoor Positioning. The diagnostics listener can be set up via the method setDiagnosticsListener.

The following table lists the events that can be received through the DiagnosticsListener.

Table 6. Diagnostics messages provided by DiagnosticsListener
Diagnostics message Category Description
List of the enabled positioning methods info Lists the positioning methods at your disposal.
List of the requested and enabled positioning methods info Lists the requested positioning methods in addition to the allowed positioning methods. In case you are missing a method you would like to use, please contact your HERE representative.
No license to use any of the requested positioning methods error In case none of the requested methods is enabled in your license, positioning cannot be performed. Please use a method allowed by your license.
Dynamic permissions are not set for the application and service cannot be started error Please set the permissions as instructed in Using HERE Positioning
No reference position error The same as INJECT ERROR above.
No coverage error The same as NO COVERAGE above.
Not found error The same as NOT FOUND above.

Device Settings

The device settings may have a major impact on positioning accuracy and may even prevent HERE Positioning from functioning altogether—for example, disabling GPS/GNSS, network location support, or radio technologies prevent HERE Positioning from functioning normally. As a developer you should detect these situations, let the application user know about the situation, and inform the user about the possible corrective action. The following table lists the situations that may impact positioning, and the corrective action for each case.

Table 7. Device Settings and Corrective Actions
Situation Impact Corrective Action
Device Only Location mode is selected from the device location settings. HERE Positioning is not allowed to perform network or indoor positioning. Notify the user about the situation and inform the user to switch the Location mode to High accuracy.
Battery Saving Location mode is selected from the device location settings. HERE Positioning is not able to use satellite-based positioning. Notify the user about the situation and inform the user to switch the Location mode to High accuracy.
Airplane mode is enabled. By default, the airplane mode shuts down device radios preventing either all the network measurements or only cellular measurements, depending on how the user has modified device settings after enabling the airplane mode. Notify the user about the situation. Do not inform the user to turn off the airplane mode without warning, because there might be a valid reason why airplane mode is enabled.
wifi is disabled. Disabling wifi scans prevents wifi-based outdoor and indoor positioning. Notify the user about the situation and inform the user to switch the wifi radio on, or to turn on Scanning always available option from the wifi advanced settings or from the location settings.
Bluetooth is disabled. Disabling Bluetooth prevents Bluetooth-based indoor positioning. Notify the user about the situation and inform the user to switch the Bluetooth radio on, or to turn on Scanning always available option from the Bluetooth advanced setting or from the location settings.

Power Consumption Considerations

HERE Positioning power consumption depends heavily on the used LocationMethod. As a rule of thumb, network (wifi or cellular) positioning consumes less power than GNSS and indoor positioning. If your application does not require the highest possible accuracy, you should consider using network positioning to save energy.

Online network positioning consumes more energy than offline network positioning. In a typical setting offline positioning uses up to 80-90% less energy than online positioning. The difference is mainly because of the network connection usage in online network positioning.

In order to save energy, you should also consider pausing position updates when your application is moved to the background, unless your application is dependent on frequent location updates even when the application is in the background.

Troubleshooting HERE Positioning

If your application does not receive any position updates while using HERE Positioning, try the following:

  • Check that the Android permissions are set as defined in this document
  • Check that the positioning service is correctly defined in the application manifest
  • Make sure that the relevant network settings are enabled:
    • Go to System settings and check that Wifi, Cellular and Bluetooth (if the indoor feature is used) are enabled.
  • Make sure that the device has network connection
  • Check that the high accuracy location settings is enabled:
    • Device-only location setting prevents network and indoor positioning
    • battery-saving location setting prevents GNSS positioning
  • Make sure the indoor positioning mode is correctly set

If your application receives inaccurate position estimates while using HERE Positioning, try the following:

  • Make sure that you have wifi and Bluetooth (for indoor positioning) network measurements enabled
  • Use the best-suited LocationMethod for your applications when requesting location updates
  • Check that the high accuracy location settings is enabled
  • If you are trying to use indoor positioning, make sure that the location estimates really originate from the indoor positioning engine by checking the position source through GetPositionSource on GeoPosition

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.