---
title: Web API リファレンス
description: api.queria.io のデータセットの一覧・情報・検索の API
---

`https://api.queria.io/v1` は、データセットの一覧・1 件の情報・検索を JSON で返す API です。外部のサイトやアプリ、ブラウザの JavaScript から呼べます（CORS は `*`）。

```bash
curl https://api.queria.io/v1/datasets/queria/e_stat
```

## 認証

API トークンを `Authorization: Bearer <トークン>` で付けると、公開のデータセットに加えて、トークンの持ち主が読める非公開のデータセットも返します。付けなければ匿名で、公開のデータセットだけを返します。トークンの発行は[認証](/authentication)を参照してください。

- cookie は読みません。queria.io にログインしていても、トークンを付けなければ匿名として扱います
- 無効なトークンを付けると、匿名に切り替えずに `401` を返します
- **API トークンを、公開するサイトの HTML や JavaScript に書かないでください。** ページを開いた人がトークンを読み取り、非公開のデータセットを読めるようになります。トークンを付けて呼ぶのは、自分のサーバーやパソコンからにしてください。ブラウザから非公開のデータセットを読むときは、[ブラウザに渡すトークン](#ブラウザに渡すトークン)を使います

### ブラウザに渡すトークン

`POST /v1/token` に API トークンを送ると、有効期限が 1 時間のトークンを返します。自分のサーバーが API トークンを持ち、ブラウザにはこのトークンだけを渡します。ブラウザはこのトークンを `Authorization: Bearer <トークン>` で付けて、`GET` の各エンドポイントと data.queria.io のデータを読めます。

```bash
curl https://api.queria.io/v1/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d subject_token=qk_... \
  -d subject_token_type=urn:ietf:params:oauth:token-type:access_token
```

```json
{
  "access_token": "eyJ...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

- 本文は `application/x-www-form-urlencoded` で送ります（OAuth 2.0 Token Exchange、RFC 8693 の形）
- 返したトークンで読めるのは、元の API トークンで読めるデータセットと同じです。読めるデータセットを絞る `scope`・`audience`・`resource` は受け付けません（`400` の `invalid_target`）
- 有効期限は 1 時間です。元の API トークンの期限がそれより早いときは、その期限までになります。`expires_in` の秒数が切れる前に、サーバーで作り直してブラウザに渡してください
- 使えるのは個人の API トークンだけです。団体の API トークンは `400` の `invalid_grant` になります
- レートリミットは元の API トークンと共有します
- エラーは OAuth の形（`{ "error": "invalid_grant", "error_description": "..." }`）で返します。`429` と `503` には `Retry-After` ヘッダーが付きます

## レートリミット

上限は目安で、変わることがあります。

| 呼び出し元 | 上限 |
| --- | --- |
| 匿名 | IP アドレスごとに 1 分 60 回 |
| API トークンあり | トークンごとに 1 分 600 回 |

上限を超えると `429` と `Retry-After` ヘッダーを返します。

## エンドポイント

| メソッドとパス | 返すもの |
| --- | --- |
| `GET /v1/datasets` | データセットの一覧 |
| `GET /v1/datasets/{handle}/{name}` | 1 件のデータセットの情報 |
| `GET /v1/datasets/{handle}/{name}/declaration` | publish されたデータセットの宣言（テーブル・列の説明など） |
| `GET /v1/search?q=` | データセット・テーブル・列の検索 |
| `GET /v1/openapi.json` | OpenAPI の仕様書 |
| `POST /v1/token` | ブラウザに渡すトークン（[ブラウザに渡すトークン](#ブラウザに渡すトークン)） |

データセットは `queria/e_stat` のような完全修飾名（handle と name）で指定します。短い名前（`e_stat` だけ）は受け付けません。

### データセットの情報

`GET /v1/datasets/{handle}/{name}` はデータセットの情報を、ほかの項目で包まずにそのまま返します。一覧と検索の `datasets` の各要素も同じ項目を持ちます。

| 項目 | 内容 |
| --- | --- |
| `handle`・`name` | 持ち主とデータセットの名前 |
| `qualified_name` | 完全修飾名 |
| `title`・`description`・`keywords` | タイトル・説明・キーワード |
| `catalog_url` | DuckLake のカタログの URL。DuckDB で `ATTACH` するときに使います |
| `versioned_catalog_url` | 今のバージョンに固定したカタログの URL |
| `page_url` | queria.io のデータセットのページ |
| `visibility` | 公開範囲（`public`・`private`・`premium`） |
| `licenses` | ライセンスの一覧（`id`・`title`・`url`）。ライセンスが登録されていないデータセットでは項目ごと省きます |
| `updated_at`・`bytes` | 更新日時・サイズ |
| `pro_required` | プレミアムのデータセットを、読む権限の無いトークン（または匿名）で取得したときだけ `true` が付きます。このとき `catalog_url` を `ATTACH` してもデータは読めません |

`GET /v1/datasets/{handle}/{name}/declaration` は宣言の JSON をそのまま返します。宣言を持たないデータセットでは `null` を返します。

### 一覧と検索の応答

`GET /v1/datasets` は `datasets`（データセットの配列）と `next_cursor` を返します。`GET /v1/search` は、検索語の `query`、データセットに当たった `datasets`、テーブルと列に当たった `entries`、`next_cursor` を返します。

検索は次のパラメータを受け付けます。`q` は、ほかの絞り込みを指定したときは省略できます。

| パラメータ | 内容 |
| --- | --- |
| `q` | 検索語。空白で区切った語をすべて含むものを返します |
| `type` | 当たり先を `dataset`・`table`・`column` のどれかに限定します |
| `column`・`entity` | この列名・識別子を持つテーブルに限定します。繰り返して指定できます（それぞれ 8 個まで） |
| `geo` | `true` で位置情報の列を持つテーブルに限定します |
| `area` | 地域コード（6 桁または 5 桁）の地域を収録するテーブルに限定します |
| `year` | 西暦の年を期間に含むテーブルに限定します |
| `theme` | このテーマのテーブルに限定します |
| `min_rows`・`max_rows` | 行数がこの範囲（両端を含む）のテーブルに限定します |
| `value` | その言葉を含む値を持つ列があるテーブルに限定します。繰り返して指定できます（8 個まで） |

### ページネーション

一覧と検索は `limit` で件数を指定し（1〜200、既定は 50）、応答の `next_cursor` を次のリクエストの `cursor` に渡します。`next_cursor` が `null` なら最後のページです。`cursor` の中身は変わることがあるので、組み立てずに受け取った値をそのまま渡してください。`offset` は受け付けません。

```bash
curl "https://api.queria.io/v1/datasets?limit=50"
curl "https://api.queria.io/v1/datasets?limit=50&cursor=<next_cursor の値>"
```

## エラー

`/v1/token` を除き、エラーはステータスコードと次の形の本文で返します。

```json
{ "error": { "code": "not_found", "message": "Dataset not found" } }
```

| ステータスコード | 意味 |
| --- | --- |
| `400` | パラメータが正しくない（`cursor` が読めない、`limit` が範囲外、`offset` を指定したなど） |
| `401` | API トークンが無効 |
| `404` | データセットやパスが無い |
| `405` | 使えないメソッドを使った（`POST` は `/v1/token` だけ） |
| `429` | レートリミットに達した |
| `500` | サーバー側のエラー |
| `503` | API トークンを一時的に確認できなかった。`Retry-After` の秒数を待ってから送り直してください |

## バージョン

`/v1` の応答には項目を追加することがあります。項目の削除や名前・型の変更は `/v2` として別に出します。知らない項目は無視するように実装してください。
