Monitoring Web Service API Documentation

• Authentication
• API Reference
  • Extract Data
  • Extract Events
• Data Reference
  • Sound
  • Vibration Velocity
  • Vibration Acceleration
  • Weather

Authentication

The API uses Bearer authentication. You must include a unique API key in the header of every request.

Important: Your API key grants access to your project data. Keep it secret and never share it or expose it in client-side code.

Include the API key in the HTTP Authorization header like this:

Authorization: Bearer YOUR_API_KEY

API Reference

Extract Data

Retrieve a list of data records for a specific site.

Note: The API will return an empty response if the station is not configured to register the requested data types.

Endpoint

POST https://api.monitoring.softdb.com/inquiry/sites/{siteId}/records

Query Parameters

Attribute	In	Type	Required	Description
siteId	path	string	Yes	The unique site ID.
time	query	string	Yes	The start time for the request (ISO 8601 format).
endTime	query	string	No	The end time for the request (ISO 8601 format).
format	query	string	No	The response format. Options: json (default) or csv.
timezone	query	string	No	The timezone used for average calculations. Defaults to the site's local timezone.

Body Parameters

The request body must be a JSON object containing a queries array:

{
  "queries": [
    // List of query objects
  ]
}

Base Query Object Fields:

Attribute	Type	Required	Description
type	string	Yes	Must be sound, vibration, weather, or overpressure.
data	string	Yes	The specific data name. See the Data Reference section.
spectrum	string	No	Required for spectrum data. Options: 1 (Octave), 3 (1/3 Octave), or fft (FFT).
period	number	No	Duration of each data point in seconds, aligned to the clock. For example, 3600 returns one data point per hour.

Conditional Fields based on type:

If type is sound:

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

If type is vibration:

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

If type is weather:

Attribute	Type	Required	Description
aggregate	string	Yes	Must be min, max, or avg.

Example Request Body:

{
  "queries": [
    {
      "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
    }
  ]
}

Responses

Success Response (200 OK)

Response 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
]

Response Schema

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "startTime": { "type": "string", "format": "date-time" },
      "endTime": { "type": "string", "format": "date-time" },
      "label": { "type": "string" },
      "unit": { "type": "string" },
      "data": {
        "type": "object",
        "properties": {
          "start": {
            "type": "array",
            "items": { "type": "number" },
            "description": "UNIX timestamps in milliseconds"
          },
          "end": {
            "type": "array",
            "items": { "type": "number" },
            "description": "UNIX timestamps in milliseconds"
          },
          "value": {
            "type": "array",
            "items": { "type": "number" }
          },
          "saturated": {
            "type": "array",
            "items": { "type": "number" }
          }
        },
        "required": ["start", "end", "value", "saturated"]
      }
    },
    "required": ["startTime", "endTime", "label", "unit", "data"]
  }
}

Error Responses

HTTP Code	Description
400	Invalid parameter. Check the response body for details.
401	Missing or invalid authentication token.
403	Access denied. You do not have permission for this resource.
5xx	Server error. Try again later, or contact Soft dB support.

Python Example: Extract Data

import requests

API_TOKEN = "your_api_token"
SITE_ID = "your_site_id"
API_URL = f"https://api.monitoring.softdb.com/inquiry/sites/{SITE_ID}/records"

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

    params = {
        "time": "2024-03-20T00:00:00Z",
        "endTime": "2024-03-21T00:00:00Z",
        "format": "json",
    }

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

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

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

    raise Exception(f"API Error: {response.status_code} - {response.text}")

if __name__ == "__main__":
    print(fetch_data())

---

Extract Events

Retrieve triggered events, their specific details and associated files.

List Events

Retrieve all events for a site within a given timeframe.

GET https://api.monitoring.softdb.com/sites/{siteId}/events

Parameters:

Name	In	Type	Required	Description
siteId	path	string	Yes	The unique site ID.
type	query	string	Yes	The type of event to query (e.g., sound, vibration).
startTime	query	string	Yes	Start time (ISO 8601 format).
endTime	query	string	Yes	End time (ISO 8601 format).
format	query	string	No	Response format: json, csv. Defaults to json.
timezone	query	string	No	Timezone for the response data. Defaults to the site timezone

Response (200 OK)

Response Schema

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": { "type": "string" },
      "startTime": { "type": "string", "format": "date-time" },
      "endTime": { "type": "string", "format": "date-time" },
      "type": { "type": "string" },
      "preTrig": { "type": ["number", "null"] },
      "source": { "type": ["string", "null"] },
      "station": { "type": "string" },
      "site": { "type": "string" },
      "meta": {
        "type": "array",
        "items": { "type": "object" }
      },
      "files": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "startTime": { "type": "string", "format": "date-time" },
            "endTime": { "type": "string", "format": "date-time" },
            "fileType": { "type": "string" },
            "contentType": { "type": "string" },
            "preTrig": { "type": "number" }
          }
        }
      },
      "sound": {
        "type": "object",
        "properties": {
          "audioFile": { "type": "boolean" },
          "image": { "type": "boolean" }
        }
      },
      "vibrations": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "type": { "type": "string" },
            "axis": { "type": "string" },
            "saturated": { "type": "boolean" },
            "peakValue": { "type": ["number", "null"] },
            "peakTime": { "type": ["number", "null"] },
            "peakFreq": { "type": ["number", "null"] }
          }
        }
      },
      "overpressure": {
        "type": ["object", "null"],
        "properties": {
          "saturated": { "type": "boolean" },
          "peakValue": { "type": ["number", "null"] },
          "peakTime": { "type": ["number", "null"] },
          "peakFreq": { "type": ["number", "null"] }
        }
      }
    }
  }
}

Get Event Details

Retrieve the exact details of a single, specific event. This response includes a unique URL link for each file. Those links are valid for 1 hour.

GET https://api.monitoring.softdb.com/sites/{siteId}/events/{eventId}

Parameters:

Name	In	Type	Required	Description
siteId	path	string	Yes	The unique site ID.
eventId	path	string	Yes	The unique event ID.

The response follows the exact schema of a single item from the List Events array above, with the addition of the url property in the files array.

Response Schema

{
  "type": "object",
  "properties": {
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "startTime": { "type": "string", "format": "date-time" },
          "endTime": { "type": "string", "format": "date-time" },
          "fileType": { "type": "string" },
          "contentType": { "type": "string" },
          "preTrig": { "type": "number" },
          "url": { "type": "string", "format": "uri" }
        }
      }
    }
  }
}

Python Example: Extract Events

import requests

API_TOKEN = "your_api_token"
SITE_ID = "your_site_id"
API_URL = f"https://api.monitoring.softdb.com/sites/{SITE_ID}/events"

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

    params = {
        "type": "sound",
        "startTime": "2024-03-20T00:00:00Z",
        "endTime": "2024-03-21T00:00:00Z",
        "format": "json"
    }

    response = requests.get(API_URL, headers=headers, params=params)

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

    raise Exception(f"API Error: {response.status_code} - {response.text}")

if __name__ == "__main__":
    print(fetch_events())

---

Data Reference

Use these exact string values for the data attribute in your queries to specify which metrics you want to extract.

Sound

Value	Description
leq	Equivalent Continuous Sound Level: The average acoustic energy measured over the specified period.
lpk	Peak Sound Level: The highest instantaneous sound pressure level recorded during the period.
lftm5	Takt-Maximal Level: The maximum sound level measured with a fast time weighting over consecutive 5-second intervals.
l_min	Minimum Sound Level: The lowest sound pressure level recorded during the period.
l_max	Maximum Sound Level: The highest sound pressure level recorded during the period.
ln	Percentile Sound Level: The sound level exceeded for n% of the measurement period (requires the stats parameter).

Vibration Velocity

Value	Description
rms	Root Mean Square (RMS): The average vibration velocity energy over the period.
peak	Peak Particle Velocity (PPV): The maximum instantaneous vibration velocity.
kbf_max	Maximum KB Value: The maximum frequency-weighted vibration severity (often used for human perception standards).
kbftm	Takt-Maximal KB Value: The maximum frequency-weighted vibration severity measured over specific time intervals.
vb1_max	Maximum Velocity (Axis 1): The peak vibration velocity along the first primary measurement axis.
vb2_max	Maximum Velocity (Axis 2): The peak vibration velocity along the second primary measurement axis.
vb3_max	Maximum Velocity (Axis 3): The peak vibration velocity along the vertical or third measurement axis.

Vibration Acceleration

Value	Description
rms	Root Mean Square (RMS): The average vibration acceleration energy over the period.
rms_wm	Weighted RMS: The frequency-weighted average vibration acceleration.
peak	Peak Acceleration: The maximum instantaneous vibration acceleration.
peak_wm	Weighted Peak: The frequency-weighted maximum instantaneous acceleration.

Weather

Value	Description
humidity	Relative Humidity: The concentration of water vapor present in the air.
pressure	Barometric Pressure: The atmospheric air pressure.
rain_rate	Precipitation Rate: The volume of rain that falls over the specified time period.
temperature	Air Temperature: The ambient temperature recorded at the site.
wind_direction	Wind Direction: The direction from which the wind originates, measured in degrees.
wind_speed	Wind Speed: The velocity of the wind measured at the station.