> ## Documentation Index
> Fetch the complete documentation index at: https://data.kushiro.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> curl で k-Data の主要エンドポイントを試す。

このページでは `curl` で `k-Data` の基本的な使い方を確認します。

## 1. Health check

```sh theme={null}
curl https://data.kushiro.app/api/v1/health
```

レスポンス例:

```json theme={null}
{
  "status": "ok",
  "time": "2026-05-06T00:00:00.000Z"
}
```

## 2. Source 一覧を取得する

```sh theme={null}
curl https://data.kushiro.app/api/v1/sources
```

`source_id` は `metrics` / `points` の必須 query parameter です。
まず source 一覧で目的のデータセットを探してください。

## 3. 数値データを取得する

人口・観光客数・財政指標などの数値データは `GET /api/v1/metrics` から取得します。

```sh theme={null}
curl "https://data.kushiro.app/api/v1/metrics?source=kushiro_population_households_monthly&limit=10"
```

期間や metric 名で絞り込む例:

```sh theme={null}
curl "https://data.kushiro.app/api/v1/metrics?source=kushiro_population_households_monthly&metric=population_total&from=2026-01-01&to=2026-12-31"
```

主な query parameter:

| Parameter | 必須  | 説明                                   |
| --------- | --- | ------------------------------------ |
| `source`  | yes | source ID                            |
| `metric`  | no  | metric 名の完全一致                        |
| `from`    | no  | `period.start_date` の下限。`YYYY-MM-DD` |
| `to`      | no  | `period.end_date` の上限。`YYYY-MM-DD`   |
| `town`    | no  | 町名の完全一致                              |
| `age`     | no  | 年齢ラベルの完全一致                           |
| `limit`   | no  | default `1000`、max `10000`           |
| `offset`  | no  | default `0`                          |

## 4. 施設・地点系データを取得する

施設、AED、避難場所、学校、議会だより索引などの施設・地点系データは `GET /api/v1/points` から取得します。

```sh theme={null}
curl "https://data.kushiro.app/api/v1/points?source=kushiro_aed_locations&limit=10"
```

category で絞り込む例:

```sh theme={null}
curl "https://data.kushiro.app/api/v1/points?source=kushiro_aed_locations&category=aed&limit=10"
```

主な query parameter:

| Parameter  | 必須  | 説明                         |
| ---------- | --- | -------------------------- |
| `source`   | yes | source ID                  |
| `category` | no  | point category の完全一致       |
| `limit`    | no  | default `1000`、max `10000` |
| `offset`   | no  | default `0`                |

## Pagination

`metrics` と `points` は共通して `total`, `limit`, `offset` を返します。
次ページを取得するときは `offset` に前回の `offset + limit` を指定してください。

```sh theme={null}
curl "https://data.kushiro.app/api/v1/metrics?source=kushiro_population_households_monthly&limit=1000&offset=1000"
```