Sensor Data

The sensor_data app handles integration with continuous monitoring (CM) providers. It allows the platform to fetch and display live sensor measurements and alerting data from third-party providers on a per-site basis.

Currently supported providers:

• Sensirion — device-level methane concentration, wind speed, and wind direction measurements, plus site-level emission alerting data.
• LongPath — site-level emission event alerting data and daily rolling averages.

Site sensor configuration

Each site has an optional sensor_config JSON field (Site.sensor_config) that controls which provider integrations are active for that site. This field can be set during site import (see Site operations) or edited directly in the admin.

Supported fields

Field	Type	Description
sensors	Array of objects	List of individual sensor devices linked to the site. Each object must contain id (device identifier) and provider (e.g. sensirion). Used for device-level sensor data retrieval.
sensirion_site_id	string	The Sensirion platform site ID. When set, the site will display Sensirion alerting data (emission events and rates) in the timeline and detail views.
longpath_site_id	string	The LongPath platform site ID. When set, the site will display LongPath alerting data (emission events and rates) and daily rolling averages in the timeline and detail views.

Example

{
    "sensors": [
        {"id": "device-abc-123", "provider": "sensirion"},
        {"id": "device-def-456", "provider": "sensirion"}
    ],
    "sensirion_site_id": "SITE-001",
    "longpath_site_id": "LP-001"
}

All fields are optional. An empty object {} is the default.

Provider configuration

Before sensor data can be fetched, the provider must be configured at the company level via the Django admin.

Sensirion

Create a SensirionConfig record linked to the company, then add one or more SensirionConfigCredentials entries with:

• sensor_api_key — used for device measurement endpoints
• alerting_api_key — used for site emission/alerting endpoints

Multiple credential sets are supported. The system will try each one until it finds credentials that can access the requested devices or site.

LongPath

Create a LongpathConfig record linked to the company with:

• api_key — the LongPath API key

Feature flags

Sensor data visibility in the frontend is controlled by user/company flags (see Flags and Switches):

• enable_sensor_data — required for all sensor data plots on the site detail page (Sensirion alerting, device measurements).
• enable_longpath_data — required for LongPath alerting and rolling averages on both the site detail page and the timeline view. On the detail page, this flag works in conjunction with enable_sensor_data.

Data types

The sensor data API supports three data types, specified via the data_type parameter when creating a request:

Data type	Description	Supported providers
sensor	Device-level measurements (methane concentration, wind direction, wind speed). Data is fetched in 6-hour windows and deduplicated.	Sensirion only
alerts	Site-level emission events with associated emission rates over time.	Sensirion, LongPath
rolling_averages	Daily rolling averages including daily, 7-day, and 90-day rollup averages plus 7-day trend data.	LongPath only

API flow

Sensor data retrieval is asynchronous due to the potentially long response times from external providers.

1. Create a request

POST /api/v1/sensor-data

Request body:

Field	Type	Required	Description
site_id	UUID	Yes	The site to fetch data for.
emission_record_id	UUID	No	An emission record to center the date range around (±60 days).
start_date	datetime	No	Explicit start of the date range.
end_date	datetime	No	Explicit end of the date range.
data_type	string	No	sensor (default), alerts, or rolling_averages.
data_provider	string	No	sensirion (default) or longpath.

Either emission_record_id or both start_date and end_date must be provided.

Validation constraints:

• data_type=sensor with data_provider=longpath is not supported.
• data_type=rolling_averages is only supported with data_provider=longpath.

The response contains a request_id. Duplicate requests within 10 minutes return the existing request ID.

2. Poll for results

For sensor data:

GET /api/v1/sensor-data/<request_id>/sensor

For alerting data:

GET /api/v1/sensor-data/<request_id>/alerting

For rolling averages:

GET /api/v1/sensor-data/<request_id>/rolling-averages

The response includes a status field:

Status	Description
PENDING	Request is queued.
IN_PROGRESS	Request is being processed by a Celery worker.
COMPLETED	Data is available in response_data.
FAILED	An error occurred. Details in error_message.

Response format — sensor data

[
    {
        "device_id": "device-abc-123",
        "measurements": [
            {
                "timestamp": "2024-01-15T12:00:00+00:00",
                "methane_concentration": 2.1,
                "wind_direction": 180.0,
                "wind_speed": 3.5
            }
        ]
    }
]

Response format — alerting data

[
    {
        "emission_id": "evt-123",
        "emission": {
            "emissionId": "evt-123",
            "emissionStatus": "Active",
            "emissionEventType": "Continuous",
            "startTime": "2024-01-10T00:00:00Z",
            "endTime": "2024-01-15T00:00:00Z",
            "emissionConfirmedAt": "2024-01-10T01:00:00Z",
            "lastUpdatedAt": "2024-01-15T00:00:00Z",
            "lastEmissionRate": 1.5,
            "emissionSource": "Tank battery",
            "emissionLatitude": null,
            "emissionLongitude": null
        },
        "rates": [
            {
                "timestamp": "2024-01-10T00:00:00Z",
                "measurement": 1.2
            }
        ]
    }
]

Response format — rolling averages

[
    {
        "daily_rolling_average_id": "ra-456",
        "site_id": "LP-001",
        "site_name": "Well Pad A",
        "node_name": "Node-1",
        "report_date_utc": "2024-01-15T00:00:00Z",
        "daily_rollup_average_kghr": 0.85,
        "seven_day_rollup_average_kghr": 1.2,
        "ninety_day_rollup_average_kghr": null,
        "seven_day_trend_kghr": -0.15,
        "seven_day_trend_percent": -11.1
    }
]

Field	Type	Description
daily_rolling_average_id	string	Unique identifier for the record.
site_id	string	LongPath site ID.
site_name	string	LongPath site name.
node_name	string	Name of the monitoring node.
report_date_utc	datetime	Date of the report (UTC).
daily_rollup_average_kghr	float | null	Daily average emission rate in kg/hr.
seven_day_rollup_average_kghr	float | null	7-day rolling average emission rate in kg/hr.
ninety_day_rollup_average_kghr	float | null	90-day rolling average emission rate in kg/hr.
seven_day_trend_kghr	float | null	7-day trend in kg/hr (positive = increasing).
seven_day_trend_percent	float | null	7-day trend as a percentage.

Scheduled cleanup

Old sensor data requests are automatically cleaned up by the remove_old_sensor_data_requests Celery task, which deletes requests older than 30 days.