# 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.