> For the complete documentation index, see [llms.txt](https://docs.airqo.net/airqo-rest-api-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.airqo.net/airqo-rest-api-documentation/api-endpoints/metadata.md).

# Metadata

## 1. Get all publicly available Grids

<mark style="color:blue;">`GET`</mark> `https://api.airqo.net/api/v2/devices/metadata/grids`

Retrieve metadata of all publicly available Grids

#### Path Parameters

| Name     | Type   | Description                                          |
| -------- | ------ | ---------------------------------------------------- |
| grid\_id | String | An object ID which is a unique identifier for a Grid |

#### Query Parameters

| Name                                    | Type   | Description        |
| --------------------------------------- | ------ | ------------------ |
| token<mark style="color:red;">\*</mark> | string | the security token |

{% tabs %}
{% tab title="200 " %}

```
{
"success":true,
"message":"Successfull Operation",
"grids":[
{"_id":"662f987f019c3e0013c27a56",
"visibility":true,
"name":"fort_portal",
"admin_level":"city",
"createdAt":"2024-04-29T12:54:23.825Z"},
{"_id":"65e98e11528c9f00133444f8",
"visibility":true,
"name":"ethiopia",
"admin_level":"country",
"createdAt":"2024-03-07T09:51:13.703Z"},
{"_id":"659d036497e611001236cd1b",
"visibility":true,
"name":"gulu_city",
"admin_level":"city",
"createdAt":"2024-01-09T08:27:16.102Z"},
{GRID 4},
{GRID 5},
]
```

{% endtab %}

{% tab title="401: Unauthorized In case of bad requests" %}

```
{"success":false, "message":"Invalid authentication", "error":"Unauthorized."}
```

{% endtab %}
{% endtabs %}

## 2. Get all publicly available Cohorts

<mark style="color:blue;">`GET`</mark> `https://api.airqo.net/api/v2/devices/metadata/cohorts`

Retrieve metadata for all publicly available Cohorts.

#### Path Parameters

| Name       | Type   | Description                                            |
| ---------- | ------ | ------------------------------------------------------ |
| cohort\_id | String | An object ID which is a unique identifier for a Cohort |

#### Query Parameters

| Name                                    | Type   | Description        |
| --------------------------------------- | ------ | ------------------ |
| token<mark style="color:red;">\*</mark> | string | the security token |

{% tabs %}
{% tab title="200 " %}

````
```json
{
    "success": true,
    "message": "There are no records for this search",
    "cohorts": []
}
```
````

{% endtab %}

{% tab title="401: Unauthorized In case of bad requests" %}

```
{"success":false, "message":"Invalid authentication", "error":"Unauthorized."}
```

{% endtab %}
{% endtabs %}

## 3. Get all publicly available Devices

<mark style="color:blue;">`GET`</mark> `https://api.airqo.net/api/v2/devices/metadata/devices`

Retrieve  all publicly available Devices. Obtain essential information about individual devices for precise data retrieval.

#### Path Parameters

| Name       | Type   | Description                                            |
| ---------- | ------ | ------------------------------------------------------ |
| device\_id | String | An object ID which is a unique identifier for a Device |

#### Query Parameters

| Name                                    | Type   | Description        |
| --------------------------------------- | ------ | ------------------ |
| token<mark style="color:red;">\*</mark> | string | the security token |

{% tabs %}
{% tab title="200 " %}

````
```json
{
    "success": true,
    "message": "There are no records for this search",
    "devices": []
}
```
````

{% endtab %}

{% tab title="401: Unauthorized In case of bad requests" %}

```
{"success":false, "message":"Invalid authentication", "error":"Unauthorized."}
```

{% endtab %}
{% endtabs %}

## 4. Get all publicly available Sites

<mark style="color:blue;">`GET`</mark> `https://api.airqo.net/api/v2/devices/metadata/sites`

Retrieve  all publicly available Sites. Access publicly available details about specific air quality monitoring sites.

#### Path Parameters

| Name     | Type   | Description                                          |
| -------- | ------ | ---------------------------------------------------- |
| site\_id | String | An object ID which is a unique identifier for a Site |

#### Query Parameters

| Name                                    | Type   | Description        |
| --------------------------------------- | ------ | ------------------ |
| token<mark style="color:red;">\*</mark> | string | the security token |

{% tabs %}
{% tab title="200 " %}

````
```json
{
    "success": true,
    "message": "There are no records for this search",
    "sites": []
}
```
````

{% endtab %}

{% tab title="401: Unauthorized In case of bad requests" %}

```
{"success":false, "message":"Invalid authentication", "error":"Unauthorized."}
```

{% endtab %}
{% endtabs %}

## 5. Retrieve Site and Device IDs associated with Grid ID

<mark style="color:blue;">`GET`</mark> `https://api.airqo.net/api/v2/devices/grids/{GRID_ID}/generate`

Retrieve  all publicly available Sites. Generate all the site and device IDs associated with a Grid

#### Path Parameters

| Name                                       | Type   | Description                                          |
| ------------------------------------------ | ------ | ---------------------------------------------------- |
| grid\_id<mark style="color:red;">\*</mark> | String | An object ID which is a unique identifier for a Grid |

#### Query Parameters

| Name                                    | Type   | Description        |
| --------------------------------------- | ------ | ------------------ |
| token<mark style="color:red;">\*</mark> | string | the security token |

{% tabs %}
{% tab title="200 " %}

````
```json
{
    "success": true,
    "message": "There are no records for this search",
    "sites": []
}
```
````

{% endtab %}

{% tab title="401: Unauthorized In case of bad requests" %}

```
{"success":false, "message":"Invalid authentication", "error":"Unauthorized."}
```

{% endtab %}
{% endtabs %}

## 6. Retrieve Site and Device IDs associated with Cohort ID

<mark style="color:blue;">`GET`</mark> `https://api.airqo.net/api/v2/devices/cohorts/{COHORT_ID}/generate`

Retrieve  all publicly available Sites. Generate all the site and device IDs associated with a Cohort

#### Path Parameters

| Name                                         | Type   | Description                                            |
| -------------------------------------------- | ------ | ------------------------------------------------------ |
| cohort\_id<mark style="color:red;">\*</mark> | String | An object ID which is a unique identifier for a Cohort |

#### Query Parameters

| Name                                    | Type   | Description        |
| --------------------------------------- | ------ | ------------------ |
| token<mark style="color:red;">\*</mark> | string | the security token |

{% tabs %}
{% tab title="200 " %}

````
```json
{
    "success": true,
    "message": "There are no records for this search",
    "sites": []
}
```
````

{% endtab %}

{% tab title="401: Unauthorized In case of bad requests" %}

```
{"success":false, "message":"Invalid authentication", "error":"Unauthorized."}
```

{% endtab %}
{% endtabs %}

## 7. List All AirQo Sites and their Details for Publicly Available Grids

<mark style="color:blue;">`GET`</mark> `https://api.airqo.net/api/v2/devices/grids/summary`

List all Site Details of publicly available Grids. List details of all existing AirQo Locations

#### Query Parameters

| Name         | Type   | Description                                                                                                                                                     |
| ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| admin\_level | String | This is a filter to narrow your search accordingly. Admin Levels include but are not limited to: country, province, state, village, county, district, city, etc |
| id           | String | the unique ID of a Grid                                                                                                                                         |

#### Response Body

{% tabs %}
{% tab title="200 " %}

<pre><code>```json
{
    "success": true,
    "message": "Successfull Operation",
    "grids": [
{
            "_id": "65e98e11528c9f00133444f8",
            "visibility": true,
            "name": "ethiopia",
            "admin_level": "country",
            "network": "airqo",
            "long_name": "Ethiopia",
            "createdAt": "2024-03-07T09:51:13.703Z",
            "sites": [
                {
                    "_id": "637392727c737c001e785545",
                    "formatted_name": "2R6C+GJF, Jacros - Salite Mehret Rd, Addis Ababa, Ethiopia",
                    "parish": "Bole",
                    "sub_county": "Bole",
                    "city": "Addis Ababa",
                    "region": "Addis Ababa",
                    "country": "Ethiopia",
                    "name": "U.S. Department of State Ethiopia - Addis Ababa",
                    "approximate_latitude": 9.007071093631989,
                    "approximate_longitude": 38.819870427611285,
                    "location_name": "Ethiopia",
                    "search_name": "Addis Ababa",
                    "data_provider": "US Embassy"
                },
                {Site 2},
                {Site 3},
                {Site 4}
                ],
<strong>            "numberOfSites": 6       
</strong><strong>  },
</strong><strong>  {Grid 2},
</strong><strong>  {Grid 3},
</strong><strong>  {Grid 4}
</strong><strong>}
</strong>```
</code></pre>

{% endtab %}

{% tab title="401: Unauthorized In case of bad requests" %}

```
{"success":false, "message":"Invalid authentication", "error":"Unauthorized."}
```

{% endtab %}
{% endtabs %}

## Usage Instructions

Effortlessly integrate metadata retrieval into your applications. Navigate through each section to learn how to utilise the provided endpoints, gaining valuable insights into grids, cohorts, devices, and sites. Enhance your air quality data understanding with detailed metadata, empowering your applications with context and accuracy.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.airqo.net/airqo-rest-api-documentation/api-endpoints/metadata.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.