Noise sensor monitoring API docs

Welcome to the noise-sensors-monitoring API docs

Below are available the API endpoints:

Devices

1. List all devices, with their location details

Endpoint: GET http://localhost:8000/devices/locations
Response: 200 OK
Response format:

[
    {
        "id": "49e879b0-f41a-4524-b383-1ab6f7354ab1",
        "latitude": 0.3476,
        "longitude": 32.5825,
        "city": "Kampala",
        "division": "N/A",
        "parish": "N/A",
        "village": "N/A"
    },
   ...
]

Recordings

1. List recordings for all device locations

Endpoint: GET http://localhost:8000/devices/device_recordings/
Response: 200 OK
Response format

[
    {
        "id": "0e3b59c9-8f97-4d25-92f6-57b31967feef",
        "location_recordings": []
    },
    {
        "id": "916c99c5-5374-4a01-84fa-3411bd4aa977",
        "location_recordings": [
            {
                "id": 10,
                "time_recorded": "2022-03-18T15:32:29.125119+03:00",
                "category": null,
                "audio": "https://url.something.com/audio/SB05/.....wav",
                "triggering_threshold": 70
            },
            ...
        ]
    }
    ...
]

2. List recordings for a particular device location

Endpoint: GET http://localhost:8000/devices/device_recordings/uuid
Sample request: GET http://localhost:8000/devices/device_recordings/6d94fb5b-e284-43e8-987b-f1cd44f070aa
Response: 200 OK
Response format

{
    "id": "916c99c5-5374-4a01-84fa-3411bd4aa977",
    "location_recordings": [
        {
            "id": 10,
            "time_recorded": "2022-03-18T15:32:29.125119+03:00",
            "category": null,
            "audio": "https://url.something.com/audio/SB05/.....wav",
            "triggering_threshold": 70
        },
        ...
    ]
}

3. Edit a recording (mostly used to update its noise category)

Endpoint: PATCH http://localhost:8000/audio/update/id/
Sample request: PATCH http://localhost:8000/audio/update/1/
Sample request body:

{
    "category": 10
}

Response: 200 OK
Response format

{
   "id": 10,
   "time_recorded": "2022-03-18T15:32:29.125119+03:00",
   "category": null,
   "audio": "https://url.something.com/audio/SB05/.....wav",
   "triggering_threshold": 70
}

Analysis and Metrics

1. Location metrics

This is the main endpoint used for retrieving all the locations and metrics. Endpoint: GET http://localhost:8000/devices/location_metrics

2. Noise analysis for all locations (3 days default)

Endpoint: GET http://localhost:8000/analysis/
Response: 200 OK
Response format:

[
    {
        "location": {
            "city": "Entebbe",
            "division": "A",
            "parish": "Lugonjo",
            "village": "Lugonjo",
            "noise_analysis": {
                "day_time_average": 61.301770193756724,
                "day_time_median": 64.63844,
                "highest_day_noise": 91.41908,
                "night_time_average": 8.96655608040201,
                "night_time_median": 0.0,
                "highest_night_noise": 68.70873,
                "night_time_quiet_hours": ""
            }
        }
    },
    ... 
]

2. Upload metrics file

The sensors use this endpoint to upload the metrics text file.

POST http://localhost:8000/analysis/metrics-file/

3. List metrics files

Get a list of the metrics file that were uploaded. Can filter by the number days from today using the past_days query parameter.

GET http://localhost:8000/analysis/list-metrics/SB1001?past_days=14.

4. List hourly metrics

Get a list of the hourly metrics. Can filter by the number days from today using the past_days query parameter.

GET http://localhost:8000/analysis/hourly/SB1001?past_days=2

5. Uptime

Get uptime statistics for a particular sensor. Can filter by the number days from today using the past_days query parameter. NOTE: Use a small past_days number for a fast request. 2 to 4 weeks should be enough.

GET http://localhost:8000/devices/uptime/LOCAL_TESTING_DEVICE?past_weeks=2.

Response format

{
    "uptime_based_on_audio_uploads": {
       "upload_gaps": []
       "uptime": 336.0,
       "previous_downtime": "From 2023-10-19 03:22:01.655109+00:00 to 2023-10-19 04:58:27.070456+00:00"
    }
...
}

• upload_gaps: Gaps of more than 1.5 hours where there were no uploads from the sensor.
• uptime: Number of hours that the sensor has been consistently sending uploads (tex and audio files). Consistent means there was no 24 hours gap between uploads. If null, then the sensor is down.
• previous_downtime: the last time there was a downtime. (Shows the dates)

Testing the endpoints

You can import this postman collection into postman which sets up the different requests for the above endpoints.