{ "opencollection": "1.0.0", "info": { "name": "Explore Catalog Dataset API", "version": "v2.1" }, "request": { "auth": { "type": "apikey", "key": "apikey", "value": "{{apikey}}", "placement": "query" } }, "items": [ { "info": { "name": "Dataset", "type": "folder" }, "items": [ { "info": { "name": "Query dataset records", "type": "http" }, "http": { "method": "GET", "url": "https://data.enseignementsup-recherche.gouv.fr/api/explore/v2.1/catalog/datasets/:dataset_id/records", "params": [ { "name": "dataset_id", "value": "", "type": "path", "description": "The identifier of the dataset to be queried.\n\nYou can find it in the \"Information\" tab of the dataset page or in the dataset URL, right after `/datasets/`." }, { "name": "select", "value": "", "type": "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." }, { "name": "where", "value": "", "type": "query", "description": "A `where` filter is a text expression performing a simple full-text search that can also include logical operations\n(NOT, AND, OR...) and lots of other functions to perform complex and precise search operations.\n\nFor more information, see [Opendatasoft Query Language (ODSQL)]() reference documentation." }, { "name": "group_by", "value": "", "type": "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." }, { "name": "order_by", "value": "", "type": "query", "description": "Example: `order_by=sum(age) desc, name asc`\n\nA comma-separated list of field names or aggregations to sort on, followed by an order (`asc` or `desc`).\n\nResults are sorted in ascending order by default. To sort results in descending order, use the `desc` keyword." }, { "name": "limit", "value": "", "type": "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" }, { "name": "offset", "value": "", "type": "query", "description": "Index of the first item to return (starting at 0).\n\nTo use with the `limit` parameter to implement pagination.\n\n**Note:** the maximum value depends on the type of query, see the note on `limit` for the details\n" }, { "name": "refine", "value": "", "type": "query", "description": "Example: `refine=modified:2020` - Return only the value `2020` from the `modified` facet.\n\nA facet filter used to limit the result set.\nUsing this parameter, you can refine your query to display only the selected facet value in the response.\n\nRefinement uses the following syntax: `refine=:`\n\nFor 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.\n\n**`refine` must not be confused with a `where` filter. Refining with a facet is equivalent to selecting an entry in the left navigation panel.**" }, { "name": "exclude", "value": "", "type": "query", "description": "Examples:\n- `exclude=city:Paris` - Exclude the value `Paris` from the `city` facet. Facets enumeration will display `Paris` as `excluded` without any count information.\n- `exclude=modified:2019/12` - Exclude the value `2019/12` from the `modified` facet. Facets enumeration will display `2020` as `excluded` without any count information.\n\nA facet filter used to exclude a facet value from the result set.\nUsing this parameter, you can filter your query to exclude the selected facet value in the response.\n\n`exclude` uses the following syntax: `exclude=:`\n\n**`exclude` must not be confused with a `where` filter. Excluding a facet value is equivalent to removing an entry in the left navigation panel.**" }, { "name": "lang", "value": "", "type": "query", "description": "A language value.\n\nIf specified, the `lang` value override the default language, which is \"fr\".\nThe language is used to format string, for example in the `date_format` function." }, { "name": "timezone", "value": "", "type": "query", "description": "Set the timezone for datetime fields.\n\nTimezone 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)." }, { "name": "include_links", "value": "", "type": "query", "description": "If set to `true`, this parameter will add HATEOAS links in the response.\n" }, { "name": "include_app_metas", "value": "", "type": "query", "description": "If set to `true`, this parameter will add application metadata to the response.\n" } ] }, "docs": "Perform a query on dataset records." }, { "info": { "name": "List export formats", "type": "http" }, "http": { "method": "GET", "url": "https://data.enseignementsup-recherche.gouv.fr/api/explore/v2.1/catalog/datasets/:dataset_id/exports", "params": [ { "name": "dataset_id", "value": "", "type": "path", "description": "The identifier of the dataset to be queried.\n\nYou can find it in the \"Information\" tab of the dataset page or in the dataset URL, right after `/datasets/`." } ] }, "docs": "List available export formats" }, { "info": { "name": "Export a dataset", "type": "http" }, "http": { "method": "GET", "url": "https://data.enseignementsup-recherche.gouv.fr/api/explore/v2.1/catalog/datasets/:dataset_id/exports/:format", "params": [ { "name": "dataset_id", "value": "", "type": "path", "description": "The identifier of the dataset to be queried.\n\nYou can find it in the \"Information\" tab of the dataset page or in the dataset URL, right after `/datasets/`." }, { "name": "format", "value": "", "type": "path" }, { "name": "select", "value": "", "type": "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." }, { "name": "where", "value": "", "type": "query", "description": "A `where` filter is a text expression performing a simple full-text search that can also include logical operations\n(NOT, AND, OR...) and lots of other functions to perform complex and precise search operations.\n\nFor more information, see [Opendatasoft Query Language (ODSQL)]() reference documentation." }, { "name": "order_by", "value": "", "type": "query", "description": "Example: `order_by=sum(age) desc, name asc`\n\nA comma-separated list of field names or aggregations to sort on, followed by an order (`asc` or `desc`).\n\nResults are sorted in ascending order by default. To sort results in descending order, use the `desc` keyword." }, { "name": "group_by", "value": "", "type": "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." }, { "name": "limit", "value": "", "type": "query", "description": "Number of items to return in export.\n\nUse -1 (default) to retrieve all records\n" }, { "name": "refine", "value": "", "type": "query", "description": "Example: `refine=modified:2020` - Return only the value `2020` from the `modified` facet.\n\nA facet filter used to limit the result set.\nUsing this parameter, you can refine your query to display only the selected facet value in the response.\n\nRefinement uses the following syntax: `refine=:`\n\nFor 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.\n\n**`refine` must not be confused with a `where` filter. Refining with a facet is equivalent to selecting an entry in the left navigation panel.**" }, { "name": "exclude", "value": "", "type": "query", "description": "Examples:\n- `exclude=city:Paris` - Exclude the value `Paris` from the `city` facet. Facets enumeration will display `Paris` as `excluded` without any count information.\n- `exclude=modified:2019/12` - Exclude the value `2019/12` from the `modified` facet. Facets enumeration will display `2020` as `excluded` without any count information.\n\nA facet filter used to exclude a facet value from the result set.\nUsing this parameter, you can filter your query to exclude the selected facet value in the response.\n\n`exclude` uses the following syntax: `exclude=:`\n\n**`exclude` must not be confused with a `where` filter. Excluding a facet value is equivalent to removing an entry in the left navigation panel.**" }, { "name": "lang", "value": "", "type": "query", "description": "A language value.\n\nIf specified, the `lang` value override the default language, which is \"fr\".\nThe language is used to format string, for example in the `date_format` function." }, { "name": "timezone", "value": "", "type": "query", "description": "Set the timezone for datetime fields.\n\nTimezone 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)." }, { "name": "use_labels", "value": "", "type": "query", "description": "If set to `true`, this parameter will make exports output the label of each field rather than its name.\n\nThis parameter only makes sense for formats that contain a list of the fields in their output.\n" }, { "name": "compressed", "value": "", "type": "query", "description": "If set to `true`, this parameter can compress the output file of a specific export format with GZIP, e.g. `.csv.gzip`.\n" }, { "name": "epsg", "value": "", "type": "query", "description": "This parameter sets the EPSG code to project shapes into for formats that support geometric features.\n" } ] }, "docs": "Export a dataset in the desired format.\n**Note:** The `group_by` parameter is only available on exports starting with the v2.1" }, { "info": { "name": "Export a dataset in CSV", "type": "http" }, "http": { "method": "GET", "url": "https://data.enseignementsup-recherche.gouv.fr/api/explore/v2.1/catalog/datasets/:dataset_id/exports/csv", "params": [ { "name": "dataset_id", "value": "", "type": "path", "description": "The identifier of the dataset to be queried.\n\nYou can find it in the \"Information\" tab of the dataset page or in the dataset URL, right after `/datasets/`." }, { "name": "delimiter", "value": "", "type": "query", "description": "Sets the field delimiter of the CSV export" }, { "name": "list_separator", "value": "", "type": "query", "description": "Sets the separator character used for multivalued strings" }, { "name": "quote_all", "value": "", "type": "query", "description": "Set it to true to force quoting all strings, i.e. surrounding all strings with quote characters" }, { "name": "with_bom", "value": "", "type": "query", "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.\n**Warning:** the default value of this parameter is `false` in v2.0 and `true` starting with v2.1" } ] }, "docs": "Export a dataset in CSV (Comma Separated Values). Specific parameters are described here" }, { "info": { "name": "Export a dataset in Parquet", "type": "http" }, "http": { "method": "GET", "url": "https://data.enseignementsup-recherche.gouv.fr/api/explore/v2.1/catalog/datasets/:dataset_id/exports/parquet", "params": [ { "name": "dataset_id", "value": "", "type": "path", "description": "The identifier of the dataset to be queried.\n\nYou can find it in the \"Information\" tab of the dataset page or in the dataset URL, right after `/datasets/`." }, { "name": "parquet_compression", "value": "", "type": "query", "description": "Sets the compression parameter for the Parquet export file" } ] }, "docs": "Export a dataset in Parquet. Specific parameters are described here" }, { "info": { "name": "Export a dataset in GPX", "type": "http" }, "http": { "method": "GET", "url": "https://data.enseignementsup-recherche.gouv.fr/api/explore/v2.1/catalog/datasets/:dataset_id/exports/gpx", "params": [ { "name": "dataset_id", "value": "", "type": "path", "description": "The identifier of the dataset to be queried.\n\nYou can find it in the \"Information\" tab of the dataset page or in the dataset URL, right after `/datasets/`." }, { "name": "name_field", "value": "", "type": "query", "description": "Sets the field that is used as the 'name' attribute in the GPX output" }, { "name": "description_field_list", "value": "", "type": "query", "description": "Sets the fields to use in the 'description' attribute of the GPX output" }, { "name": "use_extension", "value": "", "type": "query", "description": "Set it to true to use the `` tag for attributes (as GDAL does). Set it to false to use the `` tag for attributes.\n**Warning:** the default value of this parameter is `false` in v2.0 and `true` starting with v2.1" } ] }, "docs": "Export a dataset in GPX. Specific parameters are described here" }, { "info": { "name": "List dataset facets", "type": "http" }, "http": { "method": "GET", "url": "https://data.enseignementsup-recherche.gouv.fr/api/explore/v2.1/catalog/datasets/:dataset_id/facets", "params": [ { "name": "dataset_id", "value": "", "type": "path", "description": "The identifier of the dataset to be queried.\n\nYou can find it in the \"Information\" tab of the dataset page or in the dataset URL, right after `/datasets/`." }, { "name": "where", "value": "", "type": "query", "description": "A `where` filter is a text expression performing a simple full-text search that can also include logical operations\n(NOT, AND, OR...) and lots of other functions to perform complex and precise search operations.\n\nFor more information, see [Opendatasoft Query Language (ODSQL)]() reference documentation." }, { "name": "refine", "value": "", "type": "query", "description": "Example: `refine=modified:2020` - Return only the value `2020` from the `modified` facet.\n\nA facet filter used to limit the result set.\nUsing this parameter, you can refine your query to display only the selected facet value in the response.\n\nRefinement uses the following syntax: `refine=:`\n\nFor 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.\n\n**`refine` must not be confused with a `where` filter. Refining with a facet is equivalent to selecting an entry in the left navigation panel.**" }, { "name": "exclude", "value": "", "type": "query", "description": "Examples:\n- `exclude=city:Paris` - Exclude the value `Paris` from the `city` facet. Facets enumeration will display `Paris` as `excluded` without any count information.\n- `exclude=modified:2019/12` - Exclude the value `2019/12` from the `modified` facet. Facets enumeration will display `2020` as `excluded` without any count information.\n\nA facet filter used to exclude a facet value from the result set.\nUsing this parameter, you can filter your query to exclude the selected facet value in the response.\n\n`exclude` uses the following syntax: `exclude=:`\n\n**`exclude` must not be confused with a `where` filter. Excluding a facet value is equivalent to removing an entry in the left navigation panel.**" }, { "name": "facet", "value": "", "type": "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" }, { "name": "lang", "value": "", "type": "query", "description": "A language value.\n\nIf specified, the `lang` value override the default language, which is \"fr\".\nThe language is used to format string, for example in the `date_format` function." }, { "name": "timezone", "value": "", "type": "query", "description": "Set the timezone for datetime fields.\n\nTimezone 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)." } ] }, "docs": "Enumerates facet values for records and returns a list of values for each facet.\nCan be used to implement guided navigation in large result sets.\n" }, { "info": { "name": "List dataset attachments", "type": "http" }, "http": { "method": "GET", "url": "https://data.enseignementsup-recherche.gouv.fr/api/explore/v2.1/catalog/datasets/:dataset_id/attachments", "params": [ { "name": "dataset_id", "value": "", "type": "path", "description": "The identifier of the dataset to be queried.\n\nYou can find it in the \"Information\" tab of the dataset page or in the dataset URL, right after `/datasets/`." } ] }, "docs": "Returns a list of all available attachments for a dataset.\n" }, { "info": { "name": "Read a dataset record", "type": "http" }, "http": { "method": "GET", "url": "https://data.enseignementsup-recherche.gouv.fr/api/explore/v2.1/catalog/datasets/:dataset_id/records/:record_id", "params": [ { "name": "dataset_id", "value": "", "type": "path", "description": "The identifier of the dataset to be queried.\n\nYou can find it in the \"Information\" tab of the dataset page or in the dataset URL, right after `/datasets/`." }, { "name": "record_id", "value": "", "type": "path", "description": "Record identifier" }, { "name": "select", "value": "", "type": "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." }, { "name": "lang", "value": "", "type": "query", "description": "A language value.\n\nIf specified, the `lang` value override the default language, which is \"fr\".\nThe language is used to format string, for example in the `date_format` function." }, { "name": "timezone", "value": "", "type": "query", "description": "Set the timezone for datetime fields.\n\nTimezone 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)." } ] }, "docs": "Reads a single dataset record based on its identifier.\n" } ] } ], "bundled": true }