Introduction to the Device Location API

The Device Location API lets you retrieve the current or cached location of IoT devices in an account. The APIs can be used with Open Development certified IoT devices (i.e. routers, modems, vending machines with embedded modules, etc). These APIs cannot be used to locate non-IoT devices such as Smartphones, Feature Phones, Tablets, Laptops and Netbooks. It is very important that only devices certified to work with precise location are used for precise location. Your account manager or support contact can help you with a list of certified devices.

The accuracy of a reported location is dependent on a number of factors including the cell site power level, antenna beam width, cell density and GPS availability. The cell density has the greatest effect in urban areas, where you will see more accurate locations since cell density is high relative to rural areas. Rural areas will rely more on GPS signal for accuracy.

Knowing the location of devices on the network is important in many applications, including Retail/Vending, Banking/ATM, Asset Tracking, Fleet Management, Telematics, Healthcare/Fitness/Lifestyle, Smart Grid, Government/Public Safety, Smart Home, and more. Location data can be used in:

  • Tracking fixed assets for integrity (e.g., to ensure assets are where they are supposed to be).
  • Periodic tracking of mobile assets.
    • A fleet management company may need to monitor a fleet of moving trucks on an hourly (or “n”) basis on a nationwide map where approximate location is sufficient.
    • Another company in the delivery logistics space may need to track the precise (10 meter accuracy) location of their delivery trucks within a small city.
  •  Geo-fencing for asset protection tracking or for alerting/notification features.
    • A construction company may want to track some short-term leased
      GPS-equipped equipment operating on a site. They can create a geo-fence
      to trigger an alert if the boundaries of the site are crossed.
    • A delivery company may want to send an email/SMS to a customer when the delivery truck is within a certain distance of the customer’s premises

Current or Cached Locations

The Device Location Service can be set to automatically track device locations on an on-going basis. When you first request a device’s current location, the system locates the device and returns the location and it stores the location information in a cache. After that, you can request either the device’s current location (which will also update the information in the cache) or the device’s cached location. The response includes the time that the location was reported, so you can tell how current any cached location information is.

The device location request has an option to request a device’s cached location or the current location if there is no cached location information

Synchronous or Asynchronous Requests

The API includes a synchronous request that you can use to obtain the locations of up to 20 devices at a time (Using the consent of “Coarse Only Allowed”). To find the locations of more devices, use the asynchronous request to create a device location report and then retrieve the report when it is ready. (If the request is for cached device location information, the report will be ready immediately). An asynchronous request can also provide device location reports for “Precise Only Allowed” (current location, motion or periodic location) or used for mixed consent (coarse and precise allowed) to determine current or cached location.

Your device management system can send regular requests to create device location reports and then receive callback messages when the reports are ready, or it can poll to check the status of reports

Location Service Subscriptions

The ThingSpace Device Location service is a subscription-based service, which means that an account must be signed up to use the service or any API requests will return an error. There are two types of subscriptions:

  • Monthly Recurring Charge (MRC) billing: A pre-pay plan for a specified number of licenses for location searches per month. Any searches in excess of the subscription amount will be charged as event-based billing.
  • Event-based billing: A post-pay plan in which the account is billed for the number of searches that were run during the billing cycle.

A search for a device’s current (not cached) location uses one license, or is counted as one event. This is true even if the device can’t be located (i.e. the device has been powered off). License usage and billing events are counted by device, not by request. A single request to get the location of 10 devices uses 10 licenses or counts as 10 billing events, not just 1.

The number of location searches used by an account is reconciled with the billing system once per day.

Note: requests for the cached location of devices are “free” – they do not use a subscription license in MRC billing or count as billable events in event-based billing

To get started

You can follow these general steps to get started with the Device Location API:

  1. Read the documentation to understand what capabilities are available in the API.
  2. Register on the ThingSpace Develop site to get access to the API.
  3. Sign up for Connectivity Management login credentials.
  4. Once you have both a ThingSpace account and a Connectivity Management account, try the API requests in the API Console, and then start coding your own application.