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
401instead 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,audienceandresourceto narrow the datasets are not supported (400withinvalid_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_inseconds pass and pass it to the browser - Only personal API tokens are accepted. Organization API tokens return
400withinvalid_grant - The token shares the rate limit of the API token
- Errors use the OAuth shape (
{ "error": "invalid_grant", "error_description": "..." }).429and503include aRetry-Afterheader
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.
