Using AirVantage APIs to Update Device Location

Most Sierra Wireless AirLink gateways and routers come with GPS and can report their location to ALMS. In some cases, customers’ devices either do not have a GPS module, they have not attached a GPS antenna, or the device is installed indoors in a location where the antenna cannot see the sky and receive the GPS signal. In these situations, customers may wish to import a fixed location for these devices into ALMS so the devices can be shown on a map, or leverage other ALMS location features.

Any ALMS user familiar with using AirVantage APIs with ALMS can use the APIs to update the location of their devices in ALMS. This page provides an overview of the process.

Initializing Table Of Contents...

Prerequisites

There are six prerequisites for starting this process.

• Download and install Postman
  • This is the recommended tool for running the API calls, and the files provided have been tested with this product. You are free to use any similar application.
    • Download: https://www.getpostman.com/products
    • Documentation: https://www.getpostman.com/docs/v6/
      
      
• Obtain your ALMS account UID
  • The UID appears on the main screen of the “My Account” section
    
• Generate a list of device serial numbers
  
  
• Define the locations in Lat/Long format for each serial number
  • The serial numbers and lat/longs will be populated in import-location.csv [download, 1 KB].
    
    
• Obtain a current access token to AirVantage
  • To obtain a current access token, go to https://doc.airvantage.net/av/reference/cloud/API/ and review the Authentication section.
    
    
• Disable Location Services on the Gateway Configuration
  • If you do not have an antenna installed on the gateway, be sure to disable Location Services in your device configuration. Any GPS coordinates that are sent from the gateway will overwrite the value you have uploaded. If Location Services are enabled, the gateway will send 0,0 if it cannot get an actual location fix.
    

Instructions

1. Populate import-location.csv with your ALMS access token, account UI, the serial numbers and locations of the gateways that require a location.
   
2. Right-click to download (Save link as…) the ImportLocations.postman_collection.json collection and then import it into Postman — (click Import).
   
3. Open the collection runner — (click Runner).
   
4. Select the collection.
   
   
5. Attach the prepared CSV file.
   
   
6. Set the iteration to equal the number of rows to import (“1” for 1 gateway, “2” for 2 gateways, “100” for 100 gateways etc.).
   
   
7. Run the collection.

Troubleshooting

Location Formats: The GPS coordinates must be in a lat/long file format following the degree decimals convention. Longitude must be between -180 and 180 and latitude between -90 and 90.

Errors in the API Call: Cannot read property 0 of undefined — the system query API failed. This is a very simple API that is called first for each system; the error either means the system (serial number specified in the csv) doesn’t exist in your account or you have a bad access token.