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. Heading is denoted by degrees from 0-360. Use of heading in the location.publish call helps to visually indicate on Portal maps in which direction the object is moving.
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: StringReply, DwOpenResponse

PHP API

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

location.publish

C API

JAVA API

PHP API

Related topics