openapi: 3.0.3
info:
title: Explore Catalog API
version: v2.1
description: 'The Opendatasoft Explore API v2 is organized around REST. It provides access to all the data available through the platform in a coherent, hierarchical way.
- Only the HTTP `GET` method is supported.
- All API endpoints return JSON.
- Endpoints are organized in a hierarchical way describing the relative relationship between objects.
- All responses contain a list of links allowing easy and relevant navigation through the API endpoints.
- All endpoints use the [Opendatasoft Query Language (ODSQL)](https://help.huwise.com/apis/ods-explore-v2/#section/Opendatasoft-Query-Language-(ODSQL)). This means that, most of the time, parameters work the same way for all endpoints.
- While the `records` endpoint is subject to a [limited number of returned records](https://help.huwise.com/apis/ods-explore-v2/#tag/Dataset/operation/getRecords), the `exports` endpoint has no limitations.'
contact:
email: support@opendatasoft.com
license:
name: Copyright Opendatasoft
url: https://legal.huwise.com/en/terms-of-use.html
servers:
- url: https://public.opendatasoft.com/api/explore/v2.1
security:
- apikey: []
tags:
- name: Catalog
description: API to enumerate datasets
paths:
/catalog/datasets:
get:
summary: Query catalog datasets
operationId: getDatasets
tags:
- Catalog
description: Retrieve available datasets.
parameters:
- $ref: '#/components/parameters/select'
- $ref: '#/components/parameters/where'
- $ref: '#/components/parameters/order_by'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/refine'
- $ref: '#/components/parameters/exclude'
- $ref: '#/components/parameters/lang'
- $ref: '#/components/parameters/timezone'
- $ref: '#/components/parameters/group_by'
- $ref: '#/components/parameters/include_links'
- $ref: '#/components/parameters/include_app_metas'
responses:
'200':
description: A list of available datasets
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/datasets'
examples:
datasets:
$ref: '#/components/examples/datasets-v2.1'
'400':
$ref: '#/components/responses/bad_request'
'401':
description: Unauthorized
'429':
$ref: '#/components/responses/quota'
'500':
description: Internal Server Error
/catalog/exports:
get:
summary: List export formats
operationId: listExportFormats
tags:
- Catalog
description: List available export formats
responses:
'200':
description: A list of available export formats
content:
application/json; charset=utf-8:
schema:
type: object
properties:
links:
type: array
items:
$ref: '#/components/schemas/links'
'400':
$ref: '#/components/responses/bad_request'
'401':
description: Unauthorized
'429':
$ref: '#/components/responses/quota'
'500':
description: Internal Server Error
/catalog/exports/{format}:
get:
summary: Export a catalog
operationId: exportDatasets
tags:
- Catalog
description: Export a catalog in the desired format.
parameters:
- $ref: '#/components/parameters/format-catalog'
- $ref: '#/components/parameters/select'
- $ref: '#/components/parameters/where'
- $ref: '#/components/parameters/order_by'
- $ref: '#/components/parameters/group_by'
- $ref: '#/components/parameters/limit_export'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/refine'
- $ref: '#/components/parameters/exclude'
- $ref: '#/components/parameters/lang'
- $ref: '#/components/parameters/timezone'
responses:
'200':
description: Return a file
'400':
$ref: '#/components/responses/bad_request'
'401':
description: Unauthorized
'429':
$ref: '#/components/responses/quota'
'500':
description: Internal Server Error
/catalog/exports/csv:
get:
summary: Export a catalog in CSV
operationId: exportCatalogCSV
tags:
- Catalog
description: Export a catalog in CSV (Comma Separated Values). Specific parameters are described here
parameters:
- name: delimiter
in: query
required: false
schema:
type: string
enum:
- ;
- ','
- "\t"
- '|'
default: ;
description: Sets the field delimiter of the CSV export
- name: list_separator
in: query
required: false
schema:
type: string
default: ','
description: Sets the separator character used for multivalued strings
- name: quote_all
in: query
required: false
schema:
type: boolean
default: false
description: Set it to true to force quoting all strings, i.e. surrounding all strings with quote characters
- name: with_bom
in: query
required: false
schema:
type: boolean
default: true
description: 'Set it to true to force the first characters of the CSV file to be a Unicode Byte Order Mask (0xFEFF). It usually makes Excel correctly open the output CSV file without warning.
**Warning:** the default value of this parameter is `false` in v2.0 and `true` starting with v2.1'
responses:
'200':
description: Return a file
'400':
$ref: '#/components/responses/bad_request'
'401':
description: Unauthorized
'429':
$ref: '#/components/responses/quota'
'500':
description: Internal Server Error
/catalog/exports/dcat{dcat_ap_format}:
get:
summary: Export a catalog in RDF/XML (DCAT)
operationId: exportCatalogDCAT
tags:
- Catalog
description: Export a catalog in RDF/XML described with DCAT (Data Catalog Vocabulary). Specific parameters are described here
parameters:
- $ref: '#/components/parameters/dcat_format'
- name: include_exports
in: query
required: false
schema:
$ref: '#/components/schemas/enum-format-datasets'
description: Sets the datasets exports exposed in the DCAT export. By default, all exports are exposed.
examples:
legacy:
summary: Only expose csv, json and geojson datasets exports
value: csv,json,geojson
- name: use_labels_in_exports
in: query
required: false
schema:
type: boolean
default: true
description: If set to `true`, this parameter will make distributions output the label of each field rather than its name. This parameter only applies on distributions that contain a list of the fields in their output (e.g., CSV, XLSX).
responses:
'200':
description: Return a file
'400':
$ref: '#/components/responses/bad_request'
'401':
description: Unauthorized
'429':
$ref: '#/components/responses/quota'
'500':
description: Internal Server Error
/catalog/facets:
get:
summary: List facet values
operationId: getDatasetsFacets
tags:
- Catalog
description: 'Enumerate facet values for datasets and returns a list of values for each facet.
Can be used to implement guided navigation in large result sets.'
parameters:
- $ref: '#/components/parameters/facet'
- $ref: '#/components/parameters/refine'
- $ref: '#/components/parameters/exclude'
- $ref: '#/components/parameters/where'
- $ref: '#/components/parameters/timezone'
responses:
'200':
description: An enumeration of facets
content:
application/json; charset=utf-8:
schema:
type: object
properties:
links:
type: array
items:
$ref: '#/components/schemas/links'
facets:
type: array
items:
$ref: '#/components/schemas/facet_enumeration'
examples:
catalog_facets:
$ref: '#/components/examples/catalog_facets'
'400':
$ref: '#/components/responses/bad_request'
'401':
description: Unauthorized
'429':
$ref: '#/components/responses/quota'
'500':
description: Internal Server Error
/catalog/datasets/{dataset_id}:
get:
summary: Show dataset information
operationId: getDataset
tags:
- Catalog
description: 'Returns a list of available endpoints for the specified dataset, with metadata and endpoints.
The response includes the following links:
* the attachments endpoint
* the files endpoint
* the records endpoint
* the catalog endpoint.'
parameters:
- $ref: '#/components/parameters/dataset_id'
- $ref: '#/components/parameters/select'
- $ref: '#/components/parameters/lang'
- $ref: '#/components/parameters/timezone'
- $ref: '#/components/parameters/include_links'
- $ref: '#/components/parameters/include_app_metas'
responses:
'200':
description: The dataset
content:
application/json; charset=utf-8json:
schema:
$ref: '#/components/schemas/dataset'
examples:
dataset:
$ref: '#/components/examples/dataset-v2.1'
'400':
$ref: '#/components/responses/bad_request'
'401':
description: Unauthorized
'429':
$ref: '#/components/responses/quota'
'500':
description: Internal Server Error
components:
schemas:
datasets:
type: object
properties:
total_count:
type: integer
_links:
type: array
items:
$ref: '#/components/schemas/links'
results:
type: array
items:
$ref: '#/components/schemas/dataset'
dataset:
type: object
additionalProperties: {}
properties:
_links:
type: array
items:
$ref: '#/components/schemas/links'
dataset_id:
type: string
dataset_uid:
type: string
readOnly: true
attachments:
type: array
items:
type: object
properties:
mimetype:
type: string
url:
type: string
id:
type: string
title:
type: string
has_records:
type: boolean
data_visible:
type: boolean
features:
type: array
description: 'A map of available features for a dataset, with the fields they apply to.
'
items:
type: string
metas:
type: object
fields:
type: array
items:
type: object
properties:
name:
type: string
label:
type: string
type:
type: string
annotations:
type: object
description:
type: string
nullable: true
links:
type: object
properties:
href:
type: string
format: uri
rel:
type: string
enum:
- self
- first
- last
- next
- dataset
- catalog
enum-format-datasets:
type: string
enum:
- csv
- fgb
- geojson
- gpx
- json
- jsonl
- jsonld
- kml
- n3
- ov2
- parquet
- rdfxml
- shp
- turtle
- xlsx
facet_value_enumeration:
type: object
properties:
name:
type: string
count:
type: integer
value:
type: string
state:
type: string
facet_enumeration:
type: object
properties:
name:
type: string
facets:
type: array
items:
$ref: '#/components/schemas/facet_value_enumeration'
parameters:
facet:
name: facet
in: query
description: "A facet is a field used for simple filtering (through the `refine` and `exclude` parameters) or exploration (with the `/facets` endpoint).\n\nIt can also be a function such as `facet=facet(name=\"field_name\")` which is identical to `facet=field_name`. But this `facet()` function\ncan also take some optional arguments such as `disjunctive`, `hierarchical`, `separator`, `sort` and `limit`.\n\n* `disjunctive`: a boolean `true/false`, whether multiple values can be selected for the facet\n* `hierarchical`: a boolean `true/false` if the field is hierarchical. The separator must be given as the argument.\n For instance, you can do `facet=facet(name=\"filepath\", hierarchical=true, separator=\"/\")` to retrieve facets related to this field which might look like `\"/home/user/file.txt\"`\n* `separator`: a string, e.g. `/`, `-`, `;`\n* `sort`: a string which describes how to sort the facets. Possible arguments are `count` and `-count` for all field types, `alphanum` and `-alphanum` for `date`, `datetime` and `text`, `num` and `-num` for `decimal` and `int`\n* `limit`: an integer to limit the number of results\n"
style: form
explode: true
schema:
type: string
exclude:
name: exclude
in: query
description: 'Examples:
- `exclude=city:Paris` - Exclude the value `Paris` from the `city` facet. Facets enumeration will display `Paris` as `excluded` without any count information.
- `exclude=modified:2019/12` - Exclude the value `2019/12` from the `modified` facet. Facets enumeration will display `2020` as `excluded` without any count information.
A facet filter used to exclude a facet value from the result set.
Using this parameter, you can filter your query to exclude the selected facet value in the response.
`exclude` uses the following syntax: `exclude=<FACETNAME>:<FACETVALUE>`
**`exclude` must not be confused with a `where` filter. Excluding a facet value is equivalent to removing an entry in the left navigation panel.**'
style: form
explode: true
schema:
type: string
limit_export:
name: limit
in: query
description: 'Number of items to return in export.
Use -1 (default) to retrieve all records
'
schema:
minimum: -1
type: integer
default: -1
refine:
name: refine
in: query
description: 'Example: `refine=modified:2020` - Return only the value `2020` from the `modified` facet.
A facet filter used to limit the result set.
Using this parameter, you can refine your query to display only the selected facet value in the response.
Refinement uses the following syntax: `refine=<FACETNAME>:<FACETVALUE>`
For date, and other hierarchical facets, when refining on one value, all second-level values related to that entry will appear in facets enumeration. For example, after refining on the year 2019, the related second-level month will appear. And when refining on August 2019, the third-level day will appear.
**`refine` must not be confused with a `where` filter. Refining with a facet is equivalent to selecting an entry in the left navigation panel.**'
style: form
explode: true
schema:
type: string
select:
name: select
in: query
description: "Examples:\n- `select=size` - Example of select, which only return the \"size\" field.\n- `select=size * 2 as bigger_size` - Example of a complex expression with a label, which returns a new field named \"bigger_size\" and containing the double of size field value.\n- `select=dataset_id, fields` - Example of a select in catalog ODSQL query to only retrieve dataset_id and schema of datasets.\n\nA select expression can be used to add, remove or change the fields to return.\nAn expression can be:\n - a wildcard ('*'): all fields are returned.\n - A field name: only the specified field is returned.\n - An include/exclude function: All fields matching the include or exclude expression are included or excluded. This expression can contain wildcard.\n - A complex expression. The result of the expression is returned. A label can be set for this expression, and in that case, the field will be named after this label."
schema:
type: string
order_by:
name: order_by
in: query
description: 'Example: `order_by=sum(age) desc, name asc`
A comma-separated list of field names or aggregations to sort on, followed by an order (`asc` or `desc`).
Results are sorted in ascending order by default. To sort results in descending order, use the `desc` keyword.'
style: form
explode: false
schema:
type: string
dcat_format:
name: dcat_ap_format
in: path
required: true
schema:
type: string
enum:
- _ap_ch
- _ap_de
- _ap_se
- _ap_sp
- _ap_it
- _ap_vl
- _ap_benap
description: 'DCAT format specifier for the catalog export.
`dcat_ap_*` formats are only available upon activation.'
style: simple
include_links:
name: include_links
in: query
description: 'If set to `true`, this parameter will add HATEOAS links in the response.
'
schema:
type: boolean
default: false
where:
name: where
in: query
description: 'A `where` filter is a text expression performing a simple full-text search that can also include logical operations
(NOT, AND, OR...) and lots of other functions to perform complex and precise search operations.
For more information, see [Opendatasoft Query Language (ODSQL)](<https://help.huwise.com/apis/ods-explore-v2/#section/Opendatasoft-Query-Language-(ODSQL)/Where-clause>) reference documentation.'
schema:
type: string
lang:
name: lang
in: query
description: 'A language value.
If specified, the `lang` value override the default language, which is "fr".
The language is used to format string, for example in the `date_format` function.'
schema:
type: string
enum:
- en
- fr
- nl
- pt
- it
- ar
- de
- es
- ca
- eu
- sv
style: form
timezone:
name: timezone
in: query
description: 'Set the timezone for datetime fields.
Timezone IDs are defined by the [Unicode CLDR project](https://github.com/unicode-org/cldr). The list of timezone IDs is available in [timezone.xml](https://github.com/unicode-org/cldr/blob/master/common/bcp47/timezone.xml).'
schema:
type: string
default: UTC
examples:
UTC:
summary: UTC timezone
value: UTC
Europe/Paris:
summary: Paris timezone
value: Europe/Paris
US/Eastern:
summary: Eastern timezone
value: US/Eastern
Europe/London:
summary: London timezone
value: Europe/London
Europe/Berlin:
summary: Berlin timezone
value: Europe/Berlin
format-catalog:
name: format
in: path
required: true
schema:
type: string
enum:
- csv
- data.json
- dcat
- dcat_ap_ch
- dcat_ap_de
- dcat_ap_se
- dcat_ap_sp
- dcat_ap_it
- dcat_ap_vl
- dcat_ap_benap
- dublin_core
- json
- rdf
- rss
- ttl
- xlsx
description: 'Format specifier for the catalog export.
`dcat_ap_*` formats are only available upon activation.
See [here](#tag/Catalog/operation/listExportFormats) to get the list of available export formats'
style: simple
group_by:
name: group_by
in: query
description: "Example: `group_by=city_field as city`\n\nA group by expression defines a grouping function for an aggregation.\nIt can be:\n - a field name: group result by each value of this field\n - a range function: group result by range\n - a date function: group result by date\n\nIt is possible to specify a custom name with the 'as name' notation."
style: form
explode: false
schema:
type: string
dataset_id:
name: dataset_id
in: path
description: 'The identifier of the dataset to be queried.
You can find it in the "Information" tab of the dataset page or in the dataset URL, right after `/datasets/`.'
required: true
schema:
type: string
include_app_metas:
name: include_app_metas
in: query
description: 'If set to `true`, this parameter will add application metadata to the response.
'
schema:
type: boolean
default: false
offset:
name: offset
in: query
description: 'Index of the first item to return (starting at 0).
To use with the `limit` parameter to implement pagination.
**Note:** the maximum value depends on the type of query, see the note on `limit` for the details
'
schema:
minimum: 0
type: integer
default: 0
limit:
name: limit
in: query
description: "Number of items to return.\n\nTo use with the `offset` parameter to implement pagination.\n\nThe maximum possible value depends on whether the query contains a `group_by` clause or not.\n\nFor a query **without** a `group_by`:\n - the maximum value for `limit` is 100,\n - `offset+limit` should be less than 10000\n\nFor a query **with** a `group_by`:\n - the maximum value for `limit` is 20000,\n - `offset+limit` should be less than 20000\n\n**Note:** If you need more results, please use the /exports endpoint.\n"
schema:
maximum: 100
minimum: -1
type: integer
default: 10
examples:
dataset-v2.1:
value:
dataset_id: geonames-all-cities-with-a-population-1000
dataset_uid: da_s2n5ed
attachments: []
has_records: true
data_visible: true
fields:
- description: null
label: Geoname ID
type: text
name: geoname_id
annotations:
facetsort:
- -count
id: []
- description: null
label: Name
type: text
name: name
annotations:
sortable: []
- annotations: {}
description: null
type: text
name: ascii_name
label: ASCII Name
- description: null
label: Alternate Names
type: text
name: alternate_names
annotations:
multivalued:
- ','
- annotations: {}
label: Feature Class
type: text
name: feature_class
description: see http://www.geonames.org/export/codes.html
- annotations: {}
label: Feature Code
type: text
name: feature_code
description: see http://www.geonames.org/export/codes.html
- annotations: {}
description: null
type: text
name: country_code
label: Country Code
- description: null
label: Country name EN
type: text
name: cou_name_en
annotations:
facet: []
facetsort:
- alphanum
disjunctive: []
- annotations: {}
description: null
type: text
name: country_code_2
label: Country Code 2
- annotations: {}
description: null
type: text
name: admin1_code
label: Admin1 Code
- description: null
label: Admin2 Code
type: text
name: admin2_code
annotations:
facetsort:
- -count
- annotations: {}
description: null
type: text
name: admin3_code
label: Admin3 Code
- annotations: {}
description: null
type: text
name: admin4_code
label: Admin4 Code
- annotations: {}
description: null
type: int
name: population
label: Population
- annotations: {}
description: null
type: text
name: elevation
label: Elevation
- annotations: {}
description: null
type: int
name: dem
label: DIgital Elevation Model
- description: null
label: Timezone
type: text
name: timezone
annotations:
facet: []
hierarchical:
- /
- annotations: {}
description: null
type: date
name: modification_date
label: Modification date
- annotations: {}
description: null
type: text
name: label_en
label: LABEL EN
- description: null
label: Coordinates
type: geo_point_2d
name: coordinates
annotations:
facetsort:
- -count
metas:
default:
records_count: 137611
modified: '2021-06-23T07:50:20+00:00'
source_domain_address: null
references: https://download.geonames.org/export/dump/
keyword:
- Geonames
- city
- world
source_domain_title: null
geographic_reference:
- world
timezone: null
title: Geonames - All Cities with a population > 1000
parent_domain: null
theme:
- Administration, Government, Public finances, Citizenship
modified_updates_on_data_change: true
metadata_processed: '2021-06-23T07:50:26.162000+00:00'
data_processed: '2021-06-22T08:47:08+00:00'
territory:
- World
description: "<p>All cities with a population > 1000 or seats of adm div (ca 80.000)</p><h4>Sources and Contributions</h4><ul><li><strong>Sources</strong> : GeoNames is aggregating over hundred different <a href=\"http://www.geonames.org/data-sources.html\">data sources</a>. \t</li><li><strong>Ambassadors</strong> : <a href=\"http://www.geonames.org/team.html#ambassadors\">GeoNames Ambassadors</a> help in many countries. \t</li><li><strong>Wiki</strong> : A <a href=\"http://www.geonames.org/manual.html\">wiki</a> allows to view the data and quickly fix error and add missing places. \t</li><li><strong>Donations and Sponsoring</strong> : Costs for running GeoNames are covered by <a href=\"http://www.geonames.org/donations.html\">donations and sponsoring</a>.</li></ul><p><b>Enrichment:</b></p><ul><li>add country name</li></ul>"
modified_updates_on_metadata_change: false
shared_catalog: null
source_domain: null
attributions:
- https://www.geonames.org/about.html
geographic_area_mode: null
geographic_reference_auto: true
geographic_area: null
publisher: GeoNames
language: en
license: CC BY 4.0
source_dataset: null
metadata_languages:
- en
oauth_scope: null
federated: true
license_url: https://creativecommons.org/licenses/by/4.0/
features:
- geo
- analyze
- timeserie
catalog_facets:
value:
links: []
facets:
- name: publisher
facets:
- count: 2
state: displayed
name: Opendatasoft
value: Opendatasoft
- count: 2
state: displayed
name: Opendatasoft - Data Team
value: Opendatasoft - Data Team
- name: features
facets:
- count: 19
state: displayed
name: analyze
value: analyze
- count: 13
state: displayed
name: timeserie
value: timeserie
- name: language
facets:
- count: 17
state: displayed
name: en
value: en
- count: 4
state: displayed
name: fr
value: fr
datasets-v2.1:
value:
total_count: 19
results:
- dataset_id: world-administrative-boundaries-countries-and-territories
dataset_uid: da_6kvv9v
attachments: []
has_records: true
data_visible: true
fields:
- annotations: {}
description: null
type: geo_point_2d
name: geo_point_2d
label: Geo Point
- annotations: {}
description: null
type: geo_shape
name: geo_shape
label: Geo Shape
- description: null
label: Status
type: text
name: status
annotations:
facet: []
- description: ISO 3 code of the country to which the territory belongs
label: ISO 3 country code
type: text
name: color_code
annotations:
facet: []
- description: null
label: Region of the territory
type: text
name: region
annotations:
facet: []
- description: null
label: ISO 3 territory code
type: text
name: iso3
annotations:
sortable: []
- description: null
label: Continent of the territory
type: text
name: continent
annotations:
facet: []
- description: Name of the territory
label: English Name
type: text
name: name
annotations:
sortable: []
- annotations: {}
description: null
type: text
name: iso_3166_1_alpha_2_codes
label: ISO 3166-1 Alpha 2-Codes
- annotations: {}
label: French Name
type: text
name: french_short
description: French term, when it is available in https://data.opendatasoft.com/explore/dataset/countries-territories-taxonomy-mvp-ct-taxonomy-with-hxl-tags1@public/table/, English name otherwise
metas:
default:
records_count: 256
modified: '2021-06-23T14:59:57+00:00'
source_domain_address: null
references: https://geonode.wfp.org/layers/geonode:wld_bnd_adm0_wfp
keyword:
- United Nation
- ISO-3 code
- Countries
- Territories
- Shape
- Boundaries
source_domain_title: null
geographic_reference:
- world
timezone: null
title: World Administrative Boundaries - Countries and Territories
parent_domain: null
theme:
- Administration, Government, Public finances, Citizenship
modified_updates_on_data_change: false
metadata_processed: '2021-06-23T15:00:02.656000+00:00'
data_processed: '2019-05-15T07:49:01+00:00'
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/opendatasoft/refs/heads/main/openapi/opendatasoft-catalog-api-openapi.yml