Common filters

Both inventory explorer APIs use the same kind of filtering by location with geoBounds or globally with queryString.

Filter queries

The format of a query matches the following pattern:

{
    "filters": {
      "geoBounds": {...},
      "queryString": "..."
    }
}

Global filters

Filtering on location

{
    "filters": {
        "geoBounds": {
            "topLeft": {
                "lat": 50.56789,
                "lon": 1.10101
            },
            "bottomRight": {
                "lat": 12.34567,
                "lon": 20.20202
            }
        }
    }
}

Select all devices within the coordinates boundaries.

Filtering using RSQL notation

Filtering expression using RSQL notation and should not exceed 512 characters.

This syntax permits mixing several patterns according to allowed fields (see following table).

Supported fields Description

name

{
    "queryString": "name=='my Device'"
}

device name

id

{
    "queryString": "id==myId"
}

device identifier

group.path

{
    "queryString": "group.path==/foo/bar"
}

group path

group.id

{
    "queryString": "group.id==myGroupId"
}

group identifier

tags

{
    "queryString": "tags=in=(spain, v2)"
}

tags

properties.k

{
    "queryString": "properties.k==myKey"
}

properties key

properties.v

{
    "queryString": "properties.v==myValue"
}

properties value

properties

{
    "queryString": "properties=q='k==myKey and v==myValue'"
}

properties (associated with =q= operator)

property

{
    "queryString": "property.myKey==myValue"
}

properties (associated with key value, the key must contain only alphanumeric characters and '_', otherwise use the filter described above)

interfaces

{
    "queryString": "interfaces=q='connector==lo*'"
}

interfaces (associated with =q= operator)

interfaces.connector

{
    "queryString": "interfaces.connector==mqtt"
}

interface connector type (Ex: sms, lora, mqtt)

interfaces.nodeId

{
    "queryString": "interfaces.nodeId==myNodeId"
}

interface node identifier

interfaces.enabled

{
    "queryString": "interfaces.enabled==false"
}

interface activation state (true or false)

interfaces.status

{
    "queryString": "interfaces.status!=OFFLINE"
}

interface status (REGISTERED, INITIALIZING, INITIALIZED, REACTIVATED, ONLINE, ACTIVATED, OFFLINE, DEACTIVATED, CONNECTIVITY_ERROR, UNKNOWN)

interfaces.definition.profile

{
    "queryString": "interfaces.definition.profile==Generic_v2"
}

interface profile (for Lora)

activities

{
    "queryString": "activities=q='state!=SILENT or ruleId==ac*'"
}

activities (associated with =q= operator)

activities.ruleId

{
    "queryString": "activities.ruleId==myRuleId"
}

activities rule identifier

activities.state

{
    "queryString": "activities.state==ACTIVE"
}

activities state (UNKNOWN, SILENT, ACTIVE)

aggregatedActivityState

{
    "queryString": "aggregatedActivityState==ACTIVE"
}

activity state (UNKNOWN, SILENT, ACTIVE) aggregated all activities state of the device

network.lora.lostMessagesRangeLabel

{
    "queryString": "network.lora.lostMessagesRangeLabel==10-20%"
}

Buckets (0-10%, 10-20%, 20-30%, 30-100%) corresponding to the percentage of lost messages by the device with Lora connectivity (computed with lostMessagesRatio)

This syntax permits mixing several filters according to allowed logical and comparison operators (see the following table).

Supported operators Description

==

{
    "queryString": "name=='my Device'"
}

equality

==<value>*

{
    "queryString": "id==my*"
}

means search for all id starting with 'my' characters

equality with prefix

!=

{
    "queryString": "group.path!=/foo/bar"
}

means search for all group paths different from '/foo/bar'

different

=q=

{
    "queryString": "properties=q='k==myKey and v==myValue'"
}

means search for all properties with key equals to 'myKey' and value equals 'myValue'.

equality only for activities, interfaces, properties nested fields

=in=

{
    "queryString": "tags=in=(spain, v2)"
}

means search for all tags equals to 'spain' or 'v2'.

group of possible values (corresponding to several 'or' operators)

and

{
    "queryString": "properties.k==myKey and tags!=demo"
}

logical and

;

{
    "queryString": "properties.k==myKey;tags!=demo"
}

identical to 'and' operator (other syntax)

or

{
    "queryString": "properties.k==myKey or tags!=demo"
}

logical or

,

{
    "queryString": "properties.k==myKey,tags!=demo"
}

identical to 'or' operator (other syntax)

RSQL complex syntax using (), '', " " can be executed:

We can regroup fields using parenthesis (by default 'and' operation is always rated first).

{
    "filters": {
        "queryString": "(tags==myTag or name==awesome*) and (group.path==/foo/* or properties=q='k==Version and v==\"my complete value\"' and interfaces.connector==lora)"
    }
}

The apostrophe character can be set using the \\.

{
    "filters": {
        "queryString": "tags=='Aujourd\\'hui'"
    }
}

All fields and values are case sensitive.

When search needs prefix value, only equality operator is accepted in this case.

Combinations of filters

Combining filters is supported. A "filters" section with multiple entries will result in all filters being applied concurrently during devices selection (by performing a logical AND between conditions).

{
    "filters": {
        "queryString": "interfaces.connector==lora",
        "geoBounds": {
            "topLeft": {
                "lat": 50.56789,
                "lon": 1.10101
            },
            "bottomRight": {
                "lat": 12.34567,
                "lon": 20.20202
            }
        }
    }
    }
}

Select all LoRa devices located inside the requested boundaries.

Device internal representation

As a reminder, the public model of a device, as exposed by the device management APIs, is fully described Cf. device object model. The inventory service maintains a slightly different version of this model, in order to provide additional information on devices and facilitate complex queries on their structure.

{
    "id": "urn:lo:nsid:lora:0004A30B001FE084",
    "name": "my device",
    "description": "this is my device",
    "tags": [
        "spain",
        "v2"
    ],
    "properties": [
        {
            "key": "prop1",
            "value": "val1"
        },
        {
            "key": "prop2",
            "value": "val2"
        }
    ],
    "groupId": "uyVhhN",
    "groupPath": "/foo/bar",
    "interfaces": [
        {
            "connector": "lora",
            "nodeId": "0004A30B001FE084",
            "definition" : {                        // Definition content is connectivity dependent
                "devEUI" : "0004A30B001FE084",
                "activationType" : "OTAA",
                "profile" : "Microchip RN2483",
                "encoding" : "StartKit",
                "connectivityOptions" : {
                    "ackUl" : false,
                    "location" : false
                }
            },
            "enabled": true,
            "status": "ACTIVATED"
        }
    ],
    "connectors": ["lora"],
    "config": [],
    "resources": {},
    "location": {
        "lat": 48.8541822991324,
        "lon": 2.3463792646484762,
        "alt": 0.5,
        "accuracy": 10.0,
        "provider": "GPS",
        "lastUpdate": "2020-08-26T09:53:25.308Z",
    },
    "activityStates": [
        {
            "rule": {
                "id": "ec8a3217-7b3f-4020-b37b-133a65ad6384",
                "tags": [
                    "spain",
                    "v2"
                ]
            },
            "timestamp": "2020-08-26T09:53:25.308Z",
            "state": "SILENT"
        }
    ],
    "aggregatedActivityState": "SILENT",
    "lastDataCollected": "2020-08-27T09:51:25.301Z",
    "defaultDataStreamId": "stream1",
    "network": {
        "lora": {
            "lostMessageRangeRatio": 0.024
       }
    }
}

Note that a few fields have been added or modified with respect to the view provided by the device management services:

  • "connectors" is a flat list of all interfaces connectors

  • "lastDataCollected" marks the reception date of the most recent data received from the device

  • "properties" have been reorganized as a list of objects, so that their "key"s and "value"s can be accessed as fields

  • "activityStates" is a more complete view of the device’s activity.All states are available when the device is targeted by several activity rules.

  • "groupPath" is an alias for "group.path".

  • "groupId" is an alias for "group.id".

  • "location" is a record of the last known location of the device that can be either the static location set by a user, or a location published by the device, or a location given by the network, with additional metadata.

  • "aggregatedActivityState" is a simplified activity state which regroups the list of activity rules (present in 'activityStates' field) in an unique state with the following logical :

Aggregated state

Description

SILENT

At least one activity rule is set to SILENT

ACTIVE

At least one activity rule is set to ACTIVE and none is set to SILENT

UNKNOWN

At least one activity rule is set to UNKNOWN and none is set neither to ACTIVE nor to SILENT

  • "network" contains network traffic information relative to device. Data are sorted according to the connectivity (only lora is available for now) (ex : network.lora.lostMessagesRatio) :

Field

Description

lostMessagesRatio

Ratio of messages lost by the device over a 14-day window (with a limit of 10,000 messages). Its value is between 0 and 1 (1 if all messages are lost). Available only if device analytics option is activated.


This version of device representation is not accessible by the API, but you can use the search API from the inventory explorer to get your device representation of inventory explorer version.

Example

POST /api/v1/deviceMgt/explorer/search
{
    "filters": {
        "queryString": "id==urn:lo:nsid:lora:0004A30B001FE084"
    }
}

Response

{
    "bookmark": [
        "urn:lo:nsid:lora:0004A30B001FE084"
    ],
    "devices": [
        {
            "id": "urn:lo:nsid:lora:0004A30B001FE084",
            "name": "my device",
            "description": "this is my device",
            "group": {
                "id": "uyVhhN",
                "path": "/foo/bar"
            },
            "tags": [
                "spain",
                "v2"
            ],
            "properties": [
                {
                "key": "prop1",
                "value": "val1"
            },
            {
                "key": "prop2",
                "value": "val2"
            }
        ],
        "interfaces": [
            {
            "connector": "lora",
            "nodeId": "0004A30B001FE084",
            "definition" : {
                "devEUI" : "0004A30B001FE084",
                "activationType" : "OTAA",
                "profile" : "Microchip RN2483",
                "encoding" : "StartKit",
                "connectivityOptions" : {
                    "ackUl" : false,
                    "location" : false
                }
            },
            "enabled": true,
            "status": "ACTIVATED"
            "capabilities": {
                "configuration": {
                    "available": false
                },
                "command": {
                    "available": false
                },
                "resource": {
                    "available": false
                }
            },
            "activity": {
                "lastDlFcnt": 140,
                "lastUlFcnt": 12799,
                "lastDeactivationTs": "2019-10-23T09:06:10.898Z",
                "lastActivationTs": "2019-10-23T09:06:35.549Z",
                "lastSignalLevel": 1,
                "avgSignalLevel": 1
            },
            "lastContact": "2019-11-28T03:58:38.429Z",
            "created": "2019-09-11T15:26:19.157Z",
            "updated": "2020-08-27T09:51:25.301Z"
            }
        ],
        "activities": [
            {
                "ruleId": "ec8a3217-7b3f-4020-b37b-133a65ad6384",
                "state": "SILENT"
            }
        ],
        "location": {
            "lat": 44.888841,
            "lon": 4.8854379999999935,
            "alt": 123.0,
            "provider": "static",
            "lastUpdate": "2020-08-27T09:51:25.301Z"
        },
        "created": "2019-09-11T15:26:19.157Z",
        "updated": "2020-08-27T09:51:25.301Z",
        "network": {
            "lora": {
                "lostMessageRangeRatio": 0.018
             }
        }
    }]
}
Version 2026.7.0 • Updated date 2026-08-11 12:37:29 UTC