Finding IDs

To use the AirQo API, you need the right identifier for your data source. This page explains how to find Cohort IDs, Grid IDs, Site IDs, and Device IDs.

---

Cohort ID

A Cohort ID groups your organisation's devices together. Cohorts are managed by AirQo.

How to find your Cohort ID:

• Public Cohorts: Use the Metadata API — List all cohorts endpoint to browse all publicly visible cohorts
• Private Cohorts: Contact support@airqo.net — your Cohort ID will be shared securely once your organisation's Cohort is set up

A Cohort ID looks like: 64b9c7d5e3f82b0014c5a123

Network-wide data without a Cohort of your own

The public cohort has a fixed, readable Cohort ID — airqo-public — that you can use wherever an endpoint takes a Cohort ID. See Public Cohort →.

---

Grid ID

A Grid ID represents a geographical area (typically a city or district). Grids are public.

How to find your Grid ID:

1. Call the grid summary endpoint: GET /api/v2/devices/grids/summary
2. Use the admin_level=city query parameter to filter to city-level grids
3. Locate your city by long_name and copy its _id value

Known Grid IDs (examples):

City	Grid ID
Nairobi	64b7ac8fd7249f0029feca80

For other cities, use the Metadata API to browse all available grids.

---

Site ID

A Site ID identifies a specific physical monitoring location.

How to find Site IDs:

• Call the grid generate endpoint (GET /api/v2/devices/grids/{GRID_ID}/generate) to list every site ID and device ID within a grid
• Call the Metadata API — List all sites to browse all public monitoring sites
• Or call the recent measurements endpoint for your Grid and collect the site_id field from each measurement record

A Site ID looks like: 64f7b3e8c9d25a0013f2d456

Don't know which site to use for a specific place?

Not every neighbourhood or landmark has a monitoring site named after it. Two options:

• Programmatically: use the Find the nearest sites to a coordinate endpoint — pass a latitude/longitude and get back the nearest sites sorted by distance.
• In the app: the Near You feature in the AirQo Mobile App does the same thing using your phone's GPS.

---

Device ID and Device Name

A Device ID uniquely identifies a sensor unit. Device names follow the pattern airqo_XXXXX.

How to find Device IDs:

• Call any measurements endpoint and look at the device_id and device fields in each measurement record
• The device field (e.g. airqo_bx2847) is the device name — pass it as device_names in Analytics API requests
• The device_id field (e.g. 65c8d4a2f1b45c0012a3e789) can be passed as device_ids in Analytics API requests
• Forecasts are scoped by Site ID (site_id), not Device ID — see Forecast API →

---

ID format reference

Identifier	Format	Example
Cohort ID	24-char hex string	64b9c7d5e3f82b0014c5a123
Grid ID	24-char hex string	64b7ac8fd7249f0029feca80
Site ID	24-char hex string	64f7b3e8c9d25a0013f2d456
Device ID	24-char hex string	65c8d4a2f1b45c0012a3e789
Device Name	airqo_XXXXX	airqo_bx2847

---

Browsing via the Metadata API

The Metadata API provides dedicated endpoints for discovering every public resource:

What you want	Endpoint
Browse all grids	GET /api/v2/devices/metadata/grids
Browse grids by city/country	GET /api/v2/devices/grids/summary?admin_level=city
Look up one grid	GET /api/v2/devices/metadata/grids/{GRID_ID}
Sites in a grid	GET /api/v2/devices/grids/{GRID_ID}/generate
Browse all cohorts	GET /api/v2/devices/metadata/cohorts
Sites and devices in a cohort	GET /api/v2/devices/cohorts/{COHORT_ID}/generate
Browse all sites	GET /api/v2/devices/metadata/sites
Browse all devices	GET /api/v2/devices/metadata/devices

---

Still can't find your ID?

Contact support@airqo.net with your organisation's name or the city/region you are monitoring. The team can look up the correct IDs for you.