swagger: "2.0"
schemes:
  - https
host: public.opendatasoft.com
basePath: /api/v2
info:
  contact:
    x-twitter: opendatasoft
  title: opendatasoft
  version: 2.1.0
  x-apisguru-categories:
    - open_data
  x-logo:
    url: https://twitter.com/opendatasoft/profile_image?size=original
  x-origin:
    - format: swagger
      url: http://public.opendatasoft.com/api/v2/swagger.json
      version: "2.0"
    - format: swagger
      url: http://public.opendatasoft.com/api/v2/swagger.json
      version: "2.0"
  x-providerName: opendatasoft.com
produces:
  - application/json
securityDefinitions:
  api_key:
    in: query
    name: apikey
    type: apiKey
  basic:
    type: basic
security:
  - api_key: []
  - basic: []
parameters:
  attachment_id:
    in: path
    name: attachment_id
    required: true
    type: string
  dataset_id:
    description: |
      Dataset identifier.

      Can be found in the "information" tab of the dataset page.
    in: path
    name: dataset_id
    required: true
    type: string
  exclude:
    collectionFormat: multi
    description: |
      An array of facet filters. For example **city:Paris** or **modified:2019/12**.
      The request will exclude the defined facet value.

      Read [filtering with facets value](https://help.opendatasoft.com/apis/ods-search-v2/#filtering-with-facets-values) for more details.

      *Not to be confused with a where filter. Excluding a facet value is equivalent to removing an entry in the left navigation panel.*

      *exclude is not available for monitoring sources*
    in: query
    items:
      type: string
    name: exclude
    required: false
    type: array
  facet:
    collectionFormat: multi
    description: |
      A facet is a field used for simple filtering (through the parameters refine and exclude) or exploration (with the endpoint `/facets`).

      Facets can be configured in the back-office or with this parameter.

      Read [the facets documentation](https://help.opendatasoft.com/apis/ods-search-v2/#facets) for more details.
    in: query
    items:
      type: string
    name: facet
    type: array
  file_id:
    in: path
    name: file_id
    required: true
    type: string
  group_by:
    description: |
      A group by expression defines a grouping function for an aggregation.
      It can be:
       - a field name: group result by each value of this field
       - a range function: group result by range
       - a date function: group result by date
      It is possible to specify a custom name with the 'as name' notation. For instance: group_by='city_field as city'.
    in: query
    name: group_by
    required: false
    type: string
  include_app_metas:
    default: false
    description: |
      Explicitely request application metas for each datasets.
    in: query
    name: include_app_metas
    type: boolean
  limit:
    default: 10
    description: |
      Number of items to return.

      To use in conjonction with offset to implement pagination.

      Limit maximum value is 100. To retrive more data use export entry points.
      The default value is 10.
    in: query
    maximum: 100
    minimum: -1
    name: limit
    required: false
    type: integer
  limit_export:
    default: -1
    description: |
      Number of items to return in export.

      Use -1 (default) to retrieve all records
    in: query
    minimum: -1
    name: limit
    required: false
    type: integer
  metadata_template_name:
    in: path
    name: metadata_template_name
    required: true
    type: string
  metadata_template_type:
    default: basic
    enum:
      - basic
      - interop
      - extra
    in: path
    name: metadata_template_type
    required: true
    type: string
  mime_type:
    description: Specify one (or many) mime type(s) and return only the files matching said type(s).
    in: query
    name: mime_type
    required: false
    type: string
  offset:
    default: 0
    description: |
      Index of the first item to return (starting at 0).

      To use in conjonction with limit to implement pagination.
    in: query
    minimum: 0
    name: offset
    required: false
    type: integer
  order_by:
    description: |
      A comma-separated list of field names or aggregations to sort on, followed by an order (`asc` or `desc`).

      Sorts results according to the specified fields' values in ascending order by default.
      To sort results in descending order, use the `desc` keyword.

      Example: `sum(age) desc, name asc`
    in: query
    items:
      collectionFormat: csv
      type: string
    name: order_by
    required: false
    type: array
  pretty:
    default: false
    description: Activate pretty print
    in: query
    name: pretty
    type: boolean
  record_id:
    in: path
    name: record_id
    required: true
    type: string
  refine:
    collectionFormat: multi
    description: |
      An array of facet filters. For example **city:Paris** or **modified:2019/12**.
      The request will only include the selected facet value.

      Read [filtering with facets value](https://help.opendatasoft.com/apis/ods-search-v2/#filtering-with-facets-values) for more details.

      *Not to be confused with a where filter. Refining with a facet is equivalent to selecting an entry in the left navigation panel.*

      *refine is not available for monitoring sources*
    in: query
    items:
      type: string
    name: refine
    required: false
    type: array
  reuse_id:
    in: path
    name: reuse_id
    required: true
    type: string
  search:
    collectionFormat: multi
    description: |
      An array of full text search.

      A full text search performs a prefixed text search for each provided terms in all visible fields of a catalog/dataset.
    in: query
    items:
      type: string
    name: search
    required: false
    type: array
  select:
    description: |
      A select expression can be used to add, remove or change fields to return.
      An expression can be:
        - a wildcard ('*'): return all fields
        - a field name: return only this field
        - an include/exclude function. Include (resp exclude) all field matching include/exclude expression. This expression can contain wildcard. For example: include(spa*) will return all fields begining with 'spa'
        - a complex expression: return the result of this expression. A label can be set for this expression, in that case, field will be named with this label. For instance: 'size * 2 as bigger_size' will return a new field named bigger_size and containing the double of size field value.
    in: query
    name: select
    required: false
    type: string
  slug:
    description: |
      Page slug.
    in: path
    name: slug
    required: true
    type: string
  snapshot_id:
    in: path
    name: snapshot_id
    required: true
    type: string
  sort:
    description: |
      **Deprecated, use `order_by` instead.**

      A list of field names, each possibly prefixed with a minus (-).

      Sorts results according to the specified fields' values. By default, the sort is ascending (from the smallest
      value to the biggest value). A minus sign (‘-‘) may be used to perform a descending sort. Sorting is only
      available on numeric fields (int, double, date and datetime) and on text fields which have the sortable
      annotation.
    in: query
    items:
      collectionFormat: csv
      type: string
    name: sort
    required: false
    type: array
  source:
    default: catalog
    description: |
      Each source represents a different catalog of datasets you'll be able to query.

      There are 2 sources available:

      * catalog: the catalog of datasets on your portal
      * opendatasoft: Opendatasoft's repository of public datasets, also available at
        [data.opendatasoft.com](https://data.opendatasoft.com/page/home/)
    enum:
      - catalog
      - opendatasoft
      - monitoring
    in: path
    name: source
    required: true
    type: string
  thumbnail_size:
    description: Set the size of the thumbnail representing the resource (attachment, image or file)
    in: query
    name: thumbnail_size
    type: string
  timezone:
    default: UTC
    description: Set timezone for datetime fields
    in: query
    name: timezone
    type: string
  where:
    collectionFormat: multi
    description: |
      An array of filters.

      A filter is a text expression performing a simple full-text search that can also include logical operations
      (NOT, AND, OR...) as well as lots of other functions, thus performing more complex and more precise searches.

      Read [the query language reference](https://docs.opendatasoft.com/api/explore/v2.html#where-clause) for more details.
    in: query
    items:
      type: string
    name: where
    required: false
    type: array
tags:
  - name: root
  - name: metadata
  - name: catalog
  - name: export catalog
  - name: dataset
  - name: export dataset
paths:
  /:
    get:
      description: |
        API entry point

        Provides links for:
        * catalog, your domain's list of datasets
        * opendatasoft, all datasets on the Opendatasoft network
      operationId: getRoot
      responses:
        "200":
          description: Provide a set of links to the most basic entry points in the API (sources)
          schema:
            properties:
              links:
                items:
                  $ref: "#/definitions/link"
                type: array
      tags:
        - root
        - ods
  /pages:
    get:
      description: |
        List of all pages from this portal.
      operationId: getPages
      responses:
        "200":
          description: List of all pages, each with their endpoint.
          schema:
            properties:
              links:
                items:
                  $ref: "#/definitions/link"
                type: array
              pages:
                items:
                  properties:
                    links:
                      items:
                        $ref: "#/definitions/link"
                      type: array
                    page:
                      $ref: "#/definitions/page"
                  type: object
                type: array
      tags:
        - page
        - ods
  "/pages/{slug}":
    get:
      description: |
        A single page's metadata from this portal
      operationId: getPage
      parameters:
        - $ref: "#/parameters/slug"
      responses:
        "200":
          description: A single page's metadata.
          schema:
            properties:
              links:
                items:
                  $ref: "#/definitions/link"
                type: array
              page:
                $ref: "#/definitions/page"
      tags:
        - page
        - ods
  "/{source}":
    get:
      description: |
        Source entry points

        Provides links for the source's datasets and metadata.
      operationId: getSource
      parameters:
        - $ref: "#/parameters/source"
      responses:
        "200":
          description: Provide a set of links to the basic entry points for the given source.
          schema:
            properties:
              links:
                items:
                  $ref: "#/definitions/link"
                type: array
      tags:
        - catalog
        - ods
  "/{source}/aggregates":
    get:
      description: |
        **Deprecated, use `/datasets` instead.**
      operationId: aggregateDatasets
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/select"
        - $ref: "#/parameters/where"
        - $ref: "#/parameters/group_by"
        - $ref: "#/parameters/order_by"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/facet"
        - $ref: "#/parameters/refine"
        - $ref: "#/parameters/exclude"
      responses:
        "200":
          description: Aggregation result
          schema:
            properties:
              aggregations:
                items:
                  $ref: "#/definitions/aggregation"
                type: array
              links:
                items:
                  $ref: "#/definitions/link"
                type: array
            type: object
      tags:
        - catalog
        - aggregations
        - ods
  "/{source}/datasets":
    get:
      description: |
        List of available datasets, each with their endpoints, paginated.

        Links provided:
        * previous page
        * next page
        * last page
        * first page
      operationId: getDatasets
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/select"
        - $ref: "#/parameters/where"
        - $ref: "#/parameters/group_by"
        - $ref: "#/parameters/sort"
        - $ref: "#/parameters/order_by"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/search"
        - $ref: "#/parameters/facet"
        - $ref: "#/parameters/refine"
        - $ref: "#/parameters/exclude"
        - $ref: "#/parameters/pretty"
        - $ref: "#/parameters/timezone"
        - $ref: "#/parameters/include_app_metas"
      responses:
        "200":
          description: List of available datasets
          schema:
            properties:
              datasets:
                items:
                  properties:
                    dataset:
                      $ref: "#/definitions/dataset"
                    links:
                      items:
                        $ref: "#/definitions/link"
                      type: array
                  type: object
                type: array
              links:
                items:
                  $ref: "#/definitions/link"
                type: array
              total_count:
                type: integer
      tags:
        - catalog
        - ods
  "/{source}/datasets/{dataset_id}":
    get:
      description: |
        List of available endpoints for the specified dataset, with metadata and endpoints.

        Will provide links for:
        * the attachments endpoint
        * the files endpoint
        * the records endpoint
        * the catalog endpoint
      operationId: getDataset
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/select"
        - $ref: "#/parameters/pretty"
        - $ref: "#/parameters/timezone"
        - $ref: "#/parameters/include_app_metas"
      responses:
        "200":
          description: The dataset
          schema:
            properties:
              dataset:
                $ref: "#/definitions/dataset"
              links:
                items:
                  $ref: "#/definitions/link"
                type: array
      tags:
        - dataset
        - ods
  "/{source}/datasets/{dataset_id}/aggregates":
    get:
      description: |
        **Deprecated, use `/records` instead.**
      operationId: aggregateRecords
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/select"
        - $ref: "#/parameters/where"
        - $ref: "#/parameters/group_by"
        - $ref: "#/parameters/order_by"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/facet"
        - $ref: "#/parameters/refine"
        - $ref: "#/parameters/exclude"
      responses:
        "200":
          description: Aggregation result
          schema:
            properties:
              aggregations:
                items:
                  $ref: "#/definitions/aggregation"
                type: array
              links:
                items:
                  $ref: "#/definitions/link"
                type: array
      tags:
        - dataset
        - aggregations
        - ods
  "/{source}/datasets/{dataset_id}/attachments":
    get:
      description: |
        Get list of all available attachments
      operationId: getDatasetAttachements
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
      responses:
        "200":
          description: List of all available attachments
          schema:
            properties:
              attachments:
                items:
                  $ref: "#/definitions/attachment"
                type: array
              links:
                items:
                  $ref: "#/definitions/link"
                type: array
      tags:
        - dataset
        - ods
  "/{source}/datasets/{dataset_id}/attachments/{attachment_id}":
    get:
      description: |
        Download attachment
      operationId: downloadDatasetAttachement
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/attachment_id"
      responses:
        "200":
          description: The requested attachment
      tags:
        - dataset
        - ods
  "/{source}/datasets/{dataset_id}/exports/csv":
    get:
      description: |
        Export dataset in CSV format
      operationId: exportRecordsCSV
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/select"
        - $ref: "#/parameters/where"
        - $ref: "#/parameters/sort"
        - $ref: "#/parameters/order_by"
        - $ref: "#/parameters/limit_export"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/facet"
        - $ref: "#/parameters/refine"
        - $ref: "#/parameters/exclude"
        - $ref: "#/parameters/timezone"
        - default: ;
          description: Provide a different delimiter (default ',').
          enum:
            - ","
            - ;
            - "|"
          in: query
          name: delimiter
          required: false
          type: string
      produces:
        - text/csv
      responses:
        "200":
          description: Return a CSV file
          schema:
            type: file
      tags:
        - export dataset
        - ods
  "/{source}/datasets/{dataset_id}/exports/geojson":
    get:
      description: |
        Export dataset in GEOJSON format
      operationId: exportRecordsGEOJSON
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/select"
        - $ref: "#/parameters/where"
        - $ref: "#/parameters/sort"
        - $ref: "#/parameters/order_by"
        - $ref: "#/parameters/limit_export"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/search"
        - $ref: "#/parameters/facet"
        - $ref: "#/parameters/refine"
        - $ref: "#/parameters/exclude"
        - $ref: "#/parameters/timezone"
        - $ref: "#/parameters/pretty"
      produces:
        - application/json
      responses:
        "200":
          description: Return a GEOJSON file
          schema:
            type: file
      tags:
        - export dataset
        - ods
  "/{source}/datasets/{dataset_id}/exports/ical":
    get:
      description: |
        Export dataset in ICAL format
      operationId: exportRecordsICAL
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/select"
        - $ref: "#/parameters/where"
        - $ref: "#/parameters/sort"
        - $ref: "#/parameters/order_by"
        - $ref: "#/parameters/limit_export"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/search"
        - $ref: "#/parameters/facet"
        - $ref: "#/parameters/refine"
        - $ref: "#/parameters/exclude"
        - $ref: "#/parameters/timezone"
      produces:
        - application/json
      responses:
        "200":
          description: Return an ICAL file
          schema:
            type: file
      tags:
        - export dataset
        - ods
  "/{source}/datasets/{dataset_id}/exports/json":
    get:
      description: |
        Export dataset in JSON format
      operationId: exportRecordsJSON
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/select"
        - $ref: "#/parameters/where"
        - $ref: "#/parameters/sort"
        - $ref: "#/parameters/order_by"
        - $ref: "#/parameters/limit_export"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/search"
        - $ref: "#/parameters/facet"
        - $ref: "#/parameters/refine"
        - $ref: "#/parameters/exclude"
        - $ref: "#/parameters/pretty"
        - $ref: "#/parameters/timezone"
      produces:
        - application/json
      responses:
        "200":
          description: Return a JSON file
          schema:
            type: file
      tags:
        - export dataset
        - ods
  "/{source}/datasets/{dataset_id}/exports/ov2":
    get:
      description: |
        Export dataset in OV2 format
      operationId: exportRecordsOV2
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/select"
        - $ref: "#/parameters/where"
        - $ref: "#/parameters/sort"
        - $ref: "#/parameters/order_by"
        - $ref: "#/parameters/limit_export"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/search"
        - $ref: "#/parameters/facet"
        - $ref: "#/parameters/refine"
        - $ref: "#/parameters/exclude"
        - $ref: "#/parameters/timezone"
      produces:
        - text/plain
      responses:
        "200":
          description: Return an ov2 file
          schema:
            type: file
      tags:
        - export dataset
        - ods
  "/{source}/datasets/{dataset_id}/exports/shp":
    get:
      description: |
        Export dataset in Esri shapefile (shp) format
      operationId: exportRecordsSHP
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/select"
        - $ref: "#/parameters/where"
        - $ref: "#/parameters/sort"
        - $ref: "#/parameters/order_by"
        - $ref: "#/parameters/limit_export"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/search"
        - $ref: "#/parameters/facet"
        - $ref: "#/parameters/refine"
        - $ref: "#/parameters/exclude"
        - $ref: "#/parameters/timezone"
      produces:
        - application/zip
      responses:
        "200":
          description: Return a Shapefile zip
          schema:
            type: file
      tags:
        - export dataset
        - ods
  "/{source}/datasets/{dataset_id}/exports/xls":
    get:
      description: |
        Export dataset in XLS (Excel) format
      operationId: exportRecordsXLS
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/select"
        - $ref: "#/parameters/where"
        - $ref: "#/parameters/sort"
        - $ref: "#/parameters/order_by"
        - $ref: "#/parameters/limit_export"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/search"
        - $ref: "#/parameters/facet"
        - $ref: "#/parameters/refine"
        - $ref: "#/parameters/exclude"
        - $ref: "#/parameters/timezone"
      produces:
        - xls
      responses:
        "200":
          description: Return an XLS file
          schema:
            type: file
      tags:
        - export dataset
        - ods
  "/{source}/datasets/{dataset_id}/facets":
    get:
      description: |
        Enumerate facets values for records and return a list of values for each facet.
        Can be used to implement guided navigation in large result sets.

        Read [the facets documentation](https://help.opendatasoft.com/apis/ods-search-v2/#enumerating-facets-values) for more details.
      operationId: getRecordsFacets
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/where"
        - $ref: "#/parameters/facet"
        - $ref: "#/parameters/refine"
        - $ref: "#/parameters/exclude"
        - $ref: "#/parameters/search"
        - $ref: "#/parameters/timezone"
      responses:
        "200":
          description: Facets enumeration
          schema:
            properties:
              facets:
                items:
                  $ref: "#/definitions/facet_enumeration"
                type: array
            type: object
      tags:
        - dataset
        - facet
        - ods
  "/{source}/datasets/{dataset_id}/feedback":
    put:
      description: |
        Create new feedback entry.
      operationId: sendDatasetFeedback
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
        - description: Feedback entry
          in: body
          name: feedback
          required: true
          schema:
            properties:
              comment:
                type: string
              newValues:
                description: New record value
                type: object
              recordid:
                description: Feedback entry's recordid
                type: string
              schema:
                description: Record schema
                type: object
      responses:
        "201":
          description: |
            Success message: {status: 'ok'}
      tags:
        - dataset
        - ods
  "/{source}/datasets/{dataset_id}/files/{file_id}":
    get:
      description: |
        Download file
      operationId: getDatasetFile
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/file_id"
        - $ref: "#/parameters/thumbnail_size"
      responses:
        "200":
          description: The requested file, or its thumbnail (if thumbnail_size is specified)
      tags:
        - dataset
        - ods
  "/{source}/datasets/{dataset_id}/records":
    get:
      description: |
        Search dataset's records.
      operationId: getRecords
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/select"
        - $ref: "#/parameters/where"
        - $ref: "#/parameters/group_by"
        - $ref: "#/parameters/sort"
        - $ref: "#/parameters/order_by"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/search"
        - $ref: "#/parameters/facet"
        - $ref: "#/parameters/refine"
        - $ref: "#/parameters/exclude"
        - $ref: "#/parameters/pretty"
        - $ref: "#/parameters/timezone"
      responses:
        "200":
          description: Records
          schema:
            properties:
              links:
                items:
                  $ref: "#/definitions/link"
                type: array
              records:
                items:
                  properties:
                    links:
                      items:
                        $ref: "#/definitions/link"
                      type: array
                    record:
                      $ref: "#/definitions/record"
                  type: object
                type: array
              total_count:
                type: integer
      tags:
        - dataset
        - ods
  "/{source}/datasets/{dataset_id}/records/{record_id}":
    get:
      description: |
        Retrieve a single record based on its ID.
      operationId: getRecord
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/record_id"
        - $ref: "#/parameters/select"
        - $ref: "#/parameters/pretty"
        - $ref: "#/parameters/timezone"
      responses:
        "200":
          description: A single record
          schema:
            properties:
              links:
                items:
                  $ref: "#/definitions/link"
                type: array
              record:
                $ref: "#/definitions/record"
      tags:
        - dataset
        - ods
  "/{source}/datasets/{dataset_id}/reuses":
    get:
      description: |
        Get list of reuses
      operationId: getDatasetReuses
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/timezone"
      responses:
        "200":
          description: |
            A paginated list of reuses
          schema:
            properties:
              links:
                items:
                  $ref: "#/definitions/link"
                type: array
              reuses:
                items:
                  $ref: "#/definitions/reuse"
                type: array
      tags:
        - dataset
        - ods
  "/{source}/datasets/{dataset_id}/reuses/{reuse_id}":
    get:
      description: |
        Retrieve a single reuse based on its ID.
      operationId: getDatasetReuse
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/reuse_id"
        - $ref: "#/parameters/timezone"
      responses:
        "200":
          description: |
            A paginated list of reuses
          schema:
            properties:
              links:
                items:
                  $ref: "#/definitions/link"
                type: array
              reuse:
                $ref: "#/definitions/reuse"
      tags:
        - dataset
        - ods
  "/{source}/datasets/{dataset_id}/snapshots":
    get:
      description: |
        List of all snapshots for this dataset.
      operationId: getDatasetSnapshots
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/timezone"
      responses:
        "200":
          description: List of all snapshots, each with their endpoint.
          schema:
            properties:
              links:
                items:
                  $ref: "#/definitions/link"
                type: array
              snapshots:
                items:
                  $ref: "#/definitions/snapshot"
                type: array
      tags:
        - dataset
        - ods
  "/{source}/datasets/{dataset_id}/snapshots/{snapshot_id}":
    get:
      description: |
        List of all snapshots for this dataset.
      operationId: downloadDatasetSnapshot
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/snapshot_id"
        - $ref: "#/parameters/timezone"
      responses:
        "200":
          description: The full dataset in the state it was in when the snapshot was created, in CSV
      tags:
        - dataset
        - ods
  "/{source}/exports/csv":
    get:
      description: |
        Export catalog (source) in CSV format
      operationId: exportDatasetsCSV
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/where"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/search"
        - $ref: "#/parameters/facet"
        - $ref: "#/parameters/refine"
        - $ref: "#/parameters/exclude"
        - $ref: "#/parameters/timezone"
        - $ref: "#/parameters/include_app_metas"
        - default: ;
          description: Provide a different delimiter (default ',').
          enum:
            - ","
            - ;
            - "|"
          in: query
          name: delimiter
          required: false
          type: string
      produces:
        - text/csv
      responses:
        "200":
          description: Return a CSV file
          schema:
            type: file
      tags:
        - export catalog
        - ods
  "/{source}/exports/json":
    get:
      description: |
        Export catalog (source) in JSON format
      operationId: exportDatasetsJson
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/where"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/search"
        - $ref: "#/parameters/facet"
        - $ref: "#/parameters/refine"
        - $ref: "#/parameters/exclude"
        - $ref: "#/parameters/pretty"
        - $ref: "#/parameters/timezone"
        - $ref: "#/parameters/include_app_metas"
      produces:
        - application/json
      responses:
        "200":
          description: Return a JSON file
          schema:
            type: file
      tags:
        - export catalog
        - ods
  "/{source}/exports/rdf":
    get:
      description: |
        Export catalog (source) in RDF/XML format
      operationId: exportDatasetsRDF
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/where"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/search"
        - $ref: "#/parameters/facet"
        - $ref: "#/parameters/refine"
        - $ref: "#/parameters/exclude"
        - $ref: "#/parameters/timezone"
        - $ref: "#/parameters/include_app_metas"
      produces:
        - application/rdf+xml
      responses:
        "200":
          description: Return a RDF XML file
          schema:
            type: file
      tags:
        - export catalog
        - ods
  "/{source}/exports/rss":
    get:
      description: |
        Export catalog (source) in RSS format
      operationId: exportDatasetsRSS
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/where"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/search"
        - $ref: "#/parameters/facet"
        - $ref: "#/parameters/refine"
        - $ref: "#/parameters/exclude"
        - $ref: "#/parameters/timezone"
        - $ref: "#/parameters/include_app_metas"
      produces:
        - text/xml
      responses:
        "200":
          description: Return a JSON file
          schema:
            type: file
      tags:
        - export catalog
        - ods
  "/{source}/exports/ttl":
    get:
      description: |
        Export catalog (source) in TTL (turtle/rdf) format
      operationId: exportDatasetsTTL
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/where"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/search"
        - $ref: "#/parameters/facet"
        - $ref: "#/parameters/refine"
        - $ref: "#/parameters/exclude"
        - $ref: "#/parameters/timezone"
        - $ref: "#/parameters/include_app_metas"
      produces:
        - text/turtle
      responses:
        "200":
          description: Return a TTL file
          schema:
            type: file
      tags:
        - export catalog
        - ods
  "/{source}/exports/xls":
    get:
      description: |
        Export catalog (source) in XLS (Excel) format
      operationId: exportDatasetsXLS
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/where"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/search"
        - $ref: "#/parameters/facet"
        - $ref: "#/parameters/refine"
        - $ref: "#/parameters/exclude"
        - $ref: "#/parameters/timezone"
        - $ref: "#/parameters/include_app_metas"
      produces:
        - xls
      responses:
        "200":
          description: Return an XLS file
          schema:
            type: file
      tags:
        - export catalog
        - ods
  "/{source}/facets":
    get:
      description: |
        Enumerate facets values for datasets and return a list of values for each facet.
        Can be used to implement guided navigation in large result sets.

        Read [the facets documentation](https://help.opendatasoft.com/apis/ods-search-v2/#enumerating-facets-values) for more details.
      operationId: getDatasetsFacets
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/facet"
        - $ref: "#/parameters/refine"
        - $ref: "#/parameters/exclude"
        - $ref: "#/parameters/where"
        - $ref: "#/parameters/search"
        - $ref: "#/parameters/timezone"
      responses:
        "200":
          description: Facets enumeration
          schema:
            properties:
              facets:
                items:
                  $ref: "#/definitions/facet_enumeration"
                type: array
            type: object
      tags:
        - catalog
        - facet
        - ods
  "/{source}/metadata_templates":
    get:
      description: |
        List of available metadata templates types, each with their endpoints.
      operationId: getMetadataTemplatesTypes
      parameters:
        - $ref: "#/parameters/source"
      responses:
        "200":
          description: List of available metadata templates types
          schema:
            properties:
              links:
                items:
                  $ref: "#/definitions/link"
                type: array
      tags:
        - metadata
        - ods
  "/{source}/metadata_templates/{metadata_template_type}":
    get:
      description: |
        List of metadata templates available for this type.
      operationId: getMetadataTemplatesType
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/metadata_template_type"
      responses:
        "200":
          description: List of metadata templates
          schema:
            properties:
              links:
                items:
                  $ref: "#/definitions/link"
                type: array
              metadata_templates:
                items:
                  properties:
                    links:
                      items:
                        $ref: "#/definitions/link"
                      type: array
                    metadata_template:
                      $ref: "#/definitions/metadata_template"
                  type: object
                type: array
      tags:
        - metadata
        - ods
  "/{source}/metadata_templates/{metadata_template_type}/{metadata_template_name}":
    get:
      description: |
        A single metadata_template
      operationId: getMetadataTemplate
      parameters:
        - $ref: "#/parameters/source"
        - $ref: "#/parameters/metadata_template_type"
        - $ref: "#/parameters/metadata_template_name"
      responses:
        "200":
          description: A metadata template selected by ID.
          schema:
            properties:
              links:
                items:
                  $ref: "#/definitions/link"
                type: array
              metadata_template:
                $ref: "#/definitions/metadata_template"
      tags:
        - metadata
        - ods
definitions:
  aggregation:
    description: Result of an aggregation request.
    example:
      count(*): 86
    type: object
  attachment:
    properties:
      href:
        type: string
      metas:
        type: object
    type: object
  dataset:
    properties:
      attachments:
        items:
          type: object
        type: array
      data_visible:
        type: boolean
      dataset_id:
        type: string
      features:
        description: |
          A map of available features for a dataset, with the fields they apply to.
        items:
          type: string
        type: array
      fields:
        items:
          properties:
            annotations:
              type: object
            description:
              type: string
            label:
              type: string
            name:
              type: string
            type:
              type: string
          type: object
        type: array
      has_records:
        type: boolean
      metas:
        type: object
    type: object
  datasets:
    items:
      $ref: "#/definitions/dataset"
    type: array
  facet_enumeration:
    properties:
      facets:
        items:
          $ref: "#/definitions/facet_value_enumeration"
        type: array
      name:
        type: string
    type: object
  facet_value_enumeration:
    properties:
      count:
        type: integer
      facets:
        items:
          $ref: "#/definitions/facet_value_enumeration"
        type: array
      name:
        type: string
      value:
        type: string
    type: object
  link:
    properties:
      href:
        type: string
      rel:
        type: string
    type: object
  links:
    items:
      $ref: "#/definitions/link"
    type: array
  metadata_template:
    properties:
      name:
        type: string
      schema:
        items:
          type: object
        type: array
      type:
        type: string
    type: object
  page:
    properties:
      description:
        type: string
      slug:
        type: string
      title:
        description: |
          A localized string (that is an object where the keys are language codes and the values translations of a same
          string).
        properties:
          en:
            type: string
          fr:
            type: string
        type: object
    type: object
  query_string:
    description: |
      Query string using the query language.
      Example: (field1="value1" or field1="value2") and field2=value2 and "full text search"

      Supports geo queries with the following functions:
      * distance(myfield, center, radius): restrict entries to those where {myfield} is less than {radius} from {center} (center being defined 'lat,lon')
      * bbox(myfield, topleft, bottomright): restrict entries to those where {myfield} is within the bounds defined by the two sets of coordinates {topleft} and {bottomright}
      * polygon(myfield, mypolygon): restrict entries to those where {myfield} is within the bounds of {mypolygon}; {mypolygon} being a list of 'lat,lon' vertices
      * wkt(myfield, mywkt): restrict entries to those where {myfield} is within the body of {mywkt}; {mywkt} being a Well Known Text (see 'http://en.wikipedia.org/wiki/Well-known_text' for reference)
    type: string
  record:
    properties:
      fields:
        type: object
      id:
        type: string
      size:
        type: integer
      timestamp:
        format: dateTime
        type: string
    type: object
  records:
    items:
      $ref: "#/definitions/record"
    type: array
  reuse:
    properties:
      created_at:
        description: Date when the reuse was submitted.
        format: dateTime
        type: string
      description:
        description: Slightly longer description of what was achieved using the dataset.
      id:
        description: reuse id
        type: string
      thumbnail:
        description: URL illustrating the work.
        type: string
      title:
        description: Short description of the user's work.
        type: string
      url:
        description: URL where the work can be accessed publicly.
        type: string
      user:
        properties:
          first_name:
            type: string
          last_name:
            type: string
          username:
            type: string
        type: object
    type: object
  snapshot:
    properties:
      created_at:
        format: dateTime
        type: string
      description:
        type: string
      href:
        type: string
      snapshot_id:
        type: string
    type: object
  timezone:
    description: |
      A timezone

      If used as a parameter, defines the timezone the calculations will be performed in. If left empty, 'UTC' is
      assumed.
    example: Europe/Paris
    type: string
