Document the API to get public device data

[coderbyheart]

The site serves the device data via a REST API (https://api.nordicsemi.world/2024-04-15/devices) which can be used by third party apps to show data. Document this and make the API stable. Right now we might change this without any notice.

[martinberlin]

Upvoting this.
What it would be really useful is that each device stores an historical of the ambient readings in the API, so for example calling:
https://api.nordicsemi.world/2024-04-15/devices?ids=affirmer-lavature-salaried
So we can get in the JSON something like:

{
    "historical": [
        {
            "21": {
                "temp": 21,
                "hum": 56,
                "air_q": 550
            },
            "22": {
                "temp": 22.6,
                "hum": 56,
                "air_q": 500
            }
        }
    ]
}

21 would be the data recollection pushed at 9 PM. But that could be a timestamp or whatever. Then you can see how the ambient data recollection evolves and represent that information on a chart.

[coderbyheart]

The history is also available:

First you need to acquire a JWT for the device which is signed by the map backend and which attests that this is a public device:

http https://api.nordicsemi.world/2024-04-15/device/affirmer-lavature-salaried/jwt

{
    "@context": "https://github.com/hello-nrfcloud/proto-map/device-jwt",
    "deviceId": "oob-359404230237456",
    "id": "affirmer-lavature-salaried",
    "jwt": "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6ImEzZDZkZjQ2LTM1MDMtNDkxZS05MDU5LWFmMjQ5Y2YyYTQ1NCJ9.eyJAY29udGV4dCI6Imh0dHBzOi8vZ2l0aHViLmNvbS9oZWxsby1ucmZjbG91ZC9wcm90by1tYXAvZGV2aWNlLWp3dCIsImlkIjoiYWZmaXJtZXItbGF2YXR1cmUtc2FsYXJpZWQiLCJkZXZpY2VJZCI6Im9vYi0zNTk0MDQyMzAyMzc0NTYiLCJtb2RlbCI6InRoaW5neTkxeCIsImlhdCI6MTc0NDg4MjAxMCwiZXhwIjoxNzQ0ODg1NjEwLCJhdWQiOiJoZWxsby5ucmZjbG91ZC5jb20ifQ.AQf067DUj3tEEVaXCuhQNH94Pfyf1gJJlHbLS8yxB0LWMlMayxnH5xK3NLuqHQ8RnmdztNoKE2gKQfEmxnAZfq0zANCAXk1Dklihvn1rQV4_3w0Y_BuZw57UfkH5NM6BmJiLW7tu-gCukKG4bKacZBeYC17m8YGpEdotk1No33tO7IKv",
    "model": "thingy91x"
}

Then use that JWT to request the history e.g. the LwM2M environment object (14205), instance 0 (oob-359404230237456 is the device ID):

http 'https://api.hello.nordicsemi.cloud/2024-04-17/device/oob-359404230237456/history/14205/0?jwt=eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6ImEzZDZkZjQ2LTM1MDMtNDkxZS05MDU5LWFmMjQ5Y2YyYTQ1NCJ9.eyJAY29udGV4dCI6Imh0dHBzOi8vZ2l0aHViLmNvbS9oZWxsby1ucmZjbG91ZC9wcm90by1tYXAvZGV2aWNlLWp3dCIsImlkIjoiYWZmaXJtZXItbGF2YXR1cmUtc2FsYXJpZWQiLCJkZXZpY2VJZCI6Im9vYi0zNTk0MDQyMzAyMzc0NTYiLCJtb2RlbCI6InRoaW5neTkxeCIsImlhdCI6MTc0NDg4MTkyMCwiZXhwIjoxNzQ0ODg1NTIwLCJhdWQiOiJoZWxsby5ucmZjbG91ZC5jb20ifQ.ADa71dbtozgAt9nq2xp6vEXeOgqZCEvVlw2_Xle4rsF70-h-DCfWR7_tXBrZZ96x9gdCRuK7qS4wizjHW6EsLnqWAYYaU3-Jnmn7dcNf-bQvlb_aRX0hOq4b_REyxfXgYJYOsHfZWt4bUWspyPHHlgvWrFVechJi3Am7ZxBygctztzIp&timeSpan=lastDay' 

Source: https://github.com/hello-nrfcloud/backend/blob/32e6f2402b31229ce47b9b929f9113e65b429489/lambda/queryLwM2MHistory.ts#L82-L109

The result is a JSON with the history:

{
    "@context": "https://github.com/hello-nrfcloud/proto/lwm2m/object/history",
    "partialInstances": [
        {
            "0": 9.212696,
            "1": 66.982833,
            "10": 123,
            "2": 1011.9119531199999,
            "99": 1744879500
        },
        {
            "0": 6.297387,
            "1": 60.015956,
            "10": 64,
            "2": 995.1965625,
            "99": 1744875900
        },
        {
            "0": 5.8468029999999995,
            "1": 59.28244,
            "10": 59,
            "2": 994.54125,
            "99": 1744872300
        },
        {
            "0": 5.984686,
            "1": 58.95959,
            "10": 59,
            "2": 994.57453125,
            "99": 1744868700
        },
        {
            "0": 6.235831,
            "1": 58.838619,
            "10": 57,
            "2": 994.13664062,
            "99": 1744865100
        },
        {
            "0": 6.548532,
            "1": 58.586841,
            "10": 50,
            "2": 993.98648437,
            "99": 1744860600
        },
        {
            "0": 6.996658,
            "1": 58.368255,
            "10": 53,
            "2": 993.84664062,
            "99": 1744857000
        },
        {
            "0": 7.501418,
            "1": 58.060039,
            "10": 51,
            "2": 994.12148437,
            "99": 1744853400
        },
        {
            "0": 8.048037,
            "1": 57.674907,
            "10": 51,
            "2": 994.43234375,
            "99": 1744849800
        },
        {
            "0": 8.688228,
            "1": 57.0554,
            "10": 52,
            "2": 994.71414062,
            "99": 1744846200
        },
        {
            "0": 9.419528,
            "1": 56.217014,
            "10": 50,
            "2": 995.20804687,
            "99": 1744842600
        },
        {
            "0": 10.480787,
            "1": 55.070739,
            "10": 50,
            "2": 995.47640625,
            "99": 1744839000
        },
        {
            "0": 12.460523,
            "1": 53.892223,
            "10": 75,
            "2": 995.1877343699999,
            "99": 1744835400
        },
        {
            "0": 14.905709,
            "1": 53.236206,
            "10": 110,
            "2": 995.0353906199999,
            "99": 1744831800
        },
        {
            "0": 17.845932,
            "1": 53.020198,
            "10": 156,
            "2": 995.09929687,
            "99": 1744828200
        },
        {
            "0": 22.098842,
            "1": 52.971691,
            "10": 180,
            "2": 1009.44109375,
            "99": 1744821000
        },
        {
            "0": 20.042545,
            "1": 56.283847,
            "10": 181,
            "2": 1009.7072656199999,
            "99": 1744817400
        },
        {
            "0": 19.589427,
            "1": 57.962024,
            "10": 181,
            "2": 996.9924218699999,
            "99": 1744813800
        },
        {
            "0": 21.680191,
            "1": 62.05772,
            "10": 200,
            "2": 993.8334375,
            "99": 1744810200
        },
        {
            "0": 18.56007,
            "1": 65.726028,
            "10": 169,
            "2": 993.74304687,
            "99": 1744806600
        },
        {
            "0": 13.396235,
            "1": 65.891494,
            "10": 88,
            "2": 993.85125,
            "99": 1744803000
        },
        {
            "0": 9.990784,
            "1": 60.975109,
            "10": 54,
            "2": 994.25328125,
            "99": 1744799400
        },
        {
            "0": 9.047721,
            "1": 58.723171,
            "10": 55,
            "2": 993.7159375,
            "99": 1744795800
        }
    ],
    "query": {
        "ObjectID": 14205,
        "ObjectInstanceID": 0,
        "ObjectVersion": "1.0",
        "binIntervalMinutes": 15,
        "deviceId": "oob-359404230237456"
    }
}

[coderbyheart]

partialInstances contains an array of the numeric resources in the LwM2M object. String resources are not persisted in history.

[martinberlin]

That's great. So then partialInstances is an array of objects, that starts from 0 to 23 hours, representing each hour of the day?
Then about the data I figured out some but not all. The device is currently in my car so it's a bit cold outside in the morning in Catalunya:

{
    "0": 9.212696,
    "1": 66.982833,
    "2": 1011.9119531199999,
    "10": 123,
    "99": 1744879500
}

0: temperature
1: humidity
2: air pressure
10: air quality index BME688
99: timestamp, in my timezone would be 17 de abril de 2025 10:45

And sadly it's not coming anywhere what amount of battery is left. Or at least not in this query right?
But is already some data I could recollect and I think will serve my purpouse to use Thingy91 as a sensor to recollect information "as is" which is already a great start.

There is also another thing that I do not understand:

https://api.nordicsemi.world/2024-04-15/device/affirmer-lavature-salaried/jwt

Why the date part has to be 2024-04-15 ? I though it could be simply yesterday. But changing that fixed date results in {"message":"Forbidden"}

[coderbyheart]

The date in the URL (2024-04-15) is the API version.

Right now you cannot control the date range or start date for the history, it's fixed to the most recent timespan.

See the LwM2M object definitions for the documentation of the objects. 14205 is Environment. For your battery readings query the object 14202 (Battery and Power).

http 'https://api.hello.nordicsemi.cloud/2024-04-17/device/oob-359404230237456/history/14202/0?jwt=<jwt>&timeSpan=lastDay' 

[martinberlin]

Great thanks I will prepare an API in PHP 8.4 that can make this requests and save Thingy data in MySQL tables. That way we can set up each Nordic device with its own internal ID and then a cron each hour will recollect and store the past hour information

[coderbyheart]

You might be interested in older data, try experimenting with other timespans. They are documented here: https://github.com/hello-nrfcloud/backend/blob/32e6f2402b31229ce47b9b929f9113e65b429489/historicalData/HistoricalDataTimeSpans.ts#L13-L30

[martinberlin]

Thanks!
When I try that with the battery level query it works.
But same timespan setting with the ambient data is giving me only the last hour (1 item in the array)

[coderbyheart]

I guess your device has not sent in new or changed data in the last hour.

[martinberlin]

I discovered what it is: The GET parameters are case sensitive. Wrote timespan instead of timeSpan
Works great thanks!

[martinberlin]

I found something a bit odd when making my device public. After one month or so it stopped being public. I didn't deactivated it...
Just trying to fetch it from my symfony command got this reply:

{
    "@context": "https://github.com/hello-nrfcloud/proto/ProblemDetail",
    "title": "Device with id affirmer-lavature-salaried not shared: not_found",
    "status": 404
}

So I had to start the process again which changed my old stringID to a new one. Could this be changed in the future?
Can't be a device set to be public forever with the same ID per user request?
That would be awesome for people that wants to recollect data and do not mind that their device is public. Of course if you want it to be not public because you are tracking moving targets then you need to flash the devices with your own Firmware.

Other than that if someone is interested I can share my Nordic fetch-data (PHP 8.4 / Symfony 7 + Doctrine ORM will work with any DB like mysql or postgres just with some minor modifications)

[coderbyheart]

Device owner needs to confirm the publishing of data every 30 days. You should have received an email from [email protected] with the subject [hello.nrfcloud.com] › Action needed: <number> of your devices will expire soon

[martinberlin]

Yes correct now I see it. Quick question: Is very hard the learning curve to flash the Firmware with modifications?
If someone is interested in my data fetching script I will make it public.

[martinberlin]

We ‘ve built in Sensoria a way to configure Nordic Thingy daily data recollection for anyone that is using this sensors in their office or workplace. The idea is to make a post process after recollecting a full day of time series (each hour sensor information). That post process will send the sensor data to AI agents that will recommend actions to make your workplace more productive