Skip to main content

Quick Start

This page gets you to your first successful API response in under five minutes.

Prerequisites checklist​

Before you begin, make sure you have:

  • An AirQo account at nexus.airqo.net
  • An API client created under Profile → API
  • A SECRET TOKEN (access token) generated for that client
  • (Recommended) Your server's public IP address added to the client's IP Addresses. This is optional, but it stops automatic security checks from blocking your server. Add it now, or later if your requests get blocked (see Blocked Requests →)
  • A Cohort ID or Grid ID to query (see Finding IDs →)
More security options

You can also enable the Client Secret, restrict tokens by origin, scope them to specific Grids/Cohorts, and set access schedules. See Security Enhancements → for a full guide.

Your first request​

Fetch recent measurements for a Cohort​

Replace YOUR_COHORT_ID and YOUR_SECRET_TOKEN with your actual values:

curl -X GET \
  "https://api.airqo.net/api/v2/devices/measurements/cohorts/YOUR_COHORT_ID?token=YOUR_SECRET_TOKEN"

Fetch recent measurements for a Grid (city)​

curl -X GET \
  "https://api.airqo.net/api/v2/devices/measurements/grids/YOUR_GRID_ID?token=YOUR_SECRET_TOKEN"

A successful response looks like this:

{
  "success": true,
  "message": "successfully returned the measurements",
  "meta": {
    "total": 168,
    "skip": 0,
    "limit": 30,
    "page": 1,
    "pages": 6
  },
  "measurements": [
    {
      "device": "airqo_bx2847",
      "device_id": "65c8d4a2f1b45c0012a3e789",
      "site_id": "64f7b3e8c9d25a0013f2d456",
      "time": "2025-09-25T14:00:00.000Z",
      "pm2_5": { "value": 23.45 },
      "pm10": { "value": 31.82 },
      "frequency": "hourly"
    }
  ]
}

Understand the response​

FieldWhat it tells you
successWhether the request succeeded
meta.totalTotal matching measurements
meta.pagesHow many pages of results exist
measurements[].timeISO 8601 timestamp of the reading
measurements[].pm2_5.valuePM2.5 in μg/m³
measurements[].pm10.valuePM10 in μg/m³

For the full response reference, see Response Structure →.

What to do next​

You have confirmed that your credentials work. Now choose the path that matches your use case: