| { |
| "openapi": "3.0.3", |
| "info": { |
| "title": "UNESCO Datahub Explore API", |
| "version": "v2.1", |
| "description": "UNESCO Datahub API for accessing datasets, records, and exports from data.unesco.org" |
| }, |
| "servers": [ |
| { |
| "url": "https://data.unesco.org/api/explore/v2.1" |
| } |
| ], |
| "security": [ |
| { |
| "apikey": [] |
| } |
| ], |
| "tags": [ |
| { |
| "name": "Catalog", |
| "description": "API to enumerate datasets" |
| }, |
| { |
| "name": "Dataset", |
| "description": "API to work on records" |
| } |
| ], |
| "paths": { |
| "/catalog/datasets": { |
| "get": { |
| "summary": "Query catalog datasets", |
| "operationId": "getDatasets", |
| "tags": ["Catalog"], |
| "description": "Retrieve available datasets from UNESCO Datahub.", |
| "parameters": [ |
| { |
| "name": "select", |
| "in": "query", |
| "description": "Select specific fields or expressions", |
| "schema": {"type": "string"} |
| }, |
| { |
| "name": "where", |
| "in": "query", |
| "description": "Filter expression using ODSQL", |
| "schema": {"type": "string"} |
| }, |
| { |
| "name": "order_by", |
| "in": "query", |
| "description": "Sort order (e.g., 'modified desc')", |
| "schema": {"type": "string"} |
| }, |
| { |
| "name": "limit", |
| "in": "query", |
| "description": "Number of items to return (max 100)", |
| "schema": {"type": "integer", "default": 10, "maximum": 100} |
| }, |
| { |
| "name": "offset", |
| "in": "query", |
| "description": "Index of first item to return", |
| "schema": {"type": "integer", "default": 0} |
| }, |
| { |
| "name": "refine", |
| "in": "query", |
| "description": "Facet refinement (e.g., 'theme:Education')", |
| "schema": {"type": "array", "items": {"type": "string"}} |
| }, |
| { |
| "name": "lang", |
| "in": "query", |
| "description": "Language code", |
| "schema": {"type": "string", "enum": ["en", "fr", "es", "ar", "ru", "zh"], "default": "en"} |
| } |
| ], |
| "responses": { |
| "200": { |
| "description": "A list of available datasets", |
| "content": { |
| "application/json": { |
| "schema": { |
| "$ref": "#/components/schemas/DatasetsResponse" |
| } |
| } |
| } |
| } |
| } |
| } |
| }, |
| "/catalog/datasets/{dataset_id}": { |
| "get": { |
| "summary": "Get dataset information", |
| "operationId": "getDataset", |
| "tags": ["Catalog"], |
| "description": "Returns detailed information about a specific dataset including metadata and field schema.", |
| "parameters": [ |
| { |
| "name": "dataset_id", |
| "in": "path", |
| "required": true, |
| "description": "The dataset identifier", |
| "schema": {"type": "string"} |
| }, |
| { |
| "name": "lang", |
| "in": "query", |
| "description": "Language code", |
| "schema": {"type": "string", "default": "en"} |
| } |
| ], |
| "responses": { |
| "200": { |
| "description": "Dataset details", |
| "content": { |
| "application/json": { |
| "schema": { |
| "$ref": "#/components/schemas/Dataset" |
| } |
| } |
| } |
| } |
| } |
| } |
| }, |
| "/catalog/datasets/{dataset_id}/records": { |
| "get": { |
| "summary": "Query dataset records", |
| "operationId": "getRecords", |
| "tags": ["Dataset"], |
| "description": "Perform a query on dataset records with filtering, sorting, and aggregation.", |
| "parameters": [ |
| { |
| "name": "dataset_id", |
| "in": "path", |
| "required": true, |
| "description": "The dataset identifier", |
| "schema": {"type": "string"} |
| }, |
| { |
| "name": "select", |
| "in": "query", |
| "description": "Select specific fields (e.g., 'country,year,value')", |
| "schema": {"type": "string"} |
| }, |
| { |
| "name": "where", |
| "in": "query", |
| "description": "Filter expression using ODSQL (e.g., \"country = 'France'\")", |
| "schema": {"type": "string"} |
| }, |
| { |
| "name": "group_by", |
| "in": "query", |
| "description": "Group by expression for aggregations", |
| "schema": {"type": "string"} |
| }, |
| { |
| "name": "order_by", |
| "in": "query", |
| "description": "Sort order (e.g., 'value desc')", |
| "schema": {"type": "string"} |
| }, |
| { |
| "name": "limit", |
| "in": "query", |
| "description": "Number of records to return (max 100)", |
| "schema": {"type": "integer", "default": 10, "maximum": 100} |
| }, |
| { |
| "name": "offset", |
| "in": "query", |
| "description": "Index of first record to return", |
| "schema": {"type": "integer", "default": 0} |
| }, |
| { |
| "name": "refine", |
| "in": "query", |
| "description": "Facet refinement", |
| "schema": {"type": "array", "items": {"type": "string"}} |
| } |
| ], |
| "responses": { |
| "200": { |
| "description": "Records response", |
| "content": { |
| "application/json": { |
| "schema": { |
| "$ref": "#/components/schemas/RecordsResponse" |
| } |
| } |
| } |
| } |
| } |
| } |
| }, |
| "/catalog/datasets/{dataset_id}/facets": { |
| "get": { |
| "summary": "List dataset facets", |
| "operationId": "getRecordsFacets", |
| "tags": ["Dataset"], |
| "description": "Enumerates facet values for records. Useful for guided navigation and filtering.", |
| "parameters": [ |
| { |
| "name": "dataset_id", |
| "in": "path", |
| "required": true, |
| "description": "The dataset identifier", |
| "schema": {"type": "string"} |
| }, |
| { |
| "name": "facet", |
| "in": "query", |
| "description": "Facet field to enumerate (e.g., 'country', 'year')", |
| "schema": {"type": "array", "items": {"type": "string"}} |
| }, |
| { |
| "name": "where", |
| "in": "query", |
| "description": "Filter expression", |
| "schema": {"type": "string"} |
| } |
| ], |
| "responses": { |
| "200": { |
| "description": "Facets enumeration", |
| "content": { |
| "application/json": { |
| "schema": { |
| "$ref": "#/components/schemas/FacetsResponse" |
| } |
| } |
| } |
| } |
| } |
| } |
| }, |
| "/catalog/facets": { |
| "get": { |
| "summary": "List catalog facets", |
| "operationId": "get_datasets_facets", |
| "tags": ["Catalog"], |
| "description": "Enumerate facet values for datasets (themes, publishers, etc.)", |
| "parameters": [ |
| { |
| "name": "facet", |
| "in": "query", |
| "description": "Facet field to enumerate (e.g., 'theme', 'publisher')", |
| "schema": {"type": "array", "items": {"type": "string"}} |
| } |
| ], |
| "responses": { |
| "200": { |
| "description": "Catalog facets", |
| "content": { |
| "application/json": { |
| "schema": { |
| "$ref": "#/components/schemas/FacetsResponse" |
| } |
| } |
| } |
| } |
| } |
| } |
| }, |
| "/catalog/datasets/{dataset_id}/exports/{format}": { |
| "get": { |
| "summary": "Export dataset", |
| "operationId": "exportRecords", |
| "tags": ["Dataset"], |
| "description": "Export a dataset in various formats (csv, json, xlsx, parquet).", |
| "parameters": [ |
| { |
| "name": "dataset_id", |
| "in": "path", |
| "required": true, |
| "description": "The dataset identifier", |
| "schema": {"type": "string"} |
| }, |
| { |
| "name": "format", |
| "in": "path", |
| "required": true, |
| "description": "Export format", |
| "schema": {"type": "string", "enum": ["csv", "json", "xlsx", "parquet", "geojson"]} |
| }, |
| { |
| "name": "where", |
| "in": "query", |
| "description": "Filter expression", |
| "schema": {"type": "string"} |
| }, |
| { |
| "name": "limit", |
| "in": "query", |
| "description": "Number of records to export (-1 for all)", |
| "schema": {"type": "integer", "default": -1} |
| } |
| ], |
| "responses": { |
| "200": { |
| "description": "Export file", |
| "content": { |
| "application/octet-stream": { |
| "schema": {"type": "string", "format": "binary"} |
| } |
| } |
| } |
| } |
| } |
| }, |
| "/catalog/datasets/{dataset_id}/records/{record_id}": { |
| "get": { |
| "summary": "Get a single record", |
| "operationId": "getRecord", |
| "tags": ["Dataset"], |
| "description": "Reads a single dataset record by its identifier.", |
| "parameters": [ |
| { |
| "name": "dataset_id", |
| "in": "path", |
| "required": true, |
| "description": "The dataset identifier", |
| "schema": {"type": "string"} |
| }, |
| { |
| "name": "record_id", |
| "in": "path", |
| "required": true, |
| "description": "The record identifier", |
| "schema": {"type": "string"} |
| } |
| ], |
| "responses": { |
| "200": { |
| "description": "Single record", |
| "content": { |
| "application/json": { |
| "schema": { |
| "$ref": "#/components/schemas/Record" |
| } |
| } |
| } |
| } |
| } |
| } |
| } |
| }, |
| "components": { |
| "securitySchemes": { |
| "apikey": { |
| "type": "apiKey", |
| "description": "API key for authenticated requests", |
| "name": "apikey", |
| "in": "query" |
| } |
| }, |
| "schemas": { |
| "DatasetsResponse": { |
| "type": "object", |
| "properties": { |
| "total_count": {"type": "integer"}, |
| "results": { |
| "type": "array", |
| "items": {"$ref": "#/components/schemas/Dataset"} |
| } |
| } |
| }, |
| "Dataset": { |
| "type": "object", |
| "properties": { |
| "dataset_id": {"type": "string"}, |
| "metas": { |
| "type": "object", |
| "properties": { |
| "default": { |
| "type": "object", |
| "properties": { |
| "title": {"type": "string"}, |
| "description": {"type": "string"}, |
| "theme": {"type": "array", "items": {"type": "string"}}, |
| "keyword": {"type": "array", "items": {"type": "string"}}, |
| "publisher": {"type": "string"}, |
| "modified": {"type": "string"}, |
| "records_count": {"type": "integer"} |
| } |
| } |
| } |
| }, |
| "fields": { |
| "type": "array", |
| "items": { |
| "type": "object", |
| "properties": { |
| "name": {"type": "string"}, |
| "label": {"type": "string"}, |
| "type": {"type": "string"}, |
| "description": {"type": "string"} |
| } |
| } |
| }, |
| "has_records": {"type": "boolean"} |
| } |
| }, |
| "RecordsResponse": { |
| "type": "object", |
| "properties": { |
| "total_count": {"type": "integer"}, |
| "results": { |
| "type": "array", |
| "items": {"$ref": "#/components/schemas/Record"} |
| } |
| } |
| }, |
| "Record": { |
| "type": "object", |
| "properties": { |
| "_id": {"type": "string"}, |
| "_timestamp": {"type": "string"} |
| }, |
| "additionalProperties": true |
| }, |
| "FacetsResponse": { |
| "type": "object", |
| "properties": { |
| "facets": { |
| "type": "array", |
| "items": { |
| "type": "object", |
| "properties": { |
| "name": {"type": "string"}, |
| "facets": { |
| "type": "array", |
| "items": { |
| "type": "object", |
| "properties": { |
| "name": {"type": "string"}, |
| "value": {"type": "string"}, |
| "count": {"type": "integer"} |
| } |
| } |
| } |
| } |
| } |
| } |
| } |
| } |
| } |
| } |
| } |
|
|
