FAQs

Welcome to the AirQo API FAQ page! Here, we've compiled a comprehensive list of frequently asked questions to assist you in navigating and utilizing our API effectively.

Deployment and Data Access

Q: Are new sensors automatically added to the data stream upon deployment?

A: Yes, newly deployed sensors are seamlessly integrated into the JSON data stream.

Q: How often are measurements recorded for each device?

A: Measurements are recorded in spaces of minutes but we present an hourly resolution for each unique device.

Q: Can I access historical data for all devices?

A: Absolutely! The API provides access to historical data across all devices.

Q: How can I find the Grid ID for historical measurement stations in Kenya?

A: The Grid ID can be obtained from the endpoint for retrieving publicly available grids. Visit this link for more details. Use the admin_level query parameter to filter results according to your location, such as country, province, or city. For Nairobi, the Grid ID is 64b7ac8fd7249f0029feca80.

Q: Why am I encountering errors when attempting to retrieve data for specific site_id or device_id using Python?

A: Errors may arise due to several reasons, including incorrect API keys or device IDs, network issues, endpoint availability, rate limiting, missing headers, or lack of error handling in your code. Review your request parameters and ensure your network connection is stable. Consult the API documentation for required headers and consider implementing error handling in your code to manage exceptions gracefully.

Q: Why do Site IDs and Device IDs have separate API endpoints in the AirQo API?

A: In the AirQo API, Site IDs and Device IDs serve different purposes and are used in distinct API endpoints to ensure accurate and relevant data retrieval. Site IDs are utilised in endpoints that include /sites, such as GET /sites/{siteId}/recent, which allows users to retrieve air quality measurements for a specific site identified by its Site ID. On the other hand, Device IDs are used in endpoints that contain /devices/, like GET /devices/{deviceId}/recent, enabling users to fetch measurements from a specific device using its Device ID. This separation ensures that users can efficiently query data either by location (using Site IDs) or by the device itself (using Device IDs), depending on their specific needs.

Q: What are the differences between Site ID, Device ID, Grid ID, and Cohort ID in the AirQo API?

A: In the AirQo API, identifying and querying air quality data involves several unique identifiers, each serving a distinct purpose:

• Site ID: Represents a specific location identified by GPS coordinates. It is used to access air quality data from a particular site.

• Device ID: Identifies a single device at a site. Unlike the Site ID, which represents a location, the Device ID specifically identifies the device itself.

• Grid ID: Groups sites based on geographical proximity. This is useful for retrieving data from all sites within a defined area.

• Cohort ID: Groups devices together, regardless of their physical locations. This is ideal for organisations managing devices across various regions, enabling access to data from all grouped devices simultaneously.

Q: What are the distinct API endpoints for Site ID, Device ID, Cohort ID, and Grid ID in the AirQo?

A: In the AirQo API, each unique identifier—Site ID, Device ID, Cohort ID, and Grid ID—is associated with specific endpoints designed to facilitate precise data retrieval. Understanding these differences is crucial for effective utilisation of the API:

• Site ID: Used for accessing data from a specific location. The endpoint structure includes /sites, such as GET /sites/{siteId}/recent.

• Device ID: Enables data access from a specific device. The endpoint path contains /devices/, exemplified by GET /devices/{deviceId}/recent.

• Cohort ID: Allows data retrieval for a group of devices, regardless of their geographical distribution. The endpoint for Cohort ID is structured as GET /cohorts/{cohortId}/recent.

• Grid ID: Facilitates data access for all sites within a defined geographical area. The endpoint for Grid ID is GET /grids/{gridId}/recent.

These distinct endpoints ensure that users can accurately query data based on their specific requirements, whether they need information from a particular site, device, group of devices (Cohort), or a collection of sites within a certain area (Grid).

Data Content and Structure

Q: Why are temperature and humidity measurements not included in the JSON file?

A: Currently excluded intentionally for simplicity. We're open to revisiting based on user needs.

Q: The calibrated value and value for PM2.5 and PM10 are the same; is this intentional?

A: Currently intentional; we're planning to refine this to minimise confusion.

Q: Is the Device_ID unique for every unique device?

A: Yes, the Device_ID is unique for each device. You can expect approximately "24 * days-since-installation" measurements for each unique device.

API Data Grouping

Q: Anytime I load the API link with Grid or Cohort ID, I get access to a JSON with data across all sensors. Is this correct?

A: Yes, loading the API link provides access to a JSON file containing data across all sensors. Utilise appropriate query parameters for customisation.

Q: What is the difference between Grid ID and Cohort ID API access?

A: The Grid ID serves to logically group all sites based on geographical location, while the Cohort ID is designed for grouping devices. Cohorts are particularly useful for organisations managing devices across diverse geographic regions, allowing simultaneous access to data from all devices without the limitations imposed by Grids, which are tailored for specific geographical areas. It's worth noting that a Cohort and Grid may share the same devices, contingent on whether devices within the Cohort belong to a specific Grid. Additionally, if a Cohort owner opts to make their devices private, recent measurements won't be accessible via the Grid ID, as Grid IDs are inherently public-facing, unlike private Cohorts.

Q: How do Cohort ID and Grid ID differ in their usage within the AirQo API endpoints?

A: In the AirQo API, both Cohort ID and Grid ID are utilised to retrieve air quality measurements, but they cater to different organizational structures and geographical scopes:

• Cohort ID: Used to fetch measurements for a group of devices, regardless of their geographical distribution. This is particularly useful for organisations managing devices across various regions, allowing access to data from all devices within a specified Cohort. The endpoint for fetching measurements by Cohort ID is structured as follows: GET /cohorts/{cohortId}/recent. This endpoint enables users to retrieve data from all devices belonging to a specific Cohort.

• Grid ID: Facilitates the retrieval of measurements for all sites within a defined geographical area. Grids are designed to group sites based on their proximity, making it easier to access aggregated data from multiple sites located within the same region. The endpoint for fetching measurements by Grid ID is: GET /grids/{gridId}/recent. This endpoint allows users to obtain data from all sites within a given Grid.

These distinctions ensure that users can tailor their data retrieval according to their specific needs—whether focusing on device groups (using Cohort IDs) or geographical areas (using Grid IDs).

General API Usage

Q: How should I handle pagination when dealing with large datasets?

A: Utilise the page parameter to navigate through result pages. Refer to our pagination guide for detailed instructions.

Legal and Security Concerns

Q: Do you have legal guidance regarding unauthorised access to API tokens?

A: If you encounter any unauthorised access or security concerns, please report them immediately to our support team.

For additional assistance or queries not covered here, feel free to reach out to our support team at [e-mail].