# Sensor — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Monitor real-time and historical air quality data from thousands of sensors across different locations, filtering by area, country, sensor type, or custom criteria. Access current readings and archived datasets to track pollution patterns and analyze air quality trends over time.

**Category:** Weather | **Website:** [airsofia.info/](https://airsofia.info/) | **Docs:** [parse.bot/marketplace/1a9b23d8-8952-4a51-af05-f7eb83368afe/sensor-community-api](https://parse.bot/marketplace/1a9b23d8-8952-4a51-af05-f7eb83368afe/sensor-community-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-sensor-community-api-1a9b23d8/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_archive_files

Lists available historical archive files for a specific year and optionally a date. Returns an object with the archive URL and a list of CSV file names available. When a date is specified, lists individual sensor CSV files for that day. When only a year is given, lists date folders.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `date` | string | No | Optional date folder in YYYY-MM-DD format (e.g. 2024-01-15). When provided, lists files for that specific date. |
| `year` | string | Yes | Year folder (e.g. 2024, 2023). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-sensor-community-api-1a9b23d8/get_archive_files \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"<string>","year":"<string>"}'
```

### get_current_sensors_by_area

Fetches current sensor readings filtered by geographic area using a lat/lon center point and radius in kilometers. Returns an array of sensor reading objects including location, sensor metadata, and measurement values. Paginates as a single page; all matching sensors within the radius are returned in one response.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `latitude` | string | No | Latitude of the center point. |
| `longitude` | string | No | Longitude of the center point. |
| `radius` | string | No | Search radius in kilometers. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-sensor-community-api-1a9b23d8/get_current_sensors_by_area \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"latitude":"<string>","longitude":"<string>","radius":"<string>"}'
```

### get_current_sensors_by_country

Fetches all current sensor readings for a given two-letter country code. Returns an array of sensor reading objects. Large countries may return thousands of readings in one response.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country_code` | string | No | Two-letter country code (e.g. BG, DE, FR, PL, NL, RU). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-sensor-community-api-1a9b23d8/get_current_sensors_by_country \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country_code":"<string>"}'
```

### get_current_sensors_by_type

Fetches current sensor readings filtered by sensor type/model name. Returns an array of sensor reading objects worldwide for that sensor type. Common types include SDS011 (particulate matter), BME280 (temperature/humidity/pressure), PMS7003, DHT22, SPS30.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sensor_type` | string | No | Sensor model name (e.g. SDS011, BME280, BMP280, DHT22, PMS7003, SPS30). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-sensor-community-api-1a9b23d8/get_current_sensors_by_type \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sensor_type":"<string>"}'
```

### get_map_overview_data

Retrieves global sensor data summary used to render map layers. Returns a large array of sensor data points for either dust (particulate matter) or temperature measurements worldwide. Response can be very large (thousands of entries).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `data_type` | string | No | Type of data to retrieve. Accepted values: 'dust', 'temp'. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-sensor-community-api-1a9b23d8/get_map_overview_data \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data_type":"<string>"}'
```

### get_sensor_latest_readings

Fetches the latest measurements for a specific sensor by its numeric sensor ID. Returns an array of recent reading objects for that sensor. The sensor_id can be obtained from readings returned by the area, country, or type endpoints (sensor.id field).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sensor_id` | string | Yes | Numeric ID of the sensor (e.g. 82250). Obtain from sensor.id in area/country/type query results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-sensor-community-api-1a9b23d8/get_sensor_latest_readings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sensor_id":"<string>"}'
```

### get_sensors_by_multiple_filters

Fetches sensor readings combining multiple filter parameters including country, sensor type, and geographic area. At least one filter parameter must be provided. All specified filters are applied simultaneously (AND logic).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country_code` | string | No | Two-letter country code filter (e.g. BG, DE). |
| `latitude` | string | No | Latitude for area filter. Must be provided together with longitude and radius. |
| `longitude` | string | No | Longitude for area filter. Must be provided together with latitude and radius. |
| `radius` | string | No | Radius in kilometers for area filter. Must be provided together with latitude and longitude. |
| `sensor_type` | string | No | Sensor type filter (e.g. SDS011, BME280). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-sensor-community-api-1a9b23d8/get_sensors_by_multiple_filters \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country_code":"<string>","latitude":"<string>","longitude":"<string>","radius":"<string>","sensor_type":"<string>"}'
```