Introduction to the Device Location API

The Device Location API lets you retrieve the current or cached location of IoT devices in an account. You can use the API with all Open Development certified IoT devices, for example routers, modems, vending machines with embedded modules, etc. You cannot use the API to locate non-IoT devices such as Smartphones, Feature Phones, Tablets, Laptops and Netbooks.

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

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. (Precise location is not yet supported.)
• 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.

Note that you can only use the Device Location service to locate IoT/M2M devices; you cannot used it to locate phones or tablets.

Current or Cached Locations

The Device Location Service does not 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. 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.)

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:

• Montlhy 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) coarse location uses one license, or is counted as one event. This is true even if the device can’t be located, such as if 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 count 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 that 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.