thing.list

The thing.list command is used to find and return a list of things.

Initial TR50 Request with useSearch and iterator

The following example shows a request using useSearch and iterator parameter:

{
  "cmd": {
    "command": "thing.list",
    "params": {
      "useSearch": true,
      "iterator": "new",
      "limit": "50"
    }
  }
}

TR50 Response gets the iterator value

When the initial request is made, the parameter iterator should be assigned new. The returned result will then include an additional parameter of iterator containing a temporary unique value related to the initial query made. Example response for the above request:

{
  "cmd": {
    "success": true,
    "params": {
      "count": 100,
       "fields": [
	{list of field keys} 
	], 
       "iterator": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAADZtEFkFKQmlqRHZWUk5hb1ZHalRua1RKeEEAAAAAABErWxZjR3ZfNzZpbFJPdWZDUVBkdVdVQ0NBAAAAAAANm0MWQUpCaWpEdlZSTmFvVkdqVG5rVEp4QQAAAAAAEStcFmNHdl83NmlsUk91ZkNRUGR1V1VDQ0EAAAAAABErXRZjR3ZfNzZpbFJPdWZDUVBkdVdVQ0NB", 
	"result": [ 
	{list of result objects} 
	] 
    } 
   } 
} 

TR50 Request with iterator value

This value should be passed on to the iterator parameter for the subsequent requests to iterate through the result set until the entire result set has been returned. A subsequent request after the initial response is shown below:

{
  "cmd": {
    "command": "thing.list",
    "params": {
      "useSearch": true,
      "iterator": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAADZtEFkFKQmlqRHZWUk5hb1ZHalRua1RKeEEAAAAAABErWxZjR3ZfNzZpbFJPdWZDUVBkdVdVQ0NBAAAAAAANm0MWQUpCaWpEdlZSTmFvVkdqVG5rVEp4QQAAAAAAEStcFmNHdl83NmlsUk91ZkNRUGR1V1VDQ0EAAAAAABErXRZjR3ZfNzZpbFJPdWZDUVBkdVdVQ0NB",
      "limit": "50"
    }
  }
}

When there is no more data to iterate through you will get the following response:

{
  "cmd": {
    "success": false,
    "errorMessages": [
	  "Search has reached end of results." 
	], 
	"errorCodes": [ 
	   -90058 
	] 
   } 
} 

TR50 Request without iterator

{
  "cmd": {
    "command": "thing.list",
    "params": {
      "show": [
        "key",
        "name"
      ],
      "offset": 0,
      "limit": 10,
      "sort": "+name",
      "tags": ["tag1", "tag2"],
      "keys": ["thingkey1", "thingkey2"],
      "hasLoc": true
    }
  }
}

Request Parameters

Name Type Required Description
show Array An array of field names of the data columns to return.
useSearch Boolean   When useSearch is set to true, it will improve the performance of the operation.
In some cases there is a delay between making changes and when they will be visible to the search database, this delay is typically less than 5 seconds. As such, if you perform an update call, and subsequently call a list, you may not see the results of your operation.
iterator String   iterator is used in conjunction with the useSearch to iterate through the returned results. Initial request should be given the value new. Further requests should be given the value got in from the response. For more information, see the example below at the end of this section with the iterator and useSearch.
offset Integer The starting list offset, used for pagination. Defaults to 0, if not specified.
limit Integer Limits the number of results returned. The maximum limit you can set is 2000. Defaults to 2000.
showCount Boolean   By default, it is set to true. If set to false, the response will not include the count. Setting it to false will improve the response time but you will not know the total size of the result set.
sort String sort is an optional parameter that defines the sort order of the result set. It allows to arrange the list in either ascending(+) or descending(-) order. It is possible to sort thing.list in the following categories:id, name, key, defId, iccid, esn, meid, imei, imsi, msisdn, defName, defKey, lastSeen, loc.updated, loc.lat, loc.lng, createdOn, updatedOn, apiCounts.daily, apiCounts.monthToDate, apiCounts.total, firmware.currentVersion, firmware.targetVersion, firmware.state, varBillingPlanCode, and varVasPackageCode
tags Array If specified, the command will only return things that have all tags in this parameter.
keys Array If specified, the command will only return things that have the keys specified in this parameter.
hasLoc Boolean Only return things that have a location. Defaults to false.
hideFields Boolean If set to true, the response will not include the fields in the response parameters.
boundTo String The ID of a thing. When this is specified, the command will only return things that are bound to the thing identified by the boundTo parameter.

TR50 Response

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

{
  "cmd": {
    "success": true,
    "params": {
      	"count": 42,
      	"fields": [
	   	"id",
	   	"key",
	   	"name",
		"ownerOrgId",
		"permission",
		"defKey",
		"defName",
		"gateway",
		"iccid",
		"esn",
		"meid",
		"imei",
		"imsi",
		"msisdn",
		"smsc",
		"connected",
		"lastSeen",
		"lastCommunication",
		"loc",
		"proto",
		"remoteAddr",
		"data",
		"properties",
		"alarms",
		"attrs",
		"createdOn",
		"updatedOn",
		"firmware.id",
		"firmware.currentVersion",
		"firmware.targetVersion",
		"firmware.state",
		"apiCounts.daily",
		"apiCounts.monthToDate",
		"apiCounts.total",
		"sharedWith",
		"varBillingPlanCode",
		"varVasPackageCode"
      ],
      "result": [
        {
	"alarms": {
		"connected": {
			"ts": "2019-04-05T13:46:58.678Z",
			"since": "2019-04-05T13:46:58.678Z",
			"state": 0
			}
		},
	"apiCounts": {
		"daily": 2,
		"monthToDate": 183,
		"total": 16705
		},
	"attrs": {
		"firmware_version": { 
			"ts": "2019-04-16T02:45:48.084Z", 
			"since": "2019-03-13T17:08:27.491Z", 
			"value": "XDK-2.0.1" 
			}, 
		"serial_number": {
			"ts": "2017-08-02T20:48:20.735Z",
			"since": "2017-08-02T20:48:20.735Z",
			"value": "248CE70556961211"
			}
		},
          "id": "531c907b5d80f1330c238757",
          "key": "mything",
          "name": "My Thing",
          "defName": "A Thing",
          "connected": true,
          "connectedId": "53404db65d80f12689016ed3",
          "connectedKey": "myconnectedthing",
          "lastCommunication": "2018-12-05T15:34:43.937Z",
          "lastSeen": "2018-12-05T13:46:58.736Z",
          "gateway": {
            "make": "unknown",
            "model": "unknown",
            "dwProduct": "DW-Gateway.Linux",
            "dwPlatform": "Linux-X86-Generic",
            "dwVersion": "14.1.0-014",
            "appVersion": "2.0",
            "remShell": true
          },
          "proto": "mqtt",
          "remoteAddr": "127.0.0.1:60709",
          "locWithin": {
            "": ""
          },
          "locUpdated": "2019-04-10T20:37:53.887Z",
          "ownerOrgId": "534c36e5310f460721120051",
          "permission": "rw",
          "loc": {
            "lat": 30.455,
            "lng": -84.253333,
            "since": "2019-04-10T20:36:59.839Z",
            "acc": 0,
            "fixType": "unknown",
            "addr": {
              "streetNumber": "",
              "street": "1113 Buckingham Dr",
              "city": "Tallahassee",
              "state": "FL",
              "zipCode": "32308-5212",
              "country": "US"
            }
          }
        },
        ...
      ]
    }
  }
}

Response Parameters

Name Type Description
count Integer The total number of matching things.
fields Array An array of field names of data columns capable of being returned.
result Array The array of thing objects.

Result Array Object

Name Type Description
alarms Object Current alarm values. Since indicates the date/time this alarm had the current state
apicounts Object The number of API calls for the current day, since the beginning of the month, and total
attrs Object Lists the attribute key-value pairs with the timestamps. Since indicates the date/time this alarm had the current state. For more information on attributes, see Defining Attributes.
id String The id of the thing.
key String The key of the thing.
name String The name of the thing.
ownerOrgid String If the thing is shared, then the ownerOrgid displays the id of the organization to which it belongs to. If a thing is not shared then the orgid and the ownerOrgid are the same. For more information on sharing a thing, see Sharing Things and Connections.
permission String The permissions for the thing in the current organization.
defName String The thing definition name.
connected Bool Connection state of the thing
connectedId String If connected through a proxy, this field will contain the thing ID of the proxy.
connectedKey String If connected through a proxy, this field will contain the thing key of the proxy.
lastSeen String The last time the thing got connected.
lastCommunication String The last time the thing indicated that it is connected (the keep-alive heartbeat).
defKey String The key of the thing's definition.
gateway Object The details of the gateway
gateway.make String Brand of the gateway.
gateway.model String Model of the gateway.
gateway.dwProduct String deviceWISE product.
gateway.dwPlatform String deviceWISE platform.
gateway.dwVersion String deviceWISE version.
gateway.appVersion String deviceWISE application version.
gateway.remShell Boolean If the gateway supports remote shell.
proto String Connection protocol.
remoteAddr String The remote address of the thing.
locWithin Array The locations within the current location.
locUpdated String The date and time the Thing location is updated.
loc Object The array containing the location information.
loc.lat Float The latitude of the thing.
loc.lng Float The longitude of the thing.
loc.since String The date and time of the first publish from a location.
loc.acc Integer The accuracy of the location.
loc.fixType String The method used to determine the location of the thing.
loc.addr Object The array containing the address information.
loc.addr.streetNumber String The street number.
loc.addr.street String The street.
loc.addr.city String The city.
loc.addr.state String The state.
loc.addr.zipCode String The zip code.
loc.addr.country String The country.
smsc String The SMSC to use when sending SMS messages to the thing.

PHP API

mixed TR50httpWorker::thingList([$offset[, $limit[, $show[, $sort[, $tags[, $keys]]]]]]);