Searching data
This guide explains how to fetch the right kind of data depending on your usage, by using the Stonal search API with filters, pagination, and advanced search patterns.
You will need to get a personal access token to use the search API.
Getting started
Authentication
Here is a sample request around the search API, where we will fetch BUILDING_GROUPs and BUILDINGs.
You need to pass a query with something like that:
#!/bin/sh -ex
# Your organization
STONAL_ORG=DEMO
# Fetch your token from here: https://app.stonal.io/users/app
STONAL_TOKEN=9631e269-e21e-4ce6-92a9-c6f7ed1fa98a
curl \
https://api.stonal.io/datalake/v1/organizations/$STONAL_ORG/assets/search \
-v \
-X POST \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $STONAL_TOKEN" \
-d @query.json -o output.json
Initial query
{
"search": {
"type": {
"equals": [
"BUILDING",
"BUILDING_GROUP"
]
}
},
"properties": {
"simple": ["LAT", "LNG"]
},
"fields": [
"name",
"type",
"uid",
"externalIds"
],
"paginate": {
"size": 2
}
}
The output will be similar to this:
{
"assets": [
{
"uid": "f6472f1a-9473-4fbf-9e1c-1c063eebb430",
"name": "Building Group 1",
"type": "BUILDING_GROUP",
"externalIds": {
"SOURCE_NAME": "BG001"
},
"properties": {
"simple": {
"LAT": "46.800",
"LNG": "1.6959"
}
}
},
{
"uid": "b81ce341-86f0-4cfe-a806-1d4a0f9a12ed",
"name": "Building 1",
"type": "BUILDING",
"externalIds": {
"SOURCE_NAME": "B001"
},
"properties": {
"simple": {
"LAT": "46.500",
"LNG": "1.7959"
}
}
}
],
"paginate": {
"size": 2,
"cursor": "123456"
}
}
Subsequent queries
Then to fetch the next batch of 10 assets, you shall issue the same query with the paginate.cursor set to
the received value, ie "123456".
{
"search": {
"type": {
"equals": [
"BUILDING",
"BUILDING_GROUP"
]
}
},
"fields": [
"name",
"type",
"uid",
"externalIds",
"parent"
],
"paginate": {
"size": 2,
"cursor": "123456"
}
}
The output will be similar to this:
{
"assets": [
{
"uid": "dd127caf-5b9b-4116-884e-b42505ac1bd6",
"name": "Building Group 2",
"type": "BUILDING_GROUP",
"externalIds": {
"CODE": "BG002"
}
},
{
"uid": "2c2ca7be-78f1-4734-a4c6-bbc773c9027b",
"name": "Building 2",
"type": "BUILDING",
"externalIds": {
"CODE": "B002"
},
"parent": {
"uid": "dd127caf-5b9b-4116-884e-b42505ac1bd6"
}
}
],
"paginate": {
"size": 2,
"cursor": "234567"
}
}
Going further
There are many other ways to query data. And you can mix any of these filters.
Searching by external IDs
You can search using a single external ID, either from the asset itself or from its relations.
Searching a specific asset by one of its external IDs.
"search": {
"asset": {
"externalIds": {
"SOURCE_NAME": "BG001"
}
}
}
Searching assets whose parent matches the given external ID.
"search": {
"parent": {
"externalIds": {
"SOURCE_NAME": "BG001"
}
}
}
Matching on a pattern
You can search for types matching a regex pattern.
Searching for spaces
SPACE is another name for rooms in the Stonal platform.
This will return assets of SPACE and SPACE|* types:
"search": {
"type": {
"pattern": [
"SPACE",
"SPACE\\|.*"
]
}
}
Please note that this will apply to all spaces within the organization. If you want to limit it to a particular building, you should combine it with a parent filter like this:
"search": {
"type": {
"pattern": [
"SPACE",
"SPACE\\|.*"
]
},
"parent": {
"externalIds": {
"SOURCE_NAME": "BG001"
}
}
}
Excluding by type
Only one of notMatches or notEquals is accepted (same as matches & equals)
By matching on a pattern
Exclude specified equipments (those having a type starting by EQUIPMENT|C|CA|) when listing equipments in a building group
"search": {
"type": {
"matches": ["EQUIPMENT\\|.*"],
"notMatches": ["EQUIPMENT\\|C\\|CA\\|.*"]
},
"parentRecursive": {
"externalIds": { "CODE": "SITE_001" }
}
}
By strict equality
Exclude specified equipments (those having a type equals to EQUIPMENT|C|CA|CA01 or EQUIPMENT|A|AA) when listing equipments in a building group
"search": {
"type": {
"matches": ["EQUIPMENT\\|.*"],
"notEquals": ["EQUIPMENT|C|CA|CA01", "EQUIPMENT|A|AA"]
},
"parentRecursive": {
"externalIds": { "CODE": "SITE_001" }
}
}
Fetch a subset of fields
Fields are attributes directly associated with an asset. You can specify which fields to retrieve.
Allowed values: uid, name, updatedAt, deletedAt, type, externalIds, representations, parent
Unique identifier uid is always returned.
{
"search": {
"asset": { "uid": "2cb3683a-90f6-48de-aaa0-08f45c7bf808" }
},
"fields": ["name", "updatedAt", "externalIds"]
}
Fetch a subset of properties
Properties are associated with time-series data linked to an asset.
You can fetch the reference data for a specified property at the current time.
Items of simple list are referring to property’s code.
This code can be found in our DQC product for each asset's type
In this example we are on an BUILDING, its property named Adresse has ADDRESS for code.
Screenshoot from DQC on a URL like https://app.stonal.io/dqc/$ORGANIZATION_CODE/asset-types/EQUIPMENT/assets/$ASSET_UID
Nb: code can also have uuid format
In this example we are on an EQUIPMENT, its property named Date dernier renouvellement has 43f1f705-b3b3-4ff3-9ca3-a5c5ed638eef for code.
Screenshoot from DQC on a URL like https://app.stonal.io/dqc/$ORGANIZATION_CODE/asset-types/EQUIPMENT/assets/$ASSET_UID
{
"search": {
"type": { "equals": ["BUILDING"] }
},
"properties": {
"simple": ["ADDRESS", "BUILDING_DATE"]
}
}
{
"assets": [
{
"uid": "1321987a-b94f-4180-ab93-94432be0855f",
"properties": {
"simple": {
"ADDRESS": "28 Cr Albert 1er, 75008 Paris",
"BUILDING_DATE": "2001-09-29"
}
}
}
]
}
Differential update
You can search data that has been updated since a particular date.
"search": {
"updatedAtAfter": "2025-09-12T00:00:00"
}
Detect deleted assets
In search response, you can also include deleted assets matching specified filters.
"search": {
"updatedAtAfter": "2025-09-12T00:00:00",
"includeDeleted": true
}
Asset pictures
This mostly applies to BUILDING_GROUP and BUILDING assets.
If the asset has a PHOTO_ID, we can access it directly using this pattern of URL:
https://api.stonal.io/document-storage/v1/organizations/$org/documents/$photoId/content
We also provide a resizing and thumbnail generation for picture using imagor so that you can use it direclty in your frontend API:
https://cdn-api.stonal.io/imagor/unsafe/fit-in/200x/api.stonal.io/document-storage/v1/organizations/$org/documents/$photoId/content
The unsafe in the URL means you don't require to sign the URL but it is safe to use.