Web API リファレンス
api.queria.io のデータセットの一覧・情報・検索の API
https://api.queria.io/v1 は、データセットの一覧・1 件の情報・検索を JSON で返す API です。外部のサイトやアプリ、ブラウザの JavaScript から呼べます(CORS は *)。
curl https://api.queria.io/v1/datasets/queria/e_stat
認証
API トークンを Authorization: Bearer <トークン> で付けると、公開のデータセットに加えて、トークンの持ち主が読める非公開のデータセットも返します。付けなければ匿名で、公開のデータセットだけを返します。トークンの発行は認証を参照してください。
- cookie は読みません。queria.io にログインしていても、トークンを付けなければ匿名として扱います
- 無効なトークンを付けると、匿名に切り替えずに
401を返します - API トークンを、公開するサイトの HTML や JavaScript に書かないでください。 ページを開いた人がトークンを読み取り、非公開のデータセットを読めるようになります。トークンを付けて呼ぶのは、自分のサーバーやパソコンからにしてください。ブラウザから非公開のデータセットを読むときは、ブラウザに渡すトークンを使います
ブラウザに渡すトークン
POST /v1/token に API トークンを送ると、有効期限が 1 時間のトークンを返します。自分のサーバーが API トークンを持ち、ブラウザにはこのトークンだけを渡します。ブラウザはこのトークンを Authorization: Bearer <トークン> で付けて、GET の各エンドポイントと data.queria.io のデータを読めます。
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
{
"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 は受け付けません。
curl "https://api.queria.io/v1/datasets?limit=50"
curl "https://api.queria.io/v1/datasets?limit=50&cursor=<next_cursor の値>"
エラー
/v1/token を除き、エラーはステータスコードと次の形の本文で返します。
{ "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 として別に出します。知らない項目は無視するように実装してください。
