Skip to content
/Environmental data

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

Environmental data

Endpoints for retrieving historic environmental data

Operations

Fetch weather data

Request

Get weather measurements for the selected instruments and time range.

Optionally choose what period to recalculate results to.

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 1 minute.
The period can be set to anything between 1 minute 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.enviro: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 data samples to.

This cannot be less than the recorded data period.

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

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

Responses

OK

Bodyapplication/jsonArray [
timestring(date-time)

Time of the sample

instrumentstring

Instrument serial number

windSpeednumber

Wind speed in metres per second

windDirectionnumber

Wind direction in degrees

temperaturenumber

Temperature in degrees Celsius

pressurenumber

Pressure in bar

humiditynumber

Relative humidity as a percentage

precipitationnumber

Precipitation in millimetres per hour

]
Response
application/json
[
  {
    "time": "2023-06-09T01:00:00Z",
    "instrument": "QT123456",
    "windSpeed": 1.55,
    "windDirection": 140.37,
    "temperature": 10.48,
    "pressure": 1.012,
    "humidity": 82,
    "precipitation": 0
  }
]

Fetch particulate data

Request

Get particulates measurements for the selected instruments and time range.

Optionally choose what period to recalculate results to.

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 1 minute.
The period can be set to anything between 1 minute 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.enviro: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 data samples to.

This cannot be less than the recorded data period.

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

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

Responses

OK

Bodyapplication/jsonArray [
startTimestring(date-time)

Time of the sample

durationinteger

Duration of the sample in seconds

instrumentstring

Instrument serial number

pM1number or null

PM1 in micrograms per cubic metre

pM2p5number or null

PM2.5 in micrograms per cubic metre

pM4p25number or null

PM4.25 in micrograms per cubic metre

pM10number or null

PM10 in micrograms per cubic metre

]
Response
application/json
[
  {
    "startTime": "2023-06-08T23:00:00Z",
    "duration": 60,
    "instrument": "SCS-BGX-000",
    "pM1": 3.88,
    "pM2p5": 4.92,
    "pM4p25": 5.51,
    "pM10": 8.95
  }
]

Fetch gas data

Request

Get gases measurements for the selected instruments and time range.

Optionally choose what period to recalculate results to.

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 1 minute.
The period can be set to anything between 1 minute 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.enviro: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 data samples to.

This cannot be less than the recorded data period.

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

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

Responses

OK

Bodyapplication/jsonArray [
startTimestring(date-time)

Time of the sample

durationinteger

Duration of the sample in seconds

instrumentstring

Instrument serial number

conumber or null

Carbon monoxide in parts per billion

cO2number or null

Carbon dioxide in parts per million

h2Snumber or null

Hydrogen sulphide in parts per billion

nonumber or null

Nitric oxide in parts per billion

nO2number or null

Nitrogen dioxide in parts per billion

o3number or null

Ozone in parts per billion

sO2number or null

Sulphur dioxide in parts per billion

vocnumber or null

Volatile organic compounds in parts per billion

]
Response
application/json
[
  {
    "startTime": "2023-06-08T23:00:00Z",
    "duration": 60,
    "instrument": "SCS-BGX-000",
    "co": 207.72,
    "cO2": 507.06,
    "h2S": null,
    "no": 0,
    "nO2": 19.12,
    "o3": null,
    "sO2": null,
    "voc": 493.25
  }
]

Fetch vibration data

Request

Get ground vibration measurements for the selected instruments and time range. Either Peak Particle Velocity (PPV) or Vibration Dose Value (VDV) based on the type parameter.

Optionally choose what period to recalculate results to.

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 1 minute.
The period can be set to anything between 1 minute 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.enviro:read scope.

Security
apikey
Path
typestringrequired

The type of data to return (PPV or VDV)

Enum"PPV""VDV"
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 data samples to.

This cannot be less than the recorded data period.

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

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

Responses

OK

Bodyapplication/json
One of:

List of PPV results

Array [
startTimestring(date-time)

Time of the sample

durationinteger

Duration of the sample in seconds

instrumentstring

Instrument serial number

vMaxXnumber or null

Peak particle velocity (PPV) in X direction in mm/s

vMaxYnumber or null

Peak particle velocity (PPV) in Y direction in mm/s

vMaxZnumber or null

Peak particle velocity (PPV) in Z direction in mm/s

fDomXnumber or null

Dominant frequency in X direction in Hz

fDomYnumber or null

Dominant frequency in Y direction in Hz

fDomZnumber or null

Dominant frequency in Z direction in Hz

]
Response
application/json
[]

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