Migration Guide

The HERE Network Positioning API allows you to build applications that require location estimates based on radio network measurement data. The supported measurement data includes 2G, 3G, 4G, and WLAN measurements, as well as narrow band IoT measurements. This upgraded API supersedes the HERE Network Positioning API v1. This guide assists you in seamlessly transitioning from the previous version to the HERE Network Positioning API v2, ensuring the continued operation of your location-based applications.

Changes overview

The following steps provide a high-level overview of the actions that you must perform to successfully complete the migration.

1. Confirm that you are utilizing API credentials associated with your HERE platform account.
2. Adjust or switch the authentication method as needed.
3. Revise request parameters and JSON body properties to align with the HERE Network Positioning API v2.
4. Remove any parameters and JSON properties that are no longer supported.
5. Switch to the new service URL.

The following sections provide a detailed description of the changes you must account for when migrating to HERE Network Positioning API v2:

Service URL

The HERE Network Positioning API v2 service is available on the new URL: https://positioning.hereapi.com/v2/.

Old URLs used to access HERE Network Positioning API v2 cannot be used to access new version.

Query parameters

Query parameters app_id and app_code are not supported in HERE Network Positioning API v2. The new version supports authentication using apiKey or bearer token.

📘

Note

For more detailed information on HERE account setup, project creation, service linking, app registration, and authentication, see the Identity & Access Management Guide.

The query parameter "dry_run" has been replaced with dryRun.

Request JSON body parameters

Renamed parameters

Following JSON property names have been replaced with new names, as shown in the following table:

Moved parameters

Dependent parameters (such that require presence of each other) have been combined as sub-objects:

Examples

HERE Network Positioning API v1:

{
  "gsm": [{
    "mcc": 262, "mnc": 2, "lac": 3, "cid": 4,
    "nmr": [
      { 
        "bsic": 6, "pcch": 82, 
        "lac": 5, "cid": 6 
      },
    ]
  }],
  "cdma": [{
    "sid": 4162, "nid":10, "bsid":8583,
    "pnoffset": 10, "channel": 200
  }]
}

HERE Network Positioning API v2:

{
  "gsm": [{
    "mcc": 262, "mnc": 2, "lac": 3, "cid": 4,
    "nmr": [
      { 
        "bsic": 6, "pcch": 82, 
        "globalIdentity": { 
          "lac": 5, "cid": 6
        } 
      }
    ]
  }],
  "cdma": [{
    "sid": 4162, "nid":10, "bsid": 8583,
    "localId": { "pnOffset": 10, "channel": 200 }
  }]
}

New cellular technologies

The HERE Network Positioning API v2 supports positioning requests with two more cellular technologies: LTE Cat-M and NB-IoT, see new request body elements lteCatM and nbIot respectively in the API Reference.

Response JSON body parameters

Success response

Following changes have been made in the format of successful positioning request:

• The property "altaccuracy" of location element has been renamed as altAccuracy.
• The type of altitude (alt) and vertical accuracy (altAccuracy) properties in the location element has been changed to number (earlier integer).

Error response

The format of error responses has been changed to provide more information on the issue and possible mitigations. Please refer to the API reference for details.

Next steps

For more information on the HERE Network Positioning API v2, see the following resources:

• Developer Guide
• API Reference
• Changelog