Monitoring Web Service Api Documentation

Obtaining an API key

Authentication is handled using Bearer authentication, which consists of sending an API key that is unique to your account with each request. This key should be kept secret and not shared with anyone.

To include your API key in your request, add an HTTP Authorization header, consisting of the Bearer keyword and the token, like so:

Authorization: Bearer YOUR_API_KEY

API Reference

Extract Data

Get a list of records for a specific site.

Note: Nothing is returned if the station is not configured to register the requested data types.

POST https://api.monitoring.softdb.com/inquiry/v2/records

Parameters for the request

Query parameters:

Attribute	Type	Required	Description
project	string	Yes	The project ID. Contact Soft dB to get it.
time	string	Yes	The start time for the requests. The format is ISO 8601.
endTime	string	No	The end time for the request. The format is ISO 8601.
format	string	No	The format of the response. The default is json. The other option is csv.
timezone	string	No	The timezone used for the average calculation. The default is the timezone of the site location.

Body parameters:

The body of the request is a JSON object that contains an array of queries, like so:

{
  "queries": [
    ... // List of queries
  ]
}

Each query object has the following fields:

Attribute	Type	Required	Description
type	string	Yes	One of sound, vibration, weather or overpressure.
data	string	Yes	The name of the data. Please see the Data Reference.
spectrum	string	No	Required if wanted to extract spectrum data. Can be 1 for Octave, 3 for 1/3 Octave or fft for the FFT.
period	number	No	The duration of each data points in seconds, aligned on the clock. For example, if the period is 3600, each data points will be of 1 hour long every hour.

Depending of the type attribute, more attributes may be required.

If the type is sound:

Attribute	Type	Required	Description
ponderation	string	Yes	One of a, c or z.
stats	number	Conditionally	Required if data is ln. The number must be between 1 and 100.

If the type is vibration:

Attribute	Type	Required	Description
subType	string	Yes	One of velocity, or acceleration.
axis	string	Yes	One of x, y, z or v_sum

If the type is weather:

Attribute	Type	Required	Description
aggregate	string	Yes	One of min, max or avg.

Here is an example of queries to get the LAeq, the LA50% and the Average temperature for every 15 minutes:

[
  {
    "type": "sound",
    "data": "leq",
    "ponderation": "a",
    "period": 900
  },
  {
    "type": "sound",
    "data": "ln",
    "ponderation": "a",
    "stats": 50,
    "period": 900
  },
  {
    "type": "weather",
    "data": "temperature",
    "aggregate": "avg",
    "period": 900
  }
]

Success Response

Returns [200 OK] and a list of records. Each records has the folowwing response attributes:

Attribute	Type	Description
startTime	string	The start time of the response in the ISO 8601 format.
endTime	string	The end time of the response in the ISO 8601 format.
label	string	The name of the requested data type.
unit	string	The SI unit of the data.
data	object	The response data.
data.start	array	List of start time. It's a list of number representing the UNIX time in milliseconds.
data.end	array	List of end time. It's a list of number representing the UNIX time in milliseconds.
data.value	array	List of data point. It's a list of number.
data.saturated	array	List of saturation flags. It is 1 if saturated and 0 if not saturated.

Here is an example:

[
    {
        "startTime": "2024-08-22T10:00:00.000Z",
        "endTime": "2024-08-22T18:57:00.000Z",
        "label": "LAeq 1h (dB)",
        "unit": "dB",
        "data": {
            "start": [
                1724320800000,
                1724324400000,
                1724328000000,
                1724331600000,
                1724335200000,
                1724338800000,
                1724342400000,
                1724346000000,
                1724349600000
            ],
            "end": [
                1724324400000,
                1724328000000,
                1724331600000,
                1724335200000,
                1724338800000,
                1724342400000,
                1724346000000,
                1724349600000,
                1724353020000
            ],
            "saturated": [
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0
            ],
            "value": [
                53.83112,
                54.467808,
                54.42323,
                56.282578,
                55.718815,
                55.36246,
                55.501812,
                55.89459,
                56.359077
            ]
        }
    }
  ... // Other queries results
]

Error Responses

HTTP Code	Description
400	One of the parameter is invalid. Please see the response body for more details.
401	The auth token is missing in the header or it is invalid.
403	You don't have access to this ressource. If you believe this is an error, please contact Soft dB.
5xx	Try again later. If the error persist, please contact Soft dB for further assitances.

Example in Python

import requests

# Please contact Soft dB to get your API token
API_TOKEN = "your_api_token"

START_TIME = "2024-03-20T00:00:00Z"
END_TIME = "2024-03-21T00:00:00Z"

# Please contact Soft dB to get your project ID
PROJECT_ID = "your_project_id"

queries = [
    {"type": "sound", "data": "leq", "ponderation": "a", "period": 3600},
    {"type": "sound", "data": "ln", "ponderation": "a", "stats": 10, "period": 3600},
    {
        "type": "weather",
        "data": "temperature",
        "aggregate": "avg",
        "period": 3600,
    },
    {
        "type": "weather",
        "data": "pressure",
        "aggregate": "avg",
        "period": 3600,
    },
]

API_URL = "https://api.monitoring.softdb.com/inquiry/v2/records"


def fetch_softdb_data():
    headers = {
        "Authorization": f"Bearer {API_TOKEN}",
    }

    params = {
        "project": PROJECT_ID,
        "time": START_TIME,
        "endTime": END_TIME,
        "format": "json",
    }

    response = requests.post(
        API_URL, headers=headers, params=params, json={"queries": queries}
    )

    if response.status_code == 200:
        return response.json()

    raise Exception(f"Failed to fetch data from Soft dB API: {response.text}")


if __name__ == "__main__":
    data = fetch_softdb_data()
    print(data)

Data Reference

Sound

• leq
• lpk
• lftm5
• l_min
• l_max
• ln

Vibration Velocity

• rms
• peak
• kbf_max
• kbftm
• vb1_max
• vb2_max
• vb3_max

Vibration Acceleration

• rms
• rms_wm
• peak
• peak_wm

Weather

• humidity
• pressure
• rain_rate
• temperature
• wind_direction
• wind_speed