Skip to content
API Reference/
/
Fetch noise measurements

MyCirrus API - Instrument info, Data and Webhooks (1.0.1)

API documentation for the MyCirrus API

Download OpenAPI description
mycirrus-main.json
mycirrus-main.yaml
Overview
URL
https://www.cirrusresearch.com/support/
Support
support@cirrusresearch.com
License
MIT
Terms of Service
Languages
Servers
Mock server
https://docs.mycirrus.cloud/_mock/apis/mycirrus-main
Production server
https://api.mycirrus.cloud/v1

Instrument info and control

Endpoints for finding and controlling instruments

Operations

Noise data

Endpoints for retrieving historic noise data

Operations

Fetch noise measurements

Request

Get noise measurements for the selected instruments and time range.

Optionally choose which values to include and what period to recalculate results to.

The possible values are:

  • Leq
    • LAeq, LCeq, LZeq
    • LAE, LCE, LZE
    • LEX8
  • Peak
    • LAPeak, LCPeak, LZPeak
  • SPL Max
    • LAFMax, LASMax, LAIMax
    • LCFMax, LCSMax, LCIMax
    • LZFMax, LZSMax, LZIMax
  • Statistical Levels
    • LAF1, LAF5, LAF10, LAF50, LAF90, LAF95, LAF99
    • Not supported if Period is used. Only available from the measurements as recorded.
  • Moving Average
    • LeqT1Max, LeqT2Max
    • These fields will also add LeqT1Type and LeqT2Type to the results which include the friendly name of these types based on the settings.

 

If you specify an invalid or unavailable value, the server will ignore it.
If all specified values are invalid, the server will respond with an error.
If no values are specified, the server will return the default results (LAeq, LCPeak, LAFMax).

The maximum date range per request is 31 days. If you request a longer range, the server will respond with an error.
The default Period is the measurement period as configured in the instrument. See the settings for details.
The period can be set to anything between the measurement period and 1 day. If you request a period outside this range, the server will respond with an error.

Requires an API key with the data.noise:read scope.

Security
apikey
Query
instrumentsArray of stringsrequired

Serial numbers of selected instruments

Example: instruments=QT123456&instruments=QT234567
startstring(date-time)required

Start date and time for loading a range of data. Must be in UTC.

This uses the ISO8601 format. For example, 2023-01-01T00:00:00Z is 1st January 2023 at midnight UTC.

Example: start=2023-01-01T00:00:00Z
endstring(date-time)required

End date and time for loading a range of data. Must be in UTC.

This uses the ISO8601 format. For example, 2023-01-01T00:00:00Z is 1st January 2023 at midnight UTC.

Example: end=2023-01-31T00:00:00Z
periodstring(duration)

Period to recalculate measurement samples to.

This cannot be less than the recorded measurement period.

This uses the ISO8601 duration format. For example, P1D is 1 day, PT1H is 1 hour, PT5M is 5 minutes.

Example: period=PT1H
valuesArray of strings

Names of selected values to include in results

Default ["LAeq","LCPeak","LAFMax"]
Example: values=LAeq&values=LCPeak&values=LAFMax
curl -i -X GET \
  'https://docs.mycirrus.cloud/_mock/apis/mycirrus-main/data/noise/measurements?instruments=QT123456%2CQT234567&start=2023-01-01T00%3A00%3A00Z&end=2023-01-31T00%3A00%3A00Z&period=PT1H&values=LAeq%2CLCPeak%2CLAFMax' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/jsonArray [
startTimestring(date-time)
endTimestring(date-time)
durationinteger
instrumentstring
overloadboolean
valuesArray of objects
]
Response
application/json
[
  {
    "startTime": "2023-06-14T23:00:00Z",
    "endTime": "2023-06-14T23:15:00Z",
    "duration": 900,
    "instrument": "QT123456",
    "overload": false,
    "values": [ … ]
  }
]

Fetch noise time history

Request

Get noise time history for the selected instruments and time range.

Optionally choose which values to include and what period to recalculate results to.

The maximum date range per request is 7 days. If you request a longer range, the server will respond with an error.
The default Period is 1 second.
The period can be set to anything between the current time history setting and 1 minute. If you request a period outside this range, the server will respond with an error.
You can request data with a period of less than 1 second by using a fractional seconds value in the period. For example, PT0.1S for 100ms.

Requires an API key with the data.noise:read scope.

Security
apikey
Query
instrumentsArray of stringsrequired

Serial numbers of selected instruments

Example: instruments=QT123456&instruments=QT234567
startstring(date-time)required

Start date and time for loading a range of data. Must be in UTC.

This uses the ISO8601 format. For example, 2023-01-01T00:00:00Z is 1st January 2023 at midnight UTC.

Example: start=2023-01-01T00:00:00Z
endstring(date-time)required

End date and time for loading a range of data. Must be in UTC.

This uses the ISO8601 format. For example, 2023-01-01T00:00:00Z is 1st January 2023 at midnight UTC.

Example: end=2023-01-31T00:00:00Z
periodstring(duration)

Period to recalculate time history samples to.

This cannot be less than the recorded time history period.

This uses the ISO8601 duration format. For example, PT1H is 1 hour, PT1M is 1 minute, PT1S is 1 second.

Example: period=PT1H
valuesArray of strings

Names of selected values to include in results

Default ["LAeq","LCPeak","LAFMax"]
Example: values=LAeq&values=LCPeak&values=LAFMax
curl -i -X GET \
  'https://docs.mycirrus.cloud/_mock/apis/mycirrus-main/data/noise/timehistory?instruments=QT123456%2CQT234567&start=2023-01-01T00%3A00%3A00Z&end=2023-01-31T00%3A00%3A00Z&period=PT1H&values=LAeq%2CLCPeak%2CLAFMax' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/jsonArray [
instrumentstring
typestring
blocksArray of objects(TimeHistoryBlock)
]
Response
application/json
[
  {
    "instrument": "QT123456",
    "type": "LAeq",
    "blocks": [ … ]
  }
]

Fetch frequency bands measurements

Request

Get noise frequency band measurements for the selected instruments and time range.

Optionally choose which bands and weighting to use and what period to recalculate results to.

The possible options are:

  • Band
    • Octave - Includes all octave bands from 31.5Hz to 16KHz
    • Third - Includes all third octave bands from 6.3Hz to 20KHz
  • Frequency Weighting
    • A
    • C
    • Z

 

If you specify an invalid or unavailable band or weighting, the server will respond with an error.
If no band or weighting are specified, the server will return the default results (Octave Z).

The maximum date range per request is 31 days. If you request a longer range, the server will respond with an error.
The default Period is the measurement period as configured in the instrument. See the settings for details.
The period can be set to anything between the measurement period and 1 day. If you request a period outside this range, the server will respond with an error.

Requires an API key with the data.noise:read scope.

Security
apikey
Query
instrumentsArray of stringsrequired

Serial numbers of selected instruments

Example: instruments=QT123456&instruments=QT234567
startstring(date-time)required

Start date and time for loading a range of data. Must be in UTC.

This uses the ISO8601 format. For example, 2023-01-01T00:00:00Z is 1st January 2023 at midnight UTC.

Example: start=2023-01-01T00:00:00Z
endstring(date-time)required

End date and time for loading a range of data. Must be in UTC.

This uses the ISO8601 format. For example, 2023-01-01T00:00:00Z is 1st January 2023 at midnight UTC.

Example: end=2023-01-31T00:00:00Z
periodstring(duration)

Period to recalculate measurement samples to.

This cannot be less than the recorded measurement period.

This uses the ISO8601 duration format. For example, P1D is 1 day, PT1H is 1 hour, PT5M is 5 minutes.

Example: period=PT1H
bandsstring

Choose which set of frequency bands to use

Default "Octave"
Enum"Octave""Third"
Example: bands=Octave
weightingstring

Choose which frequency weighting to apply to the results

Default "Z"
Enum"A""C""Z"
Example: weighting=Z
curl -i -X GET \
  'https://docs.mycirrus.cloud/_mock/apis/mycirrus-main/data/frequency/measurements?instruments=QT123456%2CQT234567&start=2023-01-01T00%3A00%3A00Z&end=2023-01-31T00%3A00%3A00Z&period=PT1H&bands=Octave&weighting=Z' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/jsonArray [
startTimestring(date-time)
endTimestring(date-time)
durationinteger
instrumentstring
overloadboolean
valuesArray of objects
]
Response
application/json
[
  {
    "startTime": "2023-06-14T23:00:00Z",
    "endTime": "2023-06-14T23:15:00Z",
    "duration": 900,
    "instrument": "QT123456",
    "overload": false,
    "values": [ … ]
  }
]

Fetch frequency bands time history

Request

Get noise frequency band time history for the selected instruments and time range.

Optionally choose which bands and weighting to use and what period to recalculate results to.

The maximum date range per request is 1 day. If you request a longer range, the server will respond with an error.
The default Period is 1 second.
The period can be set to anything between the current time history setting and 1 minute. If you request a period outside this range, the server will respond with an error.
You can request data with a period of less than 1 second by using a fractional seconds value in the period. For example, PT0.1S for 100ms.

Requires an API key with the data.noise:read scope.

Security
apikey
Query
instrumentsArray of stringsrequired

Serial numbers of selected instruments

Example: instruments=QT123456&instruments=QT234567
startstring(date-time)required

Start date and time for loading a range of data. Must be in UTC.

This uses the ISO8601 format. For example, 2023-01-01T00:00:00Z is 1st January 2023 at midnight UTC.

Example: start=2023-01-01T00:00:00Z
endstring(date-time)required

End date and time for loading a range of data. Must be in UTC.

This uses the ISO8601 format. For example, 2023-01-01T00:00:00Z is 1st January 2023 at midnight UTC.

Example: end=2023-01-31T00:00:00Z
periodstring(duration)

Period to recalculate time history samples to.

This cannot be less than the recorded time history period.

This uses the ISO8601 duration format. For example, PT1H is 1 hour, PT1M is 1 minute, PT1S is 1 second.

Example: period=PT1H
bandsstring

Choose which set of frequency bands to use

Default "Octave"
Enum"Octave""Third"
Example: bands=Octave
weightingstring

Choose which frequency weighting to apply to the results

Default "Z"
Enum"A""C""Z"
Example: weighting=Z
curl -i -X GET \
  'https://docs.mycirrus.cloud/_mock/apis/mycirrus-main/data/frequency/timehistory?instruments=QT123456%2CQT234567&start=2023-01-01T00%3A00%3A00Z&end=2023-01-31T00%3A00%3A00Z&period=PT1H&bands=Octave&weighting=Z' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/jsonArray [
instrumentstring
typestring
blocksArray of objects(FreqTimeHistoryBlock)
]
Response
application/json
[
  {
    "instrument": "QT123456",
    "type": "Octave",
    "blocks": [ … ]
  }
]

Fetch a list of audio recordings

Request

Get a list of all audio recordings for this instrumetn and time range

Requires an API key with the data.audio:read scope.

Security
apikey
Query
instrumentsArray of stringsrequired

Serial numbers of selected instruments

Example: instruments=QT123456&instruments=QT234567
startstring(date-time)required

Start date and time for loading a range of data. Must be in UTC.

This uses the ISO8601 format. For example, 2023-01-01T00:00:00Z is 1st January 2023 at midnight UTC.

Example: start=2023-01-01T00:00:00Z
endstring(date-time)required

End date and time for loading a range of data. Must be in UTC.

This uses the ISO8601 format. For example, 2023-01-01T00:00:00Z is 1st January 2023 at midnight UTC.

Example: end=2023-01-31T00:00:00Z
curl -i -X GET \
  'https://docs.mycirrus.cloud/_mock/apis/mycirrus-main/data/audio?instruments=QT123456%2CQT234567&start=2023-01-01T00%3A00%3A00Z&end=2023-01-31T00%3A00%3A00Z' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/jsonArray [
idstring
instrumentstring
startTimestring(date-time)
endTimestring(date-time)
triggerStartTimestring(date-time)
triggerEndTimestring(date-time)
triggerNamestring
]
Response
application/json
[
  {
    "id": "3uCLgmZuV1ITGOLOBTzgDm8d9SMX52AixUtpSfEELGYsUQMmZw",
    "instrument": "QT123456",
    "startTime": "2023-06-12T10:27:41",
    "endTime": "2023-06-12T10:28:00",
    "triggerStartTime": "2023-06-12T10:27:42Z",
    "triggerEndTime": "2023-06-12T10:27:55Z",
    "triggerName": "Default"
  }
]

Get an audio recording

Request

Get the audio data for the given recording

Requires an API key with the data.audio:read scope.

Security
apikey
Path
recordingIdstringrequired

The audio recording id to retrieve

Example: xxxxxx-xxxxxx-xxxxxx
Query
formatstring

Choose audio file format and codec

Default "FLAC"
Enum"FLAC""WAV""AAC""OGG"
Example: format=FLAC
curl -i -X GET \
  'https://docs.mycirrus.cloud/_mock/apis/mycirrus-main/data/audio/xxxxxx-xxxxxx-xxxxxx?format=FLAC' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/octet-stream
string(binary)

The audio data encoded in the format specified in the request

Response
No content

Environmental data

Endpoints for retrieving historic environmental data

Operations

Event data

Endpoints for retrieving historic event data

Operations

System health data

Endpoints for retrieving historic system health data

Operations

Webhook management

Webhooks allow you to receive notifications when new data is available. You can configure webhooks via the API itself or via the console.
To create a webhook, go to the API console and click the "Create Webhook" button.

These are the endpoints you can use to manage your webhooks:

Operations

Webhook Messages

Webhooks allow you to receive notifications when new data is available. You can configure webhooks via the API itself or via the console.
To create a webhook, go to the API console and click the "Create Webhook" button.

When a webhook is triggered, a POST request will be sent to the URL you specified. The request will contain a JSON body with the data that triggered the webhook.

When processing the webhook request you must return a 200 OK response to indicate that the data was received successfully.

If a 200 response is not given or the request times out (5 seconds), the webhook will be retried up to 5 times.
To ensure a fast response we recommend you respond immediately and queue any further work to be done later.

If a webhook repeatedly fails you will be notified via email. If it continues to fail it will then be removed.
We cannot guarantee you will get a webhook request for every event so you should occasionally check for new items against the normal API endpoints. When processing events such as new measurements its also recommended to request all data since you last processed it rather than just the 1 new measurement from the request.

These are the types of webhook messages you can receive:

Webhooks