Skip to content

Update API docs: forecasts and self-contained metadata reference #3589

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Baalmart merged 3 commits into from
Jun 7, 2026
Merged

Update API docs: forecasts and self-contained metadata reference #3589

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
07b8069
Update API docs: forecasts and self-contained metadata reference
Baalmart Jun 7, 2026
f3a1045
fix(docs): address review feedback on API docs accuracy and lint
Baalmart Jun 7, 2026
974ae05
fix(docs): escape {GRID_ID} in finding-ids link text to prevent MDX R…
Baalmart Jun 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions src/docs-website/docs/api/for-cities/intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,13 +41,15 @@ If a device belongs to an organisation's private Cohort, it will **not** appear
| Historical measurements | `POST /api/v3/public/analytics/data-download` |
| Spatial heatmap (city) | `GET /api/v2/spatial/heatmaps/{GRID_ID}?token={SECRET_TOKEN}` |
| All available heatmaps | `GET /api/v2/spatial/heatmaps?token={SECRET_TOKEN}` |
| Daily forecasts | `GET /api/v2/predict/daily-forecasting/?grid_id={GRID_ID}&token={SECRET_TOKEN}` |
| Hourly forecasts | `GET /api/v2/predict/hourly-forecasting/?grid_id={GRID_ID}&token={SECRET_TOKEN}` |

---

## Finding your Grid ID

- **Browse the metadata endpoints** at [docs.airqo.net/airqo-rest-api-documentation/api-endpoints/metadata](https://docs.airqo.net/airqo-rest-api-documentation/api-endpoints/metadata)
- **Filter by location** using the `admin_level` query parameter (country, province, or city)
- **Browse the [Metadata API](../reference/metadata.md#grid-summary-with-site-details):** call `GET /api/v2/devices/grids/summary?admin_level=city` to list all city-level grids with their site details
- **Filter by location** using the `admin_level` query parameter (`country`, `province`, `city`, `district`)
- **Example:** The Grid ID for Nairobi is `64b7ac8fd7249f0029feca80`

---
Expand All @@ -60,7 +62,7 @@ If a device belongs to an organisation's private Cohort, it will **not** appear
| Spatial heatmaps | ✅ Free | Base64 PNG with boundary coordinates |
| Historical calibrated data | ✅ Standard+ | Via Analytics API |
| Raw sensor readings | ✅ Standard+ | Via Analytics API |
| Air quality forecasts | ✅ Premium | Via site or device ID from your Grid |
| Air quality forecasts | ✅ Premium | Via `grid_id` or per-site `site_id` — see [Forecast API](../forecasts/overview.md) |

---

Expand All @@ -79,4 +81,5 @@ City authorities already using Grid ID access:
- [Fetch recent measurements →](./recent-measurements.md)
- [Access historical data →](./historical-data.md)
- [Generate spatial heatmaps →](./spatial-heatmaps.md)
- [Get air quality forecasts →](../forecasts/overview.md)
- [Set up your account →](../getting-started/authentication.md)
9 changes: 6 additions & 3 deletions src/docs-website/docs/api/for-partners/intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,12 +33,14 @@ At this time, Cohorts are created and configured by the AirQo team on behalf of

## Your Cohort ID endpoint structure

Once you have your Cohort ID, two endpoints cover your primary data needs:
Once you have your Cohort ID, these endpoints cover your primary data needs:

| Data | Endpoint |
|------|----------|
| Recent measurements (last 7 days) | `GET /api/v2/devices/measurements/cohorts/{COHORT_ID}?token={SECRET_TOKEN}` |
| Historical measurements | `POST /api/v3/public/analytics/data-download` |
| Daily forecasts | `GET /api/v2/predict/daily-forecasting/?cohort_id={COHORT_ID}&token={SECRET_TOKEN}` |
| Hourly forecasts | `GET /api/v2/predict/hourly-forecasting/?cohort_id={COHORT_ID}&token={SECRET_TOKEN}` |

---

Expand All @@ -52,7 +54,7 @@ To change the privacy setting of your Cohort, contact [support@airqo.net](mailto

## Getting your Cohort ID

- **Public Cohorts:** Browse the metadata endpoints at [docs.airqo.net/airqo-rest-api-documentation/api-endpoints/metadata](https://docs.airqo.net/airqo-rest-api-documentation/api-endpoints/metadata)
- **Public Cohorts:** Use the [Metadata API](../reference/metadata.md#list-all-public-cohorts) — call `GET /api/v2/devices/metadata/cohorts` to list all publicly visible cohorts
- **Private Cohorts:** Contact [support@airqo.net](mailto:support@airqo.net) — your Cohort ID will be shared securely

---
Expand All @@ -64,7 +66,7 @@ To change the privacy setting of your Cohort, contact [support@airqo.net](mailto
| Recent hourly measurements | ✅ Free | Last 7 days |
| Historical calibrated data | ✅ Standard+ | Via Analytics API |
| Raw sensor readings | ✅ Standard+ | Via Analytics API |
| Air quality forecasts | ❌ | Not currently available per Cohort ID |
| Air quality forecasts | ✅ Premium | Via `cohort_id` on the [Forecast API](../forecasts/overview.md) |
| Spatial heatmaps | ❌ | Heatmaps use Grid ID |

---
Expand All @@ -73,4 +75,5 @@ To change the privacy setting of your Cohort, contact [support@airqo.net](mailto

- [Fetch recent measurements →](./recent-measurements.md)
- [Access historical data →](./historical-data.md)
- [Get air quality forecasts →](../forecasts/overview.md)
- [Set up your account →](../getting-started/authentication.md)
Loading
Loading