# Dropdown

Lists of the regions, districts, divisions and areas that exist in the current fiscal year, and the fiscal years, months and report dates that have data. They are meant for building filters and menus.

Base URL: `https://tm-api.devinpearson.me`

## Get dashboard filters

`GET /api/dropdown/dashboard-filters`

Filter options for dashboard (districts, fiscal years, dates, etc.). Successful reads are shared-cacheable for approximately 60 seconds. Cache keys include the complete request URL and query string, and responses vary by Origin. Requests with latest=true and error responses use Cache-Control: no-store.

**Query parameters**

- `fiscalYear` (string, optional): Fiscal year (YYYY-YYYY) whose months to list; defaults to the current fiscal year
- `fiscalMonth` (integer, optional): Fiscal month (1 = July). With fiscalYear, adds that month's report dates. Takes precedence over month.
- `month` (integer, optional): Calendar month (1 = January), as an alternative to fiscalMonth

**Returns**

- `success` (enum) One of: `true`.
- `data` (object)
  - `fiscalYears` (array of objects)
    - `value` (string)
    - `label` (string)
  - `months` (array of objects): Months with data in the fiscal year
    - `value` (integer)
    - `label` (string)
    - `month` (integer)
  - `dates` (array of objects): Report dates in the month; sent only when a fiscal year and a month are given
    - `value` (string)
    - `label` (string)
    - `date_value` (string)
  - `districts` (array of objects)
    - `value` (string)
    - `label` (string)
    - `district` (string)
- `metadata` (object)
  - `fiscal_year_count` (integer)
  - `month_count` (integer)
  - `date_count` (integer)
  - `district_count` (integer)
  - `last_updated` (timestamp)

**Errors**

- `422`: fiscalMonth is not between 1 and 12
- `500`: Internal server error

**Example request**

```bash
curl "https://tm-api.devinpearson.me/api/dropdown/dashboard-filters"
```

**Example response**

```json
{
  "success": true,
  "data": {
    "fiscalYears": [
      {
        "value": "string",
        "label": "string"
      }
    ],
    "months": [
      {
        "value": 0,
        "label": "string",
        "month": 0
      }
    ],
    "dates": [
      {
        "value": "string",
        "label": "string",
        "date_value": "string"
      }
    ],
    "districts": [
      {
        "value": "string",
        "label": "string",
        "district": "74"
      }
    ]
  },
  "metadata": {
    "fiscal_year_count": 0,
    "month_count": 0,
    "date_count": 0,
    "district_count": 0,
    "last_updated": "2026-11-19T04:30:00.000Z"
  }
}
```

## Get regions table

`GET /api/dropdown/regions/table`

Regions derived from the districts table for dropdown/table display. Successful reads are shared-cacheable for approximately 60 seconds. Cache keys include the complete request URL and query string, and responses vary by Origin. Requests with latest=true and error responses use Cache-Control: no-store.

**Returns**

- `success` (enum) One of: `true`.
- `data` (array of objects)
  - `value` (string): The value to send back as a filter
  - `label` (string): Display text, e.g. "District 74"
  - `region` (string)
- `metadata` (object)
  - `timestamp` (timestamp)
  - `count` (integer): Number of options in data
  - `last_updated` (timestamp)

**Errors**

- `422`: A path or query parameter has an invalid value
- `500`: Internal server error

**Example request**

```bash
curl "https://tm-api.devinpearson.me/api/dropdown/regions/table"
```

**Example response**

```json
{
  "success": true,
  "data": [
    {
      "value": "string",
      "label": "string",
      "region": "11"
    }
  ],
  "metadata": {
    "timestamp": "2026-11-19T04:30:00.000Z",
    "count": 0,
    "last_updated": "2026-11-19T04:30:00.000Z"
  }
}
```

## Get districts table

`GET /api/dropdown/districts/table`

Districts from the districts table for dropdown/table display. Successful reads are shared-cacheable for approximately 60 seconds. Cache keys include the complete request URL and query string, and responses vary by Origin. Requests with latest=true and error responses use Cache-Control: no-store.

**Returns**

- `success` (enum) One of: `true`.
- `data` (array of objects)
  - `value` (string): The value to send back as a filter
  - `label` (string): Display text, e.g. "District 74"
  - `district` (string)
  - `region` (nullable string)
- `metadata` (object)
  - `timestamp` (timestamp)
  - `count` (integer): Number of options in data
  - `last_updated` (timestamp)

**Errors**

- `422`: A path or query parameter has an invalid value
- `500`: Internal server error

**Example request**

```bash
curl "https://tm-api.devinpearson.me/api/dropdown/districts/table"
```

**Example response**

```json
{
  "success": true,
  "data": [
    {
      "value": "string",
      "label": "string",
      "district": "74",
      "region": "11"
    }
  ],
  "metadata": {
    "timestamp": "2026-11-19T04:30:00.000Z",
    "count": 0,
    "last_updated": "2026-11-19T04:30:00.000Z"
  }
}
```

## Get divisions table

`GET /api/dropdown/divisions/table`

Divisions from the divisions table for dropdown/table display. Successful reads are shared-cacheable for approximately 60 seconds. Cache keys include the complete request URL and query string, and responses vary by Origin. Requests with latest=true and error responses use Cache-Control: no-store.

**Query parameters**

- `district` (string, optional): Only options in this district

**Returns**

- `success` (enum) One of: `true`.
- `data` (array of objects)
  - `value` (string): The value to send back as a filter
  - `label` (string): Display text, e.g. "District 74"
  - `district` (nullable string)
  - `division` (string)
- `metadata` (object)
  - `timestamp` (timestamp)
  - `count` (integer): Number of options in data
  - `district` (string): The district filter applied, or "all"
  - `last_updated` (timestamp)

**Errors**

- `422`: A path or query parameter has an invalid value
- `500`: Internal server error

**Example request**

```bash
curl "https://tm-api.devinpearson.me/api/dropdown/divisions/table"
```

**Example response**

```json
{
  "success": true,
  "data": [
    {
      "value": "string",
      "label": "string",
      "district": "74",
      "division": "A"
    }
  ],
  "metadata": {
    "timestamp": "2026-11-19T04:30:00.000Z",
    "count": 0,
    "district": "74",
    "last_updated": "2026-11-19T04:30:00.000Z"
  }
}
```

## Get areas table

`GET /api/dropdown/areas/table`

Areas from the areas table for dropdown/table display. Successful reads are shared-cacheable for approximately 60 seconds. Cache keys include the complete request URL and query string, and responses vary by Origin. Requests with latest=true and error responses use Cache-Control: no-store.

**Query parameters**

- `district` (string, optional): Only options in this district
- `division` (string, optional): Only areas in this division

**Returns**

- `success` (enum) One of: `true`.
- `data` (array of objects)
  - `value` (string): The value to send back as a filter
  - `label` (string): Display text, e.g. "District 74"
  - `district` (nullable string)
  - `division` (nullable string)
  - `area` (string)
- `metadata` (object)
  - `timestamp` (timestamp)
  - `count` (integer): Number of options in data
  - `district` (string): The district filter applied, or "all"
  - `division` (string): The division filter applied, or "all"
  - `last_updated` (timestamp)

**Errors**

- `422`: A path or query parameter has an invalid value
- `500`: Internal server error

**Example request**

```bash
curl "https://tm-api.devinpearson.me/api/dropdown/areas/table"
```

**Example response**

```json
{
  "success": true,
  "data": [
    {
      "value": "string",
      "label": "string",
      "district": "74",
      "division": "A",
      "area": "01"
    }
  ],
  "metadata": {
    "timestamp": "2026-11-19T04:30:00.000Z",
    "count": 0,
    "district": "74",
    "division": "A",
    "last_updated": "2026-11-19T04:30:00.000Z"
  }
}
```
