{ "openapi": "3.1.0", "info": { "title": "HDX APIs", "version": "2.11.4", "description": "OpenAPI specification for HDX APIs as exposed by the Humanitarian Data Exchange (HDX).\n\n## Tabular Data Endpoints\n\nThe HDX **Tabular Data Endpoints (TDE)** provide programmatic access to tabular datasets hosted on HDX. Powered by the CKAN DataStore extension, they support real-time querying, customizable filters, and dataset joins. **Authentication required for all TDE requests on HDX.**\n\n- **`datastore_search`** \u2014 simple filters, browsing data, or building lightweight applications\n- **`datastore_search_sql`** \u2014 analytical purposes or when multiple conditions and calculations are required\n- **`datastore_info`** \u2014 schema information about a resource, including column names and data types\n\n## Metadata endpoints\n\nCatalog search for discovering datasets on HDX. No authentication required for public data.\n\n- **`package_search`** \u2014 search datasets by keyword, filter, or facet\n\nCKAN actions accept parameters as either query string parameters (GET) or a JSON body (POST). Both methods are equivalent.\n\n> **Note:** This specification documents behavior as described in the [CKAN 2.11 documentation](https://docs.ckan.org/en/2.11/maintaining/datastore.html). Some parameter interactions (e.g. `filters` vs `q` in `datastore_search`) have nuanced behavior that is not fully captured here.", "contact": { "name": "HDX Team", "url": "https://data.humdata.org" }, "license": { "name": "Creative Commons Attribution International", "url": "https://creativecommons.org/licenses/by/4.0/" } }, "servers": [ { "url": "https://data.humdata.org/api/3/action", "description": "HDX Production" } ], "paths": { "/datastore_search": { "get": { "operationId": "datastore_search_get", "summary": "Search a DataStore resource", "description": "Query rows from a DataStore resource with optional filtering, full-text search, sorting, and pagination.\n\nPass parameters as query string arguments (GET) or as a JSON body (POST).", "tags": [ "DataStore" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "resource_id", "in": "query", "required": true, "schema": { "title": "Resource Id", "type": "string" }, "description": "The `id` or alias of the resource to search. Required." }, { "name": "filters", "in": "query", "required": false, "schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Filters" }, "description": "Matching conditions as a dictionary of `{field: value}` pairs. Rows must match all conditions. Example: `{\"country\": \"Uganda\"}`." }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Q" }, "description": "Full-text search query. Pass a string to search across all fields, or a dictionary of `{field: query}` to target specific fields. Note: behavior differs subtly from `filters` \u2014 `q` uses full-text ranking while `filters` performs exact matching." }, { "name": "full_text", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Full Text" }, "description": "Full-text search query applied across all fields. Similar to `q` with a string value, but always searches all fields. Cannot be combined with `q`." }, { "name": "distinct", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "title": "Distinct" }, "description": "Return only unique rows. Defaults to `false`." }, { "name": "plain", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": true, "title": "Plain" }, "description": "Treat the `q` query as plain text (no special FTS operators). Set to `false` to use PostgreSQL tsquery syntax. Defaults to `true`." }, { "name": "language", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "english", "title": "Language" }, "description": "Language used for full-text search stemming. Defaults to `english`." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": 100, "title": "Limit" }, "description": "Maximum number of rows to return. Defaults to `100`." }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Offset" }, "description": "Number of rows to skip before returning results. Used for pagination." }, { "name": "fields", "in": "query", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Fields" }, "description": "Columns to include in the response. Pass a comma-separated string or a list. Defaults to all fields." }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sort" }, "description": "Comma-separated list of fields to sort by, with optional `asc`/`desc` direction. Example: `\"fieldname1 asc, fieldname2 desc\"`." }, { "name": "include_total", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": true, "title": "Include Total" }, "description": "Include the total number of matching rows in the response. Defaults to `true`." }, { "name": "total_estimation_threshold", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Total Estimation Threshold" }, "description": "When `include_total` is `true` and the estimated row count exceeds this threshold, CKAN returns an estimated total rather than an exact count. Set to `null` (default) to always return an exact count." }, { "name": "records_format", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "objects", "lists", "csv", "tsv" ], "type": "string" }, { "type": "null" } ], "default": "objects", "title": "Records Format" }, "description": "Format for the returned records. `objects` returns a list of dicts, `lists` returns a list of lists, `csv` and `tsv` return delimited strings. Defaults to `objects`." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatastoreSearchResponse" } } } }, "403": { "description": "Forbidden \u2014 API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the resource_id does not exist in the DataStore.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests \u2014 rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error \u2014 unexpected server-side failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-hideTryItPanel": true }, "post": { "operationId": "datastore_search_post", "summary": "Search a DataStore resource (POST)", "description": "Identical to the GET form. Use POST to pass parameters as a JSON body, which is useful for large `filters` or `fields` payloads.", "tags": [ "DataStore" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatastoreSearchParams" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatastoreSearchResponse" } } } }, "403": { "description": "Forbidden \u2014 API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the resource_id does not exist in the DataStore.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests \u2014 rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error \u2014 unexpected server-side failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-hideTryItPanel": true } }, "/datastore_search_sql": { "get": { "operationId": "datastore_search_sql_get", "summary": "Query a DataStore resource with SQL", "description": "Execute a SQL `SELECT` statement against one or more DataStore resources. Useful for aggregations, joins, and complex filtering that `datastore_search` cannot express.\n\nOnly `SELECT` statements are permitted.", "tags": [ "DataStore" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sql", "in": "query", "required": true, "schema": { "title": "Sql", "type": "string" }, "description": "A single SQL `SELECT` statement to execute against the DataStore. Required. Only `SELECT` statements are permitted \u2014 `INSERT`, `UPDATE`, `DELETE`, and DDL statements are not allowed. Table names correspond to resource IDs (e.g. `SELECT * FROM \"\"`)." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatastoreSearchSqlResponse" } } } }, "403": { "description": "Forbidden \u2014 API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the resource_id does not exist in the DataStore.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests \u2014 rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error \u2014 unexpected server-side failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-hideTryItPanel": true }, "post": { "operationId": "datastore_search_sql_post", "summary": "Query a DataStore resource with SQL (POST)", "description": "Identical to the GET form. Use POST for long SQL statements.", "tags": [ "DataStore" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatastoreSearchSqlParams" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatastoreSearchSqlResponse" } } } }, "403": { "description": "Forbidden \u2014 API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the resource_id does not exist in the DataStore.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests \u2014 rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error \u2014 unexpected server-side failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-hideTryItPanel": true } }, "/datastore_info": { "get": { "operationId": "datastore_info_get", "summary": "Get DataStore resource metadata", "description": "Retrieve field definitions, type information, and size/count metadata for a DataStore resource.", "tags": [ "DataStore" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "resource_id", "in": "query", "required": true, "schema": { "title": "Resource Id", "type": "string" }, "description": "The `id` or alias of the DataStore resource to describe. Required." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatastoreInfoResponse" } } } }, "403": { "description": "Forbidden \u2014 API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the resource_id does not exist in the DataStore.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests \u2014 rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error \u2014 unexpected server-side failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-hideTryItPanel": true }, "post": { "operationId": "datastore_info_post", "summary": "Get DataStore resource metadata (POST)", "description": "Identical to the GET form.", "tags": [ "DataStore" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatastoreInfoParams" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatastoreInfoResponse" } } } }, "403": { "description": "Forbidden \u2014 API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the resource_id does not exist in the DataStore.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests \u2014 rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error \u2014 unexpected server-side failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-hideTryItPanel": true } }, "/package_search": { "get": { "operationId": "package_search_get", "summary": "Search datasets", "description": "Search for datasets (packages) using Solr query syntax. Supports filtering, faceting, sorting, and pagination. No authentication required for public data.\n\nPass parameters as query string arguments (GET) or as a JSON body (POST).", "tags": [ "Catalog" ], "security": [ {}, { "ApiKeyAuthCatalog": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "*:*", "title": "Q" }, "description": "Solr search query. Supports Solr syntax. Defaults to `\"*:*\"` (all datasets)." }, { "name": "fq", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Fq" }, "description": "Solr filter query. Restricts results without affecting relevance scoring." }, { "name": "fq_list", "in": "query", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Fq List" }, "description": "Additional filter queries as a list. Each entry is ANDed with `fq`." }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "score desc, metadata_modified desc", "title": "Sort" }, "description": "Sort order as a Solr sort string. Defaults to `\"score desc, metadata_modified desc\"`." }, { "name": "rows", "in": "query", "required": false, "schema": { "anyOf": [ { "maximum": 1000, "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": 10, "title": "Rows" }, "description": "Maximum number of datasets to return. Defaults to `10`, maximum `1000`." }, { "name": "start", "in": "query", "required": false, "schema": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Start" }, "description": "Offset into the result set. Used for pagination." }, { "name": "facet", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "true", "title": "Facet" }, "description": "Enable faceted results. Defaults to `\"true\"`." }, { "name": "facet.mincount", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Facet.Mincount" }, "description": "Minimum count for a facet value to be included in the response." }, { "name": "facet.limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": 50, "title": "Facet.Limit" }, "description": "Maximum number of values returned per facet field. Defaults to `50`." }, { "name": "facet.field", "in": "query", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Facet.Field" }, "description": "Fields to facet on." }, { "name": "include_drafts", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "title": "Include Drafts" }, "description": "Include draft datasets in results. Requires authentication as the owning user or org admin. Defaults to `false`." }, { "name": "include_deleted", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "title": "Include Deleted" }, "description": "Include deleted datasets in results. Defaults to `false`." }, { "name": "include_private", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "title": "Include Private" }, "description": "Include private datasets in results. Requires authentication as a member of the owning organisation. Defaults to `false`." }, { "name": "use_default_schema", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "title": "Use Default Schema" }, "description": "Return results using the default package schema rather than any custom schema configured on the instance. Defaults to `false`." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageSearchResponse" } } } }, "403": { "description": "Forbidden \u2014 API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the requested action or endpoint does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests \u2014 rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error \u2014 unexpected server-side failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-hideTryItPanel": true }, "post": { "operationId": "package_search_post", "summary": "Search datasets (POST)", "description": "Identical to the GET form. Use POST to pass parameters as a JSON body, which is useful for long `fq_list` or `facet.field` values.", "tags": [ "Catalog" ], "security": [ {}, { "ApiKeyAuthCatalog": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageSearchParams" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageSearchResponse" } } } }, "403": { "description": "Forbidden \u2014 API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the requested action or endpoint does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests \u2014 rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error \u2014 unexpected server-side failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-hideTryItPanel": true } } }, "components": { "schemas": { "DatastoreSearchParams": { "properties": { "resource_id": { "description": "The `id` or alias of the resource to search. Required.", "title": "Resource Id", "type": "string" }, "filters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Matching conditions as a dictionary of `{field: value}` pairs. Rows must match all conditions. Example: `{\"country\": \"Uganda\"}`.", "title": "Filters" }, "q": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Full-text search query. Pass a string to search across all fields, or a dictionary of `{field: query}` to target specific fields. Note: behavior differs subtly from `filters` \u2014 `q` uses full-text ranking while `filters` performs exact matching.", "title": "Q" }, "full_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Full-text search query applied across all fields. Similar to `q` with a string value, but always searches all fields. Cannot be combined with `q`.", "title": "Full Text" }, "distinct": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "description": "Return only unique rows. Defaults to `false`.", "title": "Distinct" }, "plain": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": true, "description": "Treat the `q` query as plain text (no special FTS operators). Set to `false` to use PostgreSQL tsquery syntax. Defaults to `true`.", "title": "Plain" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "english", "description": "Language used for full-text search stemming. Defaults to `english`.", "title": "Language" }, "limit": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": 100, "description": "Maximum number of rows to return. Defaults to `100`.", "title": "Limit" }, "offset": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Number of rows to skip before returning results. Used for pagination.", "title": "Offset" }, "fields": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "string" }, { "type": "null" } ], "default": null, "description": "Columns to include in the response. Pass a comma-separated string or a list. Defaults to all fields.", "title": "Fields" }, "sort": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Comma-separated list of fields to sort by, with optional `asc`/`desc` direction. Example: `\"fieldname1 asc, fieldname2 desc\"`.", "title": "Sort" }, "include_total": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": true, "description": "Include the total number of matching rows in the response. Defaults to `true`.", "title": "Include Total" }, "total_estimation_threshold": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "When `include_total` is `true` and the estimated row count exceeds this threshold, CKAN returns an estimated total rather than an exact count. Set to `null` (default) to always return an exact count.", "title": "Total Estimation Threshold" }, "records_format": { "anyOf": [ { "enum": [ "objects", "lists", "csv", "tsv" ], "type": "string" }, { "type": "null" } ], "default": "objects", "description": "Format for the returned records. `objects` returns a list of dicts, `lists` returns a list of lists, `csv` and `tsv` return delimited strings. Defaults to `objects`.", "title": "Records Format" } }, "required": [ "resource_id" ], "title": "DatastoreSearchParams", "type": "object" }, "DatastoreSearchLinks": { "properties": { "start": { "description": "URL to the first page of results with the same parameters.", "title": "Start", "type": "string" }, "next": { "description": "URL to the next page of results.", "title": "Next", "type": "string" } }, "required": [ "start", "next" ], "title": "DatastoreSearchLinks", "type": "object" }, "DatastoreSearchResult": { "properties": { "resource_id": { "description": "The resource ID that was queried.", "title": "Resource Id", "type": "string" }, "fields": { "description": "List of field descriptor objects, each with `id` and `type` keys.", "items": { "additionalProperties": true, "type": "object" }, "title": "Fields", "type": "array" }, "offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "The offset used in the query.", "title": "Offset" }, "limit": { "description": "The limit used in the query.", "title": "Limit", "type": "integer" }, "filters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Filters applied to the query.", "title": "Filters" }, "include_total": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Echoed from the request parameter. Indicates whether `total` is included.", "title": "Include Total" }, "records_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Echoed from the request parameter. Format used for `records`.", "title": "Records Format" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Total number of matching rows. Present when `include_total` is `true`.", "title": "Total" }, "total_was_estimated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether the total count was estimated rather than exact.", "title": "Total Was Estimated" }, "total_estimation_threshold": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Row count threshold above which total estimation is used. `null` when estimation is not configured.", "title": "Total Estimation Threshold" }, "records": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "items": { "items": {}, "type": "array" }, "type": "array" }, { "type": "string" } ], "description": "Matching rows. Shape depends on `records_format`.", "title": "Records" }, "_links": { "$ref": "#/components/schemas/DatastoreSearchLinks", "description": "Pagination helper URLs. Always present \u2014 `next` contains the URL for the next page of results." } }, "required": [ "resource_id", "fields", "limit", "records", "_links" ], "title": "DatastoreSearchResult", "type": "object" }, "DatastoreSearchResponse": { "properties": { "help": { "description": "URL to the API documentation for this action.", "title": "Help", "type": "string" }, "success": { "description": "Whether the request succeeded.", "title": "Success", "type": "boolean" }, "result": { "$ref": "#/components/schemas/DatastoreSearchResult" } }, "required": [ "help", "success", "result" ], "title": "DatastoreSearchResponse", "type": "object" }, "DatastoreSearchSqlParams": { "properties": { "sql": { "description": "A single SQL `SELECT` statement to execute against the DataStore. Required. Only `SELECT` statements are permitted \u2014 `INSERT`, `UPDATE`, `DELETE`, and DDL statements are not allowed. Table names correspond to resource IDs (e.g. `SELECT * FROM \"\"`).", "title": "Sql", "type": "string" } }, "required": [ "sql" ], "title": "DatastoreSearchSqlParams", "type": "object" }, "DatastoreSearchSqlResult": { "properties": { "sql": { "description": "The SQL query echoed back from the request.", "title": "Sql", "type": "string" }, "fields": { "description": "List of field descriptor objects for the result columns, each with `id` and `type` keys.", "items": { "additionalProperties": true, "type": "object" }, "title": "Fields", "type": "array" }, "records": { "description": "List of result row objects.", "items": { "additionalProperties": true, "type": "object" }, "title": "Records", "type": "array" }, "records_truncated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Present and `true` if the result set was truncated at the server-side 32,000-row limit.", "title": "Records Truncated" } }, "required": [ "sql", "fields", "records" ], "title": "DatastoreSearchSqlResult", "type": "object" }, "DatastoreSearchSqlResponse": { "properties": { "help": { "description": "URL to the API documentation for this action.", "title": "Help", "type": "string" }, "success": { "description": "Whether the request succeeded.", "title": "Success", "type": "boolean" }, "result": { "$ref": "#/components/schemas/DatastoreSearchSqlResult" } }, "required": [ "help", "success", "result" ], "title": "DatastoreSearchSqlResponse", "type": "object" }, "DatastoreInfoParams": { "properties": { "resource_id": { "description": "The `id` or alias of the DataStore resource to describe. Required.", "title": "Resource Id", "type": "string" } }, "required": [ "resource_id" ], "title": "DatastoreInfoParams", "type": "object" }, "DatastoreInfoResult": { "properties": { "meta": { "anyOf": [ { "$ref": "#/components/schemas/DatastoreResourceMeta" }, { "type": "null" } ], "default": null, "description": "Resource metadata including aliases, row count, and size information." }, "fields": { "description": "List of field descriptor objects. Each contains `id`, `type`, and optionally `schema` with index and uniqueness information.", "items": { "additionalProperties": true, "type": "object" }, "title": "Fields", "type": "array" } }, "required": [ "fields" ], "title": "DatastoreInfoResult", "type": "object" }, "DatastoreResourceMeta": { "properties": { "aliases": { "description": "List of aliases defined for this resource.", "items": { "type": "string" }, "title": "Aliases", "type": "array" }, "count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Total number of rows in the resource table.", "title": "Count" }, "db_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Total size of the DataStore database in bytes (all tables, not just this resource).", "title": "Db Size" }, "id": { "description": "The resource ID.", "title": "Id", "type": "string" }, "idx_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Size of indexes on this resource table in bytes.", "title": "Idx Size" }, "size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Size of this resource table in bytes.", "title": "Size" }, "table_type": { "anyOf": [ { "enum": [ "BASE TABLE", "VIEW", "FOREIGN", "LOCAL TEMPORARY" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "PostgreSQL table type for this resource.", "title": "Table Type" } }, "required": [ "aliases", "id" ], "title": "DatastoreResourceMeta", "type": "object" }, "DatastoreInfoResponse": { "properties": { "help": { "description": "URL to the API documentation for this action.", "title": "Help", "type": "string" }, "success": { "description": "Whether the request succeeded.", "title": "Success", "type": "boolean" }, "result": { "$ref": "#/components/schemas/DatastoreInfoResult" } }, "required": [ "help", "success", "result" ], "title": "DatastoreInfoResponse", "type": "object" }, "PackageSearchParams": { "properties": { "q": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "*:*", "description": "Solr search query. Supports Solr syntax. Defaults to `\"*:*\"` (all datasets).", "title": "Q" }, "fq": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Solr filter query. Restricts results without affecting relevance scoring.", "title": "Fq" }, "fq_list": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Additional filter queries as a list. Each entry is ANDed with `fq`.", "title": "Fq List" }, "sort": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "score desc, metadata_modified desc", "description": "Sort order as a Solr sort string. Defaults to `\"score desc, metadata_modified desc\"`.", "title": "Sort" }, "rows": { "anyOf": [ { "maximum": 1000, "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": 10, "description": "Maximum number of datasets to return. Defaults to `10`, maximum `1000`.", "title": "Rows" }, "start": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Offset into the result set. Used for pagination.", "title": "Start" }, "facet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "true", "description": "Enable faceted results. Defaults to `\"true\"`.", "title": "Facet" }, "facet.mincount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Minimum count for a facet value to be included in the response.", "title": "Facet.Mincount" }, "facet.limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": 50, "description": "Maximum number of values returned per facet field. Defaults to `50`.", "title": "Facet.Limit" }, "facet.field": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Fields to facet on.", "title": "Facet.Field" }, "include_drafts": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "description": "Include draft datasets in results. Requires authentication as the owning user or org admin. Defaults to `false`.", "title": "Include Drafts" }, "include_deleted": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "description": "Include deleted datasets in results. Defaults to `false`.", "title": "Include Deleted" }, "include_private": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "description": "Include private datasets in results. Requires authentication as a member of the owning organisation. Defaults to `false`.", "title": "Include Private" }, "use_default_schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "description": "Return results using the default package schema rather than any custom schema configured on the instance. Defaults to `false`.", "title": "Use Default Schema" } }, "title": "PackageSearchParams", "type": "object" }, "PackageSearchResult": { "properties": { "count": { "description": "Total number of datasets matching the query.", "title": "Count", "type": "integer" }, "results": { "description": "List of matching dataset objects.", "items": { "additionalProperties": true, "type": "object" }, "title": "Results", "type": "array" }, "sort": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Sort string echoed from the request.", "title": "Sort" }, "facets": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Legacy facet counts. Prefer `search_facets`.", "title": "Facets" }, "search_facets": { "additionalProperties": true, "description": "Facet counts keyed by field name. Each entry has a `title` and an `items` list of `{name, display_name, count}` objects.", "title": "Search Facets", "type": "object" }, "facet_pivot": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Pivot facet results, if requested.", "title": "Facet Pivot" }, "facet_queries": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Facet query results, if requested.", "title": "Facet Queries" }, "expanded": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Expanded results, if requested.", "title": "Expanded" } }, "required": [ "count", "results", "search_facets" ], "title": "PackageSearchResult", "type": "object" }, "PackageSearchResponse": { "properties": { "help": { "description": "URL to the API documentation for this action.", "title": "Help", "type": "string" }, "success": { "description": "Whether the request succeeded.", "title": "Success", "type": "boolean" }, "result": { "$ref": "#/components/schemas/PackageSearchResult" } }, "required": [ "help", "success", "result" ], "title": "PackageSearchResponse", "type": "object" }, "ErrorResponse": { "properties": { "success": { "default": false, "description": "Always false for error responses.", "title": "Success", "type": "boolean" }, "error": { "additionalProperties": true, "description": "Error detail object. Always contains a '__type' string. 403/404 errors include a 'message'; validation (409) errors instead carry structured 'query'/'info' fields.", "title": "Error", "type": "object" } }, "required": [ "error" ], "title": "ErrorResponse", "type": "object" } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "HDX API token. Required for all Tabular Data Endpoint requests, including public resources." }, "ApiKeyAuthCatalog": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "HDX API token. Optional \u2014 public dataset search needs no authentication; a token is only required to include private or draft datasets." } } } }