History API [beta]

The History API is designed to provide uplink and downlink packets that an application may miss. The format of the packets is the same as for the DataAPI protocol

The History API stores only uplink and downlink message types. The query parameters are basically the same as for the DataAPI connection . The data may be presented in different formats.

Endpoints

Everynet is operating in different regions and private networks. Each region uses its own endpoint URL. Custom regions and private networks can get endpoint URLs from Everynet support.

For example, the EU region endpoint is:

https://ns.eu.everynet.io/api/v1.0/history

Resources

/api/v1.0/history/data - get DataAPI messages based on a query

You can specify either a Filter ID either a set of parameters. Only one way is allowed at the same time.

Messages are always sorted by the time they are generated by the NS.

Limiting the number of messages to X will produce only first X messages.

You can specify parameters from_id and to_id to specify the exact edges of the messages list. This is useful when you dump messages for the big time interval. Notice that in this case, both messages with ids from_id and to_id will be included.

If you specify all the parameters from, to, from_id, to_id and the timeframes overlap, the minimum time window will be selected.

Limitations

Messages are stored for at least 1 year
The minimum guaranteed message age to be retrieved is 5 minutes.
The maximum limit value is 10000 messages.

Query parameters

Name Format Default value Description
access_token access_token Required The API key. Organization admin rights required.
from yyyymmddHHMMSS One of from / from_id is required Start time. Including the edge.
to yyyymmddHHMMSS End time. NOT including the edge.
from_id message_id (xxx-x) One of from / from_id is required Start ID of the message. Including the start message.
to_id message_id (xxx-x) End ID of the message. Including the end message.
filter filter_id Query messages by already existing Filter.
types type[,type] Select only specific message types.
devices device_eui[,device_eui] Select messages only from a list of devices.
tags tag[,tag] Select messages from devices that had at least one of a tag from a list.
applications application_eui[,application_eui] Select messages only from a list of applications.
gateways gateway_id[,gateway_id] Select messages only from a list of gateways.
lora true \ false false Include LoRa protocol data in the messages.
radio true \ false false Include gateways radio data in the messages.
duplicate true \ false false Include duplicate messages. Applied only for uplink type.
limit number 100 Limit amount of messages
orgs * \ org_id[,org_id] Your organization Server admin only. List of organization IDs or * to get data from all.

Report formats

The Usage API provides data in two formats:

  • JSON A simple json array of objects (messages). Default
  • JSONL Each object (message) is present on an new line.
  • NDJSON Same as JSONL.

In order to specify a format, use an extension in the URL:

./<endpoint>
./<endpoint>.json
./<endpoint>.jsonl
./<endpoint>.ndjson

Simple Example

/api/v1.0/history/data.json
    ?access_token=<access token>
    &from=20210401000000
    &to=20210601000000
    &types=uplink
    &limit=2
[
{"id": "1620763780022-0", "meta": {"application": "6bc13f53997cb1d8", "device": "200032c8fc3df447", "device_addr": "163a6895", "gateway": "959a2322e92c213e", "network": "4d22632fa1ead06ea3fbaf85a6208ae1", "packet_hash": "04b071d5eff8c9474ceac9307bf89aaf", "packet_id": "fa5a7d82b90bc8c4997a98b1a63839d5", "time": 1620763780.022}, "params": {"counter_down": 0, "encrypted_payload": "HNvhaS09b0MK/ouqdUips+WqPfnu5mgXwKHYsgus8TU33eoCRg==", "payload": "BAAFANKthAcDGE+EUAcEuF6EUAcFiGaEUAcGWG6EUAcH6FaEZg==", "port": 0}, "type": "downlink"},
{"id": "1620763780544-0", "meta": {"application": "6bc13f53997cb1d8", "device": "200032c8fc3df447", "device_addr": "163a6895", "gateway": "959a2322e92c213e", "network": "4d22632fa1ead06ea3fbaf85a6208ae1", "packet_hash": "0f5107f43a6b4576a1c18ddc066155d1", "packet_id": "db5a6a60aca935bbe98b4f5e2ae0668a", "time": 1620763780.544}, "params": {"counter_up": 1, "duplicate": false, "encrypted_payload": "", "payload": "", "port": 1, "rx_time": 1620763780.513455}, "type": "uplink"}
]

Huge history dump example

Let's say that you need all the messages from 01-01-2020 to 01-01-2021.
Your messages traffic is 20k uplinks a month.

The algorithm in this case is the following.

You start to retrieve messages with the limit=1000 and from field.
When you reach the limit, you make another request with the last received message id as from_id field.
Upon the next request, your last message will be present as the first message.
When the amount of received messages is less than a limit, it means that there are no more messages for that time period available.

/api/v1.0/history/data.jsonl
    ...
        &from=20200101000000
        &to=20210101000000
        &limit=1000
    ...
Results (1000)    
{"id": "1620763764439-0", "meta": {"application": "6bc13f53997cb1d8", "device": "41340736ce87e291", "device_addr": "16ec088a", "gateway": "f8a8a76da30f8396", "network": "4d22632fa1ead06ea3fbaf85a6208ae1", "packet_hash": "ba8e803b94bf2ae88d4b51e1e745294e", "packet_id": "3338b88acca70932908f554aea5961f5", "time": 1620763764.439}, "params": {"counter_up": 22, "duplicate": false, "encrypted_payload": "JTAqx2HJGWMbZ+hibvAFsmiqAK/9ZzhHaw==", "payload": "MWY1ZTVlOTNmYjYwNTlmN2U1MTIzZmE5YQ==", "port": 1, "rx_time": 1620763764.40929}, "type": "uplink"}
...
{"id": "1620763780022-0", "meta": {"application": "6bc13f53997cb1d8", "device": "200032c8fc3df447", "device_addr": "163a6895", "gateway": "959a2322e92c213e", "network": "4d22632fa1ead06ea3fbaf85a6208ae1", "packet_hash": "04b071d5eff8c9474ceac9307bf89aaf", "packet_id": "fa5a7d82b90bc8c4997a98b1a63839d5", "time": 1620763780.022}, "params": {"counter_down": 0, "encrypted_payload": "HNvhaS09b0MK/ouqdUips+WqPfnu5mgXwKHYsgus8TU33eoCRg==", "payload": "BAAFANKthAcDGE+EUAcEuF6EUAcFiGaEUAcGWG6EUAcH6FaEZg==", "port": 0}, "type": "downlink"}
/api/v1.0/history/data.jsonl
    ...
        &from=20200101000000
        &to=20210101000000
        &limit=1000
        &from_id=1620763780022-0
    ...
Results (958)    
# first message is the same from previous request
{"id": "1620763780022-0", "meta": {"application": "6bc13f53997cb1d8", "device": "200032c8fc3df447", "device_addr": "163a6895", "gateway": "959a2322e92c213e", "network": "4d22632fa1ead06ea3fbaf85a6208ae1", "packet_hash": "04b071d5eff8c9474ceac9307bf89aaf", "packet_id": "fa5a7d82b90bc8c4997a98b1a63839d5", "time": 1620763780.022}, "params": {"counter_down": 0, "encrypted_payload": "HNvhaS09b0MK/ouqdUips+WqPfnu5mgXwKHYsgus8TU33eoCRg==", "payload": "BAAFANKthAcDGE+EUAcEuF6EUAcFiGaEUAcGWG6EUAcH6FaEZg==", "port": 0}, "type": "downlink"}
...
{"id": "1620763783065-0", "meta": {"application": "6bc13f53997cb1d8", "device": "41340736ce87e291", "device_addr": "16ec088a", "gateway": "f8a8a76da30f8396", "network": "4d22632fa1ead06ea3fbaf85a6208ae1", "packet_hash": "aee47016c3f8b647b9bca82364d17d77", "packet_id": "cf388df65e6c0a10b226e10a776494ba", "time": 1620763783.065}, "params": {"counter_up": 23, "duplicate": false, "encrypted_payload": "4Wiq1T16bNJebnOW+QlXnGcRQM+W6+VBDg==", "payload": "NmU4NTI4OWI2ZDRjNjEyN2JiM2JlYTU3NA==", "port": 1, "rx_time": 1620763783.037382}, "type": "uplink"}

results matching ""

    No results matching ""