Skip to content
Queria Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Web API reference

The api.queria.io API for listing, reading and searching datasets

https://api.queria.io/v1 returns the dataset list, a single dataset and search results as JSON. You can call it from other sites and apps, and from JavaScript in the browser (CORS is *).

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

Authentication

Send an API token as Authorization: Bearer <token> to get the private datasets the token’s owner can read, in addition to public datasets. Without a token, requests are anonymous and return public datasets only. To create a token, see Authentication.

  • Cookies are not read. Even if you are signed in to queria.io, a request without a token is anonymous
  • An invalid token returns 401 instead of falling back to anonymous access
  • Do not put an API token in the HTML or JavaScript of a public site. Anyone who opens the page can read the token and use it to read your private datasets. Send requests with a token only from your own server or computer. To read private datasets from the browser, use a browser token

Browser tokens

POST /v1/token takes an API token and returns a token that expires in one hour. Keep the API token on your own server and pass only this token to the browser. The browser sends it as Authorization: Bearer <token> to read the GET endpoints and data on 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
}
  • Send the body as application/x-www-form-urlencoded (OAuth 2.0 Token Exchange, RFC 8693)
  • The returned token reads the same datasets as the API token. scope, audience and resource to narrow the datasets are not supported (400 with invalid_target)
  • The token expires in one hour, or when the API token expires if that comes first. Request a new one on your server before expires_in seconds pass and pass it to the browser
  • Only personal API tokens are accepted. Organization API tokens return 400 with invalid_grant
  • The token shares the rate limit of the API token
  • Errors use the OAuth shape ({ "error": "invalid_grant", "error_description": "..." }). 429 and 503 include a Retry-After header

Rate limits

The limits are guidelines and may change.

Caller Limit
Anonymous 60 requests per minute per IP address
With an API token 600 requests per minute per token

Over the limit, the API returns 429 with a Retry-After header.

Endpoints

Method and path Returns
GET /v1/datasets The dataset list
GET /v1/datasets/{handle}/{name} One dataset
GET /v1/datasets/{handle}/{name}/declaration The published declaration of the dataset (descriptions of tables and columns)
GET /v1/search?q= Search across datasets, tables and columns
GET /v1/openapi.json The OpenAPI specification
POST /v1/token A token to pass to the browser (Browser tokens)

Datasets are named by their fully qualified name (handle and name), such as queria/e_stat. Short names such as e_stat alone are not accepted.

A dataset

GET /v1/datasets/{handle}/{name} returns the dataset object directly, without a wrapping field. Each item in datasets of the list and search responses has the same fields.

Field Content
handle, name Owner and name of the dataset
qualified_name Fully qualified name
title, description, keywords Title, description and keywords
catalog_url URL of the DuckLake catalog, for ATTACH in DuckDB
versioned_catalog_url Catalog URL pinned to the current version
page_url The dataset page on queria.io
visibility Visibility (public, private or premium)
licenses Licenses (id, title, url). Omitted when the dataset has no registered license
updated_at, bytes Last update and size
pro_required true only when a premium dataset is fetched anonymously or with a token that cannot read it. In that case, attaching catalog_url does not give access to the data

GET /v1/datasets/{handle}/{name}/declaration returns the declaration JSON as is. For a dataset without a declaration, it returns null.

List and search responses

GET /v1/datasets returns datasets (an array of datasets) and next_cursor. GET /v1/search returns the search terms in query, matching datasets in datasets, matching tables and columns in entries, and next_cursor.

Search accepts these parameters. q can be omitted when another filter is given.

Parameter Content
q Search terms. Returns results that contain all space-separated terms
type Restricts results to dataset, table or column
column, entity Restricts to tables that have this column name or identifier. Repeatable (up to 8 each)
geo true restricts to tables with a location column
area Restricts to tables that cover this area code (6 or 5 digits)
year Restricts to tables whose period includes this year
theme Restricts to tables in this theme
min_rows, max_rows Restricts to tables whose row count is in this range (both ends included)
value Restricts to tables with a column holding a value that contains this text. Repeatable (up to 8)

Pagination

The list and search take limit (1 to 200, default 50). Pass next_cursor from the response as cursor in the next request. A null next_cursor means the last page. The content of a cursor may change, so pass the value you received without building it yourself. offset is not accepted.

curl "https://api.queria.io/v1/datasets?limit=50"
curl "https://api.queria.io/v1/datasets?limit=50&cursor=<value of next_cursor>"

Errors

Except for /v1/token, errors come with a status code and a body of this form.

{ "error": { "code": "not_found", "message": "Dataset not found" } }
Status Meaning
400 Invalid parameters (such as an unreadable cursor, a limit out of range, or offset)
401 Invalid API token
404 No such dataset or path
405 A method the path does not accept (POST is accepted only by /v1/token)
429 Rate limit reached
500 Server error
503 The API token could not be verified temporarily. Wait for the number of seconds in Retry-After and retry

Versioning

Fields may be added to /v1 responses. Removing fields or changing their names or types happens in a new /v2. Ignore fields you do not know.

Was this page helpful?