{
  "openapi": "3.0.0",
  "paths": {
    "/api/public/data/indicators": {
      "get": {
        "operationId": "getIndicatorData",
        "summary": "Indicator data",
        "description": "Fetch indicator data records based on the given filter query parameters as JSON.\n\nEither the `indicator` or `geoUnit` param must be provided to query data. Both can be combined as well to narrow down the data to be returned.\n\nA maximum of 100 000 records can be returned in a single query. If more data is requested the request will fail with a `400` status code. To query more data multiple requests need to be made.\n\n### Examples queries\n\n#### Fetch all data records for a single indicator\n\n`https://api.uis.unesco.org/api/public/data/indicators?indicator=CR.1`\n\n#### Fetch all data records for a single country\n\n`https://api.uis.unesco.org/api/public/data/indicators?geoUnit=BRA`\n\n#### Fetch data records for multiple indicators and countries\n\n`https://api.uis.unesco.org/api/public/data/indicators?indicator=CR.1&indicator=CR.2&indicator=CR.3&geoUnit=BRA&geoUnit=USA&geoUnit=DEU`\n\n#### Fetch data records for multiple indicators and countries and specific time range\n\n`https://api.uis.unesco.org/api/public/data/indicators?indicator=CR.1&indicator=CR.2&indicator=CR.3&geoUnit=BRA&geoUnit=USA&geoUnit=DEU&start=2010&end=2020`\n\n#### Fetch all data records for a single country with indicator metadata\n\n`https://api.uis.unesco.org/api/public/data/indicators?geoUnit=BRA&indicatorMetadata=true`\n\n#### Fetch all data records for a single indicator with footnotes\n\n`https://api.uis.unesco.org/api/public/data/indicators?indicator=CR.1&footnotes=true`\n\n### Extended examples\n\nDownload the [extended query examples file](https://api.uis.unesco.org/api/public/documentation/examples/indicator-data-api-example-queries.zip) for even more examples on how to use the different query parameters.\n",
        "parameters": [
          {
            "name": "indicator",
            "required": false,
            "in": "query",
            "description": "Ids of the indicators request data for. For a list a of the available indicators, see the [indicator definition endpoint](https://api.uis.unesco.org/api/public/documentation/operations/listIndicators). Can be used in combination with the \"geoUnit\" parameter or standalone (returns all geo unit data for the given indicators)",
            "example": [
              "TSALARY.0",
              "READ.PRIMARY"
            ],
            "style": "form",
            "explode": true,
            "schema": {
              "nullable": false,
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "geoUnit",
            "required": false,
            "in": "query",
            "description": "Ids of the geoUnits to request data for. Allowed values are country and region ids. For a list of the available geo units the, see the [geoUnit definition endpoint](https://api.uis.unesco.org/api/public/documentation/operations/listGeoUnits). Can be used in combination with the \"indicator\" parameter or standalone (returns all indicator data for the given geo units)",
            "example": [
              "ARE",
              "AUT"
            ],
            "style": "form",
            "explode": true,
            "schema": {
              "nullable": false,
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "geoUnitType",
            "required": false,
            "in": "query",
            "description": "The geoUnitType to request data for. Can be used in combination with the \"indicator\" parameter to request either all national or regional data available for the indicator(s). Not specifying this parameter will return both national and regional data. This parameter is ignored if any \"geoUnit\" param is set, as that takes precedent.",
            "example": "NATIONAL",
            "schema": {
              "$ref": "#/components/schemas/GeoUnitType"
            }
          },
          {
            "name": "start",
            "required": false,
            "in": "query",
            "description": "The start year to request data for. Includes the year itself.",
            "example": 2010,
            "schema": {
              "nullable": false,
              "type": "number"
            }
          },
          {
            "name": "end",
            "required": false,
            "in": "query",
            "description": "The end year to request data for. Includes the year itself.",
            "example": 2015,
            "schema": {
              "nullable": false,
              "type": "number"
            }
          },
          {
            "name": "footnotes",
            "required": false,
            "in": "query",
            "description": "Whether to include footnotes (per data point) in the response",
            "example": true,
            "schema": {
              "nullable": false,
              "type": "boolean"
            }
          },
          {
            "name": "indicatorMetadata",
            "required": false,
            "in": "query",
            "description": "Whether to include indicator metadata in the response.",
            "example": true,
            "schema": {
              "nullable": false,
              "type": "boolean"
            }
          },
          {
            "name": "version",
            "required": false,
            "in": "query",
            "description": "The version to read the data from. If not provided, defaults to the current [default version](https://api.uis.unesco.org/api/public/documentation/operations/getPublishedDefaultVersion). For a list of all available version see the [list versions endpoint](https://api.uis.unesco.org/api/public/documentation/operations/listPublishedVersions) endpoint.",
            "example": "20230911-aa16ef3f",
            "schema": {
              "nullable": false,
              "type": "string"
            }
          },
          {
            "name": "Accept-Encoding",
            "in": "header",
            "description": "The supported compression algorithms",
            "required": true,
            "schema": {
              "type": "string",
              "examples": [
                "gzip",
                "br"
              ],
              "default": "gzip"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The found indicator data records",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IndicatorDataResponse"
                }
              }
            }
          },
          "400": {
            "description": "The given search criteria are invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Data"
        ]
      }
    },
    "/api/public/data/indicators/export": {
      "get": {
        "operationId": "exportIndicatorData",
        "summary": "Indicator data (export)",
        "description": "Export indicator data records based on the given filter query parameters in different formats (csv, excel and json). Always return a ZIP file containing a README.md file and data files according to the chosen format.\n\nEither the `indicator` or `geoUnit` param must be provided to query data. Both can be combined as well to narrow down the data to be returned.\n\nA maximum of 100 000 records can be returned in a single query. If more data is requested the request will fail with a `400` status code. To query more data multiple requests need to be made.\n\n### Examples queries\n\n#### Fetch all data records for a single indicator as EXCEL\n\n`https://api.uis.unesco.org/api/public/data/indicators/export?format=excel&indicator=CR.1`\n\n#### Fetch all data records for a single indicator as CSV\n\n`https://api.uis.unesco.org/api/public/data/indicators/export?format=csv&indicator=CR.1`\n\n#### Fetch all data records for a single country with indicator metadata and footnotes as EXCEL\n\n`https://api.uis.unesco.org/api/public/data/indicators/export?format=excel&geoUnit=BRA&indicatorMetadata=true&footnotes=true`\n\nSee the [indicator data endpoint documentation](https://api.uis.unesco.org/api/public/documentation/operations/getIndicatorData) for more examples on how to use the different query parameters.\n",
        "parameters": [
          {
            "name": "indicator",
            "required": false,
            "in": "query",
            "description": "Ids of the indicators request data for. For a list a of the available indicators, see the [indicator definition endpoint](https://api.uis.unesco.org/api/public/documentation/operations/listIndicators). Can be used in combination with the \"geoUnit\" parameter or standalone (returns all geo unit data for the given indicators)",
            "example": [
              "TSALARY.0",
              "READ.PRIMARY"
            ],
            "style": "form",
            "explode": true,
            "schema": {
              "nullable": false,
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "geoUnit",
            "required": false,
            "in": "query",
            "description": "Ids of the geoUnits to request data for. Allowed values are country and region ids. For a list of the available geo units the, see the [geoUnit definition endpoint](https://api.uis.unesco.org/api/public/documentation/operations/listGeoUnits). Can be used in combination with the \"indicator\" parameter or standalone (returns all indicator data for the given geo units)",
            "example": [
              "ARE",
              "AUT"
            ],
            "style": "form",
            "explode": true,
            "schema": {
              "nullable": false,
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "geoUnitType",
            "required": false,
            "in": "query",
            "description": "The geoUnitType to request data for. Can be used in combination with the \"indicator\" parameter to request either all national or regional data available for the indicator(s). Not specifying this parameter will return both national and regional data. This parameter is ignored if any \"geoUnit\" param is set, as that takes precedent.",
            "example": "NATIONAL",
            "schema": {
              "$ref": "#/components/schemas/GeoUnitType"
            }
          },
          {
            "name": "start",
            "required": false,
            "in": "query",
            "description": "The start year to request data for. Includes the year itself.",
            "example": 2010,
            "schema": {
              "nullable": false,
              "type": "number"
            }
          },
          {
            "name": "end",
            "required": false,
            "in": "query",
            "description": "The end year to request data for. Includes the year itself.",
            "example": 2015,
            "schema": {
              "nullable": false,
              "type": "number"
            }
          },
          {
            "name": "footnotes",
            "required": false,
            "in": "query",
            "description": "Whether to include footnotes (per data point) in the response",
            "example": true,
            "schema": {
              "nullable": false,
              "type": "boolean"
            }
          },
          {
            "name": "indicatorMetadata",
            "required": false,
            "in": "query",
            "description": "Whether to include indicator metadata in the response.",
            "example": true,
            "schema": {
              "nullable": false,
              "type": "boolean"
            }
          },
          {
            "name": "version",
            "required": false,
            "in": "query",
            "description": "The version to read the data from. If not provided, defaults to the current [default version](https://api.uis.unesco.org/api/public/documentation/operations/getPublishedDefaultVersion). For a list of all available version see the [list versions endpoint](https://api.uis.unesco.org/api/public/documentation/operations/listPublishedVersions) endpoint.",
            "example": "20230911-aa16ef3f",
            "schema": {
              "nullable": false,
              "type": "string"
            }
          },
          {
            "name": "format",
            "required": true,
            "in": "query",
            "description": "The requested export format",
            "example": "csv",
            "schema": {
              "$ref": "#/components/schemas/ExportFormat"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Based on the given search criteria, returns the matching indicator data in the chosen export format.",
            "headers": {
              "Content-Disposition": {
                "example": "attachment; filename=\"indicator-data-export_OAEPG.1.zip\""
              }
            },
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary",
                  "description": "ZIP file containing a README.md file and data files according to the chosen format (csv, excel or json)."
                }
              }
            }
          },
          "400": {
            "description": "The given search criteria are invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Data"
        ]
      }
    },
    "/api/public/definitions/geounits": {
      "get": {
        "operationId": "listGeoUnits",
        "summary": "List of geo units",
        "description": "Returns a list of geo units for the given version (or the current default version if no explicit version is provided).\n\n### Examples queries\n\n#### List for current default version\n\n`https://api.uis.unesco.org/api/public/definitions/geounits`\n\n#### List for specific version\n\n`https://api.uis.unesco.org/api/public/definitions/geounits?version=20240910-b5ad4d82`\n",
        "parameters": [
          {
            "name": "version",
            "required": false,
            "in": "query",
            "description": "The version to list the geo units definitions for. If not provided, the current default version is used.",
            "example": "20230911-aa16ef3f",
            "schema": {
              "nullable": false,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of geo units",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/GeoUnitDto"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The given search criteria are invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Definitions"
        ]
      }
    },
    "/api/public/definitions/geounits/export": {
      "get": {
        "operationId": "listGeoUnitsExport",
        "summary": "List of geo units (export)",
        "description": "Returns a list of geo units for the given version (or the current default version if no explicit version is provided).\n\n### Examples queries\n\n#### List for current default version as EXCEL\n\n`https://api.uis.unesco.org/api/public/definitions/geounits/export?format=excel`\n\n#### List for current default version as CSV\n\n`https://api.uis.unesco.org/api/public/definitions/geounits/export?format=csv`\n\n#### List for specific version as EXCEL\n\n`https://api.uis.unesco.org/api/public/definitions/geounits/export?format=csv&version=20240910-b5ad4d82`\n",
        "parameters": [
          {
            "name": "version",
            "required": false,
            "in": "query",
            "description": "The version to list the geo units definitions for. If not provided, the current default version is used.",
            "example": "20230911-aa16ef3f",
            "schema": {
              "nullable": false,
              "type": "string"
            }
          },
          {
            "name": "format",
            "required": true,
            "in": "query",
            "description": "The requested export format",
            "example": "csv",
            "schema": {
              "$ref": "#/components/schemas/ExportFormat"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of geo units as either CSV or EXCEL file",
            "content": {
              "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
                "schema": {
                  "type": "string",
                  "format": "binary",
                  "description": "Excel file"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string",
                  "description": "CSV file"
                }
              }
            }
          },
          "400": {
            "description": "The given search criteria are invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Definitions"
        ]
      }
    },
    "/api/public/definitions/indicators": {
      "get": {
        "operationId": "listIndicators",
        "summary": "List of indicators",
        "description": "Returns a list of indicators for the given version (or the current default version if no explicit version is provided). The list can be enhanced with additional information such as\ndisaggregations and glossary terms.\n\n### Examples queries\n\n#### List for current default version without glossary terms and disaggregations\n\n`https://api.uis.unesco.org/api/public/definitions/indicators`\n\n#### List with glossary terms and disaggregation information\n\n`https://api.uis.unesco.org/api/public/definitions/indicators?disaggregations=true&glossaryTerms=true`\n\n#### List for specific version\n\n`https://api.uis.unesco.org/api/public/definitions/indicators?version=20240910-b5ad4d82`\n",
        "parameters": [
          {
            "name": "version",
            "required": false,
            "in": "query",
            "description": "The version to list the indicators definitions for. If not provided, the current default version is used.",
            "example": "20230911-aa16ef3f",
            "schema": {
              "nullable": false,
              "type": "string"
            }
          },
          {
            "name": "glossaryTerms",
            "required": false,
            "in": "query",
            "description": "Whether to include glossary terms in the response",
            "example": true,
            "schema": {
              "nullable": false,
              "type": "boolean"
            }
          },
          {
            "name": "disaggregations",
            "required": false,
            "in": "query",
            "description": "Whether to include disaggregations in the response",
            "example": true,
            "schema": {
              "nullable": false,
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of indicators",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/IndicatorMetadata"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The given search criteria are invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Definitions"
        ]
      }
    },
    "/api/public/definitions/indicators/export": {
      "get": {
        "operationId": "listIndicatorsExport",
        "summary": "List of indicators (export)",
        "description": "Returns a list of indicators for the given version (or the current default version if no explicit version is provided) in CSV or EXCEL format. The list can be enhanced with additional information such as\ndisaggregations and glossary terms.\n\n### Examples queries\n\n#### List for current default version without glossary terms and disaggregations as EXCEL\n\n`https://api.uis.unesco.org/api/public/definitions/indicators/export?format=excel`\n\n#### List for current default version without glossary terms and disaggregations as CSV\n\n`https://api.uis.unesco.org/api/public/definitions/indicators/export?format=csv`\n\n#### List with glossary terms and disaggregation information as EXCEL\n\n`https://api.uis.unesco.org/api/public/definitions/indicators/export?format=excel&disaggregations=true&glossaryTerms=true`\n",
        "parameters": [
          {
            "name": "version",
            "required": false,
            "in": "query",
            "description": "The version to list the indicators definitions for. If not provided, the current default version is used.",
            "example": "20230911-aa16ef3f",
            "schema": {
              "nullable": false,
              "type": "string"
            }
          },
          {
            "name": "glossaryTerms",
            "required": false,
            "in": "query",
            "description": "Whether to include glossary terms in the response",
            "example": true,
            "schema": {
              "nullable": false,
              "type": "boolean"
            }
          },
          {
            "name": "disaggregations",
            "required": false,
            "in": "query",
            "description": "Whether to include disaggregations in the response",
            "example": true,
            "schema": {
              "nullable": false,
              "type": "boolean"
            }
          },
          {
            "name": "format",
            "required": true,
            "in": "query",
            "description": "The requested export format",
            "example": "csv",
            "schema": {
              "$ref": "#/components/schemas/ExportFormat"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of indicators as either CSV or EXCEL file",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string",
                  "description": "CSV file"
                }
              },
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary",
                  "description": "ZIP file with multiple CSV files"
                }
              },
              "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
                "schema": {
                  "type": "string",
                  "format": "binary",
                  "description": "Excel file"
                }
              }
            }
          },
          "400": {
            "description": "The given search criteria are invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Definitions"
        ]
      }
    },
    "/api/public/versions/default": {
      "get": {
        "operationId": "getPublishedDefaultVersion",
        "summary": "Default version",
        "description": "The current default data version.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "The current default data version.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataVersion"
                }
              }
            }
          }
        },
        "tags": [
          "Versions"
        ]
      }
    },
    "/api/public/versions": {
      "get": {
        "operationId": "listPublishedVersions",
        "summary": "List versions",
        "description": "List of all published data versions.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "List of all published data versions.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DataVersion"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Versions"
        ]
      }
    }
  },
  "info": {
    "title": "UIS Data API",
    "description": "## Table of contents\n\n- [Introduction](#introduction)\n- [License](#license)\n- [Rate limiting and caching](#rate-limiting-and-caching)\n- [Bulk Data Download](#bulk-data-download)\n- [Endpoints overview](#endpoints-overview)\n- [OpenAPI Specification](#openapi-specification)\n- [Changelog](#api-changelog)\n\n## Introduction\n\nThis API offers programmatic access to the data of the UNESCO Institute for Statistics (UIS). The data is available in\ndifferent formats and can be accessed through different endpoints.\n\n### API training session\n\nCheck out the [API training session website](https://tcg.uis.unesco.org/api_trainings/) for the video recording of the API training session and related materials.\n\n## License\n\nThe data is licensed under the [Creative Commons Attribution-ShareAlike 4.0 International](https://creativecommons.org/licenses/by-sa/4.0/) license.\n\nVisit the [Terms and conditions page](https://databrowser.uis.unesco.org/terms-and-conditions) for more information.\n\n## Rate limiting and caching\n\nThere is currently no rate limiting in place. The API relies heavily on caching to ensure that the data is served as\nquickly as possible. To ensure your usage of the API takes full advantage of caching, ensure that the query parameters\nare used in the same order as the caching is done on the full URL used to query data.\n\n### Data response limits\n\nThe API will only return 100'000 records for each query, if more data is requested, the API call with fail with a `400` http status code. If you need more data, consider using the [Bulk Data Download](#bulk-data-download) or making multiple queries.\n\n### Special considerations for browser based usage\n\nThe API can be queried directly from the browser as the CORS headers as set to allow requests from any origin. For ideal\nperformance always include an explicit `version` parameter in the query so that the response can be cached by the\nbrowser of each client. You can use the [default version endpoint](/operations/getPublishedDefaultVersion) to get the current default version.\n\n## Bulk Data Download\n\nThe Bulk Data Download Service (BDDS) allows users to download aggregated UIS datasets as flat files.\nVisit the [Bulk Data Download Service page](https://databrowser.uis.unesco.org/resources/bulk) for more information.\n\n## Endpoints overview\n\n### Version endpoints\n\nThe [default version endpoint](/operations/getPublishedDefaultVersion) returns the current default data version (newest published) and the [list versions endpoint](/operations/listPublishedVersions) returns all published versions and can be used to query data for a specific data version.\n\n### Data endpoints\n\nThe main [indicator data endpoint](/operations/getIndicatorData) offers access to the data records and supports a range of different filter options. This endpoint always return JSON data and should be used for most programmatic integrations.\n\nThe [indicator data export endpoint](/operations/exportIndicatorData) offers the same data and filter options as the indicator data endpoint but also offers results in CSV and EXCEL formats. This endpoint always returns a ZIP file with the requested data as well as a README.md file.\n\n### Definitions endpoints\n\nThe [list geo units endpoint](/operations/listGeoUnits) returns a list of all available geo units and the [list indicators endpoint](/operations/listIndicators) returns a list of all available indicators.\n\n## OpenAPI Specification\n\nThis documentation is generated from the OpenAPI specifications of the API. The specification can be downloaded either via the `Export` dropdown on the top right of this page or via this url: [https://api.uis.unesco.org/api/public/openapi/schema.json](https://api.uis.unesco.org/api/public/openapi/schema.json)\n\n## API Changelog\n\n### 2024-09-11 - Version 1.0.0\nInitial release of the UIS Data API\n\n### 2024-09-17 - Version 1.0.1\nExtended documentation to include query examples for the geo unit and indicator definitions endpoints as well as the indicator data endpoints.\n\n### 2024-09-26 - Version 1.0.2\nAdded links to the [API training session](#api-training-session) recording/materials and added extended examples file to the [indicator data endpoint](/operations/getIndicatorData) documentation page.\n\n### 2026-09-14 - Version 1.0.3\nExplicitly typed the `indicator` and `geoUnit` query params of the [getIndicatorData](/operations/getIndicatorData) and [exportIndicatorData](/operations/exportIndicatorData) operations to use `style=form` and `explode=true` settings for clarity and consistency when used for type/code generation. This behavior was already the implicit default for query params with OpenAPI specification v3.0.0 (see documentation [here](https://swagger.io/docs/specification/v3_0/serialization/#query-parameters)).\n",
    "version": "1.0.3",
    "contact": {
      "name": "UIS Data Team",
      "url": "https://uis.unesco.org/en/contact-us",
      "email": "uis.datarequests@unesco.org"
    },
    "termsOfService": "https://databrowser.uis.unesco.org/terms-and-conditions",
    "license": {
      "name": "Creative Commons Attribution-ShareAlike 4.0 International License",
      "url": "https://creativecommons.org/licenses/by-sa/4.0/"
    }
  },
  "tags": [
    {
      "name": "Data",
      "description": "data related endpoints"
    },
    {
      "name": "Export",
      "description": "export related endpoints"
    },
    {
      "name": "Versioning",
      "description": "version related endpoints"
    },
    {
      "name": "Statistics",
      "description": "data statistic related endpoints"
    },
    {
      "name": "Monitoring",
      "description": "monitoring related endpoints"
    }
  ],
  "servers": [
    {
      "url": "https://api.uis.unesco.org",
      "description": "API URL"
    }
  ],
  "components": {
    "schemas": {
      "GeoUnitType": {
        "type": "string",
        "title": "GeoUnitType",
        "description": "GeoUnit types available on UIS Data API.\n\n  - **NATIONAL** - Country level data\n  - **REGIONAL** - Regional level data\n  ",
        "enum": [
          "NATIONAL",
          "REGIONAL"
        ]
      },
      "Magnitude": {
        "type": "string",
        "description": "MAGNITUDE describes the NATURE of the data point\n\n  Possible values are:\n  - **NIL** – The value will be 0, and should be treated as NIL.\n  - **NA** – The value will be 0.  This data point is NOT APPLICABLE for the submitting nation.\n  - **SUPP** -  The value will be BLANK.  The data point was SUPPRESSED by request of the submitting nation.\n  - **LOWREL** – The value will be NUMERIC.  The data point is of LOW RELIABILITY.\n  - **INCLUDED** – The value will be BLANK. This data is INCLUDED in ANOTHER data point.\n  - **INCLUDES** – The value will be NUMERIC.  This data point INCLUDES data from another data point.\n  ",
        "enum": [
          "NIL",
          "NA",
          "SUPP",
          "LOWREL",
          "INCLUDED",
          "INCLUDES"
        ]
      },
      "Qualifier": {
        "type": "string",
        "description": "QUALIFIER describes the QUALITIES of the data point.\n\n  Possible values are:\n  - **NAT_EST** – The value will be NUMERIC.  This data point is a NATIONAL ESTIMATE.\n  - **UIS_EST** – The value will be NUMERIC.  This data point is an ESTIMATE produced by the UNESCO INSTITUTE FOR STATISTICS.\n  ",
        "enum": [
          "NAT_EST",
          "UIS_EST"
        ]
      },
      "Footnote": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Type of the footnote",
            "example": "Source",
            "nullable": false
          },
          "subtype": {
            "type": "string",
            "description": "Subtype of the footnote",
            "example": "Data sources",
            "nullable": false
          },
          "value": {
            "type": "string",
            "description": "The footnote text",
            "example": "Zimbabwe DHS 2010-11. The survey collected data on school attendance for age 5-24 and educational attainment for age 5 and above.",
            "nullable": false
          }
        },
        "required": [
          "type",
          "subtype",
          "value"
        ]
      },
      "PropertyChange": {
        "type": "object",
        "properties": {
          "property": {
            "type": "string",
            "description": "The property that changed",
            "example": "value",
            "nullable": false
          },
          "oldValue": {
            "description": "The old value of the property",
            "nullable": true,
            "oneOf": [
              {
                "type": "number",
                "example": 20
              },
              {
                "type": "string",
                "example": ""
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Footnote"
                }
              }
            ]
          },
          "newValue": {
            "description": "The new value of the property",
            "nullable": true,
            "oneOf": [
              {
                "type": "number",
                "example": 21.14
              },
              {
                "type": "string",
                "example": "new value"
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Footnote"
                }
              }
            ]
          }
        },
        "required": [
          "property"
        ]
      },
      "DataChange": {
        "type": "object",
        "properties": {
          "comparedTo": {
            "type": "object",
            "description": "The item that was compared to",
            "nullable": true
          },
          "propertyChanges": {
            "description": "The changes that were found",
            "nullable": false,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PropertyChange"
            }
          }
        },
        "required": [
          "comparedTo",
          "propertyChanges"
        ]
      },
      "IndicatorData": {
        "type": "object",
        "properties": {
          "indicatorId": {
            "type": "string",
            "example": "CR.1.Q3.M.LPIA",
            "nullable": false
          },
          "geoUnit": {
            "type": "string",
            "example": "ZWE",
            "nullable": false
          },
          "year": {
            "type": "number",
            "example": 2010,
            "nullable": false
          },
          "value": {
            "type": "number",
            "nullable": true,
            "example": 20.57
          },
          "magnitude": {
            "nullable": true,
            "example": "NA",
            "$ref": "#/components/schemas/Magnitude"
          },
          "qualifier": {
            "nullable": true,
            "example": "NAT_EST",
            "$ref": "#/components/schemas/Qualifier"
          },
          "footnotes": {
            "nullable": false,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Footnote"
            }
          },
          "change": {
            "nullable": false,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DataChange"
            }
          }
        },
        "required": [
          "indicatorId",
          "geoUnit",
          "year",
          "value",
          "magnitude",
          "qualifier"
        ]
      },
      "Message": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "The code of the message",
            "examples": [
              "UIS::001"
            ],
            "nullable": false
          },
          "message": {
            "type": "string",
            "description": "The message text content",
            "example": "The indicator id could not be found",
            "nullable": false
          }
        },
        "required": [
          "code",
          "message"
        ]
      },
      "Theme": {
        "type": "string",
        "title": "Theme",
        "description": "Toplevel UIS themes to group content.\n\n  - **EDUCATION** - Education\n  - **SCIENCE_TECHNOLOGY_INNOVATION** - Science, Technology & Innovation\n  - **CULTURE** - Culture\n  - **DEMOGRAPHIC_SOCIOECONOMIC** - Demographic & Socio-Economic\n  ",
        "enum": [
          "EDUCATION",
          "SCIENCE_TECHNOLOGY_INNOVATION",
          "CULTURE",
          "DEMOGRAPHIC_SOCIOECONOMIC"
        ]
      },
      "TimeSlotStat": {
        "type": "object",
        "properties": {
          "min": {
            "type": "number",
            "description": "The minimum year of the time line",
            "example": 1970,
            "nullable": false
          },
          "max": {
            "type": "number",
            "description": "The maximum year of the time line",
            "example": 2022,
            "nullable": false
          }
        },
        "required": [
          "min",
          "max"
        ]
      },
      "IndicatorGeoUnitStat": {
        "type": "object",
        "properties": {
          "types": {
            "type": "array",
            "example": [
              "NATIONAL",
              "REGIONAL"
            ],
            "nullable": false,
            "items": {
              "$ref": "#/components/schemas/GeoUnitType"
            }
          }
        },
        "required": [
          "types"
        ]
      },
      "IndicatorDataAvailabilityInfo": {
        "type": "object",
        "properties": {
          "totalRecordCount": {
            "type": "number",
            "description": "The total number of records available (over all geo units) for this indicator.",
            "example": 1097,
            "nullable": false
          },
          "timeLine": {
            "description": "The time line of available data records for this indicator.",
            "nullable": false,
            "allOf": [
              {
                "$ref": "#/components/schemas/TimeSlotStat"
              }
            ]
          },
          "geoUnits": {
            "description": "The geoUnits available for this indicator.",
            "nullable": false,
            "allOf": [
              {
                "$ref": "#/components/schemas/IndicatorGeoUnitStat"
              }
            ]
          }
        },
        "required": [
          "totalRecordCount",
          "geoUnits"
        ]
      },
      "Language": {
        "type": "string",
        "description": "Supported languages for the UIS Data API.\n\n  **At the moment only english is supported.**\n\n  - **en** - English\n  ",
        "enum": [
          "en"
        ]
      },
      "GlossaryTerm": {
        "type": "object",
        "properties": {
          "termId": {
            "type": "number",
            "description": "Unique glossary term identifier",
            "example": 3183,
            "nullable": false
          },
          "name": {
            "type": "string",
            "description": "Name of the glossary term",
            "example": "Gross early childhood education enrolment ratio in (a) pre-primary education and (b) early childhood educational development",
            "nullable": false
          },
          "themes": {
            "type": "array",
            "example": [
              "EDUCATION"
            ],
            "nullable": false,
            "items": {
              "$ref": "#/components/schemas/Theme"
            }
          },
          "language": {
            "example": "en",
            "nullable": false,
            "$ref": "#/components/schemas/Language"
          },
          "definition": {
            "type": "string",
            "description": "Main definition of the glossary term",
            "example": "SDG Indicator 4.2.4: Total enrolment in (a) pre-primary education and (b) early childhood educational development regardless of age expressed as a percentage of the population of the official age for the respective level of education.",
            "nullable": false
          },
          "definitionSource": {
            "type": "string",
            "description": "Source of the definition property of the glossary term",
            "example": "UNESCO Institute for Statistics",
            "nullable": false
          },
          "purpose": {
            "type": "string",
            "description": "Describes the purpose of the indicator",
            "example": "To show separately the general level of participation in the two categories of early childhood education: pre-primary education and early childhood educational development. The values indicate the capacity of the education system to enrol children of early childhood education age.",
            "nullable": false
          },
          "calculationMethod": {
            "type": "string",
            "description": "Describes the calculation method of the indicator",
            "example": "The number of students enrolled in the given category of early childhood education is expressed as a percentage of the population of the official age for the respective level of education.",
            "nullable": false
          },
          "dataRequired": {
            "type": "string",
            "description": "Data required to calculate the indicator",
            "example": "Enrolment in pre-primary education and early childhood educational development; population estimates by single year of age (if using administrative data) and data on the structure (entrance age and duration) of early childhood education.",
            "nullable": false
          },
          "dataSource": {
            "type": "string",
            "description": "Describes the data source of the indicator",
            "example": "Administrative data from schools or household survey data on enrolment; population censuses and surveys for population estimates by single year of age (if using administrative data on enrolment); administrative data from ministries of education on the structure (entrance age and duration) of early childhood education.",
            "nullable": false
          },
          "typesOfDisaggregation": {
            "type": "string",
            "description": "Describes the available disaggregations of the indicator",
            "example": "By sex from administrative sources; and by sex, location and income from household surveys and others as available.",
            "nullable": false
          },
          "interpretation": {
            "type": "string",
            "description": "Interpretation hints of the indicator",
            "example": "A high value generally indicates a high degree of participation, whether the pupils belong to the official age group or not. A value approaching or exceeding 100% indicates that a country is, in principle, able to accommodate all of its early childhood education-age population, but it does not indicate the proportion already enrolled. The achievement of a gross enrolment ratio of 100% is therefore a necessary but not sufficient condition for enrolling all eligible children in early childhood education.",
            "nullable": false
          },
          "qualityStandards": {
            "type": "string",
            "description": "Describes the relevant quality standards for the indicator",
            "example": "The indicator at each level of education should be based on total enrolment in all types of education institutions, including public, private and all other institutions that provide organized educational programme.",
            "nullable": false
          },
          "limitations": {
            "type": "string",
            "description": "Describes the limitations of the indicator",
            "example": "The gross enrolment ratio can exceed 100% due to the inclusion of over-aged or under-aged pupils because of early or late entrance",
            "nullable": false
          }
        },
        "required": [
          "termId",
          "name",
          "themes",
          "language"
        ]
      },
      "DisaggregationType": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Unique disaggregation type identifier code",
            "example": "EduLvl",
            "nullable": false
          },
          "name": {
            "type": "string",
            "description": "Name of the disaggregation type",
            "example": "Education Level",
            "nullable": false
          },
          "description": {
            "type": "string",
            "description": "Description of the disaggregation type",
            "example": "All relevant education levels including ISCED standard education levels.",
            "nullable": false
          },
          "glossaryTerms": {
            "description": "Associated glossary terms of the disaggregation type",
            "nullable": false,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GlossaryTerm"
            }
          }
        },
        "required": [
          "code",
          "name",
          "glossaryTerms"
        ]
      },
      "DisaggregationValue": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Unique disaggregation value identifier code",
            "example": "EduLvl:ISCED02",
            "nullable": false
          },
          "name": {
            "type": "string",
            "description": "Name of the disaggregation value",
            "example": "Pre-primary education",
            "nullable": false
          },
          "description": {
            "type": "string",
            "description": "Description of the disaggregation value",
            "nullable": false
          },
          "glossaryTerms": {
            "description": "Associated glossary terms of the disaggregation value",
            "nullable": false,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GlossaryTerm"
            }
          },
          "disaggregationType": {
            "description": "Disaggregation type the disaggregation value belongs to.",
            "nullable": false,
            "allOf": [
              {
                "$ref": "#/components/schemas/DisaggregationType"
              }
            ]
          }
        },
        "required": [
          "code",
          "name",
          "glossaryTerms",
          "disaggregationType"
        ]
      },
      "IndicatorMetadata": {
        "type": "object",
        "properties": {
          "indicatorCode": {
            "type": "string",
            "example": "CR.1.Q3.M.LPIA",
            "nullable": false
          },
          "name": {
            "type": "string",
            "example": "Completion rate, primary education, middle quintile, male, adjusted location parity index (LPIA)",
            "nullable": false
          },
          "theme": {
            "example": "EDUCATION",
            "nullable": false,
            "$ref": "#/components/schemas/Theme"
          },
          "lastDataUpdate": {
            "type": "string",
            "description": "The date of the last data update for this indicator. Format: 'YYYY-MM-DD'.",
            "nullable": false
          },
          "lastDataUpdateDescription": {
            "type": "string",
            "description": "Short description of the last data update.",
            "nullable": false
          },
          "dataAvailability": {
            "nullable": false,
            "allOf": [
              {
                "$ref": "#/components/schemas/IndicatorDataAvailabilityInfo"
              }
            ]
          },
          "disaggregations": {
            "nullable": false,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DisaggregationValue"
            }
          },
          "glossaryTerms": {
            "nullable": false,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GlossaryTerm"
            }
          }
        },
        "required": [
          "indicatorCode",
          "name",
          "theme",
          "lastDataUpdate",
          "lastDataUpdateDescription",
          "dataAvailability"
        ]
      },
      "IndicatorDataResponse": {
        "type": "object",
        "properties": {
          "records": {
            "nullable": false,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IndicatorData"
            }
          },
          "hints": {
            "example": [
              {
                "code": "UIS::HINT::001",
                "message": "The indicator could not be found, SCHNABBER.09876543210XXX"
              }
            ],
            "nullable": false,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Message"
            }
          },
          "indicatorMetadata": {
            "nullable": false,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IndicatorMetadata"
            }
          }
        },
        "required": [
          "records",
          "hints",
          "indicatorMetadata"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "example": 400,
            "nullable": false
          },
          "message": {
            "oneOf": [
              {
                "type": "string",
                "example": "The value for xyz is not allowed"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "example": [
                  "The value for xyz is not allowed"
                ]
              }
            ],
            "description": "Error message(s)",
            "examples": [
              "The value for xyz is not allowed",
              [
                "The value for xyz is not allowed"
              ]
            ],
            "nullable": false
          },
          "error": {
            "type": "string",
            "example": "Bad Request",
            "nullable": false
          }
        },
        "required": [
          "statusCode",
          "message",
          "error"
        ]
      },
      "ExportFormat": {
        "type": "string",
        "enum": [
          "csv",
          "excel",
          "json"
        ]
      },
      "GeoUnitDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Geo unit id. Can be either a country code or a region id.",
            "examples": [
              "VNM",
              "FJI",
              "IDN",
              "AIMS: Asia and the Pacific"
            ],
            "nullable": false
          },
          "name": {
            "type": "string",
            "description": "Geo unit name.",
            "examples": [
              "Vietnam",
              "Fiji",
              "Indonesia",
              "Asia and the Pacific"
            ],
            "nullable": false
          },
          "type": {
            "examples": [
              "NATIONAL",
              "REGIONAL"
            ],
            "nullable": false,
            "$ref": "#/components/schemas/GeoUnitType"
          },
          "regionGroup": {
            "type": "string",
            "description": "Region group id. Only relevant for regional geo units.",
            "nullable": false
          }
        },
        "required": [
          "id",
          "name",
          "type"
        ]
      },
      "ThemeDataStatus": {
        "type": "object",
        "properties": {
          "theme": {
            "example": "EDUCATION",
            "nullable": false,
            "$ref": "#/components/schemas/Theme"
          },
          "lastUpdate": {
            "type": "string",
            "description": "The date of the last update for the data the corresponding theme. Format: 'YYYY-MM-DD'.",
            "nullable": false
          },
          "description": {
            "type": "string",
            "description": "Short description of the last data update.",
            "nullable": false
          }
        },
        "required": [
          "theme",
          "lastUpdate",
          "description"
        ]
      },
      "DataVersion": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string",
            "example": "20230911-aa16ef3f",
            "nullable": false
          },
          "publicationDate": {
            "format": "date-time",
            "type": "string",
            "description": "Publication date of the data version.",
            "example": "2023-10-23T12:34:00.000Z",
            "nullable": false
          },
          "description": {
            "type": "string",
            "description": "Short description of the data version.",
            "example": "Education data refresh September 2021",
            "nullable": false
          },
          "themeDataStatus": {
            "example": [
              {
                "theme": "EDUCATION",
                "lastUpdate": "2023-09-23",
                "comment": "Data refresh September 2023"
              },
              {
                "theme": "SCIENCE_TECHNOLOGY_INNOVATION",
                "lastUpdate": "2023-03-15",
                "comment": "Data refresh March 2023"
              },
              {
                "theme": "CULTURE",
                "lastUpdate": "2023-03-15",
                "comment": "Data refresh March 2023"
              },
              {
                "theme": "DEMOGRAPHIC_SOCIOECONOMIC",
                "lastUpdate": "2023-09-23",
                "comment": "Data refresh September 2023"
              }
            ],
            "description": "Information about the status of the data for each theme.",
            "nullable": false,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ThemeDataStatus"
            }
          }
        },
        "required": [
          "version",
          "themeDataStatus"
        ]
      }
    }
  }
}