コンテンツにスキップ
Queria Docs
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

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 として別に出します。知らない項目は無視するように実装してください。

このページは役に立ちましたか?