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