location.publish

The location.publish command is used to publish the location of a Thing.

TR50 Request - with network parameters (MNC/MCC/LAC/CID)
{
  "1" : {
    "command" : "location.publish",
    "params" : {
      "thingKey" : "myThing",
      "mnc": 3,
      "mcc": 310,
      "lac": 34775,
      "cellId": 36352,
      "rssi": -80,
      "imei": "357805023984941",
      "decodeAddress": true
    }
  }
}
TR50 Request with network parameters (MCC/MNC/CELLS)
 { 
   "cmd":{ 
      "command":"location.publish",
      "params":{ 
        "thingKey" : "myThing",
         "mnc":260,
         "mcc":310,
         "imei":"357805023984941",
         "cells":[ 
            { 
               "cellId":36352,
               "lac":34775,
               "rssi":-94
            },
            { 
               "cellId":44473,
               "lac":51051,
               "rssi":-70
            }
         ],
         "decodeAddress":false
      }
   }
}
TR50 Request with network parameters 1 Cell and 1 Wifi (MCC/MNC/CID/WIFI)
 { 
   "cmd":{ 
      "command":"location.publish",
      "params":{ 
         "thingKey" : "myThing",
         "mnc":410,
         "mcc":310,
         "lac":7033,
         "cellId":17811,
         "rssi":-80,
         "wifi":[ 
            { 
               "bssid":"00:17:c5:cd:ca:aa",
               "channel":11,
               "frequency":2412,
               "signal":-51
            },
            { 
               "bssid":"d8:97:ba:c2:f0:5a"
            }
         ],
         "imei":"357805023984942",
         "decodeAddress":false
      }
   }
}
TR50 Request with LAT/LNG
{
  "cmd": {
    "command": "location.publish",
    "params": {
      "thingKey": "myThing",
      "lat": 26.394056,
      "lng": -80.11554,
      "heading": 90,
      "altitude": 100,
      "speed": 45,
      "fixAcc": 8,
      "fixType": "gps",
      "ts": "2014-04-05T02:03:04.322Z",
      "corrId": "mycorrid",
      "streetNumber": "1600",
      "street": "Pennsylvania Ave NW",
      "city": "Washington ",
      "state": "DC",
      "zipCode": "20500",
      "country": "US"
    }
  }
}

Although the address can be specified, it is not the authoritative value. It is only used for display purposes. The latitude and longitude will be reverse geolocated for the address, and any address information provided will take precedence in the displayed address.

Request Parameters

Name Type Required Description
thingKey String Yes* Key of the thing.
esn String ESN of the thing.
iccid String ICCID of the thing.
imei String IMEI of the thing.
imsi String IMSI of the thing.
meid String MEID of the thing.
msisdn String MSISDN of the thing.
*One of the above parameters is required to identify the thing.
Network Parameters
mnc Integer Yes Mobile network code.
mcc Integer Yes Mobile country code.
lac Integer Yes+

 

 

Location area code.
cellId Integer An integer representing the identifier of the Base transceiver station.
rssi Integer Received signal strength indicator.
cells Array An array of cell objects that contain a 'lac', 'cellId', and 'rssi' (See Cell Objects below)
wifi Array No An array of wifi objects (See Wifi Objects below)
imei String No An string representing the unique identifier of the mobile device.
decodeAddress Boolean No The flag requesting the address to be decoded. Defaults to false. If this parameter is true, it will override a thing definition's noDecode setting (see thing_def.create) for the single instance of the command.
+ 'cells' or a combination of 'lac', 'cellId', and 'rssi' are required. If 'cells' is used, any 'lac', 'cellId' or 'rssi' that are not in cells will be ignored.
GPS/GNSS/Manual/M2M Locate
lat Float Yes The latitude for this location publish.
lng Float Yes The longitude for this location publish.
heading Integer   The direction for this location publish.
altitude Integer   The altitude for this location publish.
speed Integer   The speed for this location publish.
fixAcc Integer   The accuracy in meters of the coordinates being published.
fixType String   A string describing the location fixation type. Typically gps , gnss , manual , or m2m-locate .

gps - Location information using the GPS

gnss - Location information based on Global Navigation Satellite System (GNSS)

manual - Location entered manually

m2m-locate - A location-based service (LBS) which provides Telit cellular module users an additional means of obtaining a geo-location fix (latitude-longitude). The service derives device position from a triangulation process which uses cellular base-stations as references. Particularly useful when GNSS signals are either masked or jammed outdoors; or where GNSS signal strength is too weak to provide a reliable position such as in many indoor situations

ts Timestamp   The timestamp for which the location data is being published.
corrId String   A correlation ID that can be used when querying to find related data objects.
debounce Integer   The debounce value is a number (in meters) used to determine if the location publish should be suppressed to avoid drifting in a small area due to inaccuracies in the location provider. The default value is 50 meters if this is not specified, indicating that if the location published is less than 50 meters from the previous location, then it will be ignored. Set to 0 to disable debouncing.
streetNumber String   The number of the building on the street. This field can be left empty and the value pre-pended in the street field.
street String   The street portion of the address.
city String   The city portion of the address.
state String   The state or province (full name or code) of the address.
zipCode String   The zip code (or postal code) of the address.
country String   The country (or country code) of the address.
Wifi Objects
bssid String Yes Basic Service Set Identifier or MAC address of the Access Point. Typical format of a MAC address is xx-xx-xx-xx-xx-xx. However, the delimiter can be any of these when sent to the API: ':' or '-' or '.'
channel Integer No Channel the WiFi network is operating in
frequency Integer No Frequency the WiFi network is operating in (MHz)
rssi Integer No Signal Strength (RSSI)
snr Integer No The current signal to noise ratio, measured in dB
Cell Objects
cellId Integer Yes An integer representing the identifier of the Base transceiver station.
lac Integer Yes An integer representing the code of the location area.
mnc Integer No An integer representing the mobile network code.
mcc Integer No An integer representing the mobile country code.
psc Integer No Primary scramble code
rssi Integer No Signal Strength (RSSI)
ta Integer No Timing advance.

If the command is sent successfully a success message is returned. Otherwise, an error and error message will be returned.

TR50 Response
{
  "cmd": {
    "success": true
  }
}

C API

// basic API
int tr50_location_publish(void *tr50, const double lat, const double lng);
 
// extended API
int tr50_location_publish_ex(void *tr50, const double lat, const double lng, void* optional_params, void** optional_reply, char** error_msg);

JAVA API

// Synchronous
int publish(String thingKey, String timestamp, String corrId, Double lat, Double lng, Double heading, Double altitude, Double speed, Double fixAcc, String fixType, Object response);
 
// Asynchronous
int publish(String thingKey, String timestamp, String corrId, Double lat, Double lng, Double heading, Double altitude, Double speed, Double fixAcc, String fixType, DwOpenReceiveActionListener recv, Object response); 

Response Objects:  StringReplyDwOpenResponse

PHP API

bool TR50httpWorker::locationPublish($thingKey, $lat, $lng[, $ts[, $heading[, $altitude[, $speed[, $fixAcc[, $fixType[, $corrId]]]]]]]);

Related topics