Category-List-API.md

+The Category List API can be used to fetch a list of focus topics and categories from the ClimateScan database. Authorization for this endpoint is required. Please refer to the User Login API for more information on providing authorization data.
+
+| Attribute | Value |
+| --- | --- |
+| URL | https://www.climatescan.org/api/v1/categories/list |
+| Supported methods | `GET` |
+| Authorization required | Yes |
+| Response type | JSON |
+
+## Request
+
+A request to the Category List API must include the `Authorization` header. Basic authorization is used to provide the username and password.
+
+No other request data is required.
+
+For example, given the username `demo` and password `p@55w0rd`:
+
+```
+POST https://www.climatescan.org/api/v1/categories/list
+Authorization: Basic ZGVtbzpwQDU1dzByZA==
+```
+
+In JavaScript, the request would look as follows.
+
+```javascript
+fetch('https://www.climatescan.org/api/v1/categories/list', {
+    method: 'POST', 
+    headers: {
+        'Authorization': `Basic ${btoa('demo:p@55w0rd')}`,
+    },
+})
+.then(res => res.json());
+```
+
+## Response
+
+If the username or password were incorrect, the endpoint may return 401 Unauthorized.
+
+If the user was successfully authenticated, then the endpoint may return a 200 OK response with a JSON body. The JSON body represents a list of categories. Each entry is structured as follows.
+
+| Attribute | Type | Description | Example value |
+| --------- | ---- | ----------- | ------------- |
+| `cat_id`  | `int` | ID of the category. | `"1"` |
+| `user_id` | `int` | ID of the user that created the category. | `"439"` |
+| `focustopic_id` | `int` | ID of the focus topic. Each category is assigned to a single focus topic. A single focus topic can have one or more categories. | `"5"` or `null` |
+| `focustopic_name` | `str` | Name of the focus topic. | `"Air quality"` |
+| `parent_category_id` | `int` | ID of the parent category. This field is optional and may be NULL. | `"1"` |
+| `name` | `str` | Name of the category. | `"Air and noise pollution"` |
+| `name_nl` | `str, null` | Dutch translation of the English category name. This field is optional and may be NULL. | `"Lucht- en geluidsoverlast"` or `null` |
+| `color` | `str` | Color code in HEX for this category. Please note that the `#` character is included in this value. | `"#171DFF"` |
+| `created_at` | `str` | Date this category was created, in `Y-m-d H:i:s` format. | `"2019-06-15 19:08:06"` |
+
+Example response:
+
+```json
+HTTP/2 200
+Content-Type: application/json
+
+[
+  {
+    "cat_id": "102",
+    "user_id": "679",
+    "focustopic_id": "5",
+    "parent_category_id": null,
+    "name": "Air and noise pollution",
+    "name_nl": "Lucht- en geluidsoverlast",
+    "color": "#171DFF",
+    "created_at": "2019-12-19 10:51:21",
+    "focustopic_name": "Air quality"
+  },
+  ...
+]
+```
+
+## Example code
+
+The following code can be used to group categories by their focus topic.
+
+```javascript
+const focusTopics = await fetch('https://www.climatescan.org/api/v1/categories/list', {
+    method: 'POST', 
+    headers: {
+        'Authorization': `Basic ${btoa('demo:p@55w0rd')}`,
+    },
+})
+.then(response => response.json())
+.then(rawCategories => rawCategories.reduce((prev, current) => {
+    if (!prev[current.focustopic_id]) {
+        prev[current.focustopic_id] = {
+            id: current.focustopic_id,
+            name: current.focustopic_name,
+            items: [],
+        };
+    }
+
+    prev[current.focustopic_id].items.push(current);
+
+    return prev;
+}, {}));
+```
+
+The output will be a dictionary in the following form:
+
+```json
+[
+    {
+        "id": "focustopic_id",
+        "name": "focustopic_name",
+        "items": [],  # list of category objects related to the given focus topic
+    }
+]
+```
\ No newline at end of file