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:
Note that you can only use the Device Location service to locate IoT/M2M devices; you cannot used it to locate phones or tablets.
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.
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.
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:
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.
You can follow these general steps to get started with the Device Location API: