Hydro-Québec Catalog API

openapi: 3.2.0
info:
  title: Hydro Quebec Catalog API
  contact:
    email: support@opendatasoft.com
  license:
    name: Copyright Opendatasoft
    url: https://legal.huwise.com/en/terms-of-use.html
  version: '1.0'
  description: 'Operations tagged Catalog across 2 of this provider''s published API definitions: hydro-quebec-open-data-explore-api-v2-0-openapi.json, hydro-quebec-open-data-explore-api-v2-1-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://donnees.hydroquebec.com/api/explore/v2.0
- url: https://donnees.hydroquebec.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'
      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.0'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          description: Unauthorized
        '429':
          $ref: '#/components/responses/quota'
        '500':
          description: Internal Server Error
    servers:
    - url: https://donnees.hydroquebec.com/api/explore/v2.0
  /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
    servers:
    - url: https://donnees.hydroquebec.com/api/explore/v2.0
  /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/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
    servers:
    - url: https://donnees.hydroquebec.com/api/explore/v2.0
  /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: false
        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
    servers:
    - url: https://donnees.hydroquebec.com/api/explore/v2.0
  /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
    servers:
    - url: https://donnees.hydroquebec.com/api/explore/v2.0
  /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
    servers:
    - url: https://donnees.hydroquebec.com/api/explore/v2.0
  /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'
      responses:
        '200':
          description: The dataset
          content:
            application/json; charset=utf-8json:
              schema:
                $ref: '#/components/schemas/dataset'
              examples:
                dataset:
                  $ref: '#/components/examples/dataset-v2.0'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          description: Unauthorized
        '429':
          $ref: '#/components/responses/quota'
        '500':
          description: Internal Server Error
    servers:
    - url: https://donnees.hydroquebec.com/api/explore/v2.0
components:
  schemas:
    enum-format-datasets:
      type: string
      enum:
      - csv
      - fgb
      - geojson
      - gpx
      - json
      - jsonl
      - jsonld
      - kml
      - n3
      - ov2
      - parquet
      - rdfxml
      - shp
      - turtle
      - xls
    dataset:
      type: object
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/links'
        dataset:
          type: object
          properties:
            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
                    - 'null'
    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'
    datasets:
      type: object
      properties:
        total_count:
          type: integer
        links:
          type: array
          items:
            $ref: '#/components/schemas/links'
        datasets:
          type: array
          items:
            $ref: '#/components/schemas/dataset'
    links:
      type: object
      properties:
        href:
          type: string
          format: uri
        rel:
          type: string
          enum:
          - self
          - first
          - last
          - next
          - dataset
          - catalog
    enum-format-datasets_2:
      type: string
      enum:
      - csv
      - fgb
      - geojson
      - gpx
      - json
      - jsonl
      - jsonld
      - kml
      - n3
      - ov2
      - parquet
      - rdfxml
      - shp
      - turtle
      - xlsx
    dataset_2:
      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
                - 'null'
    datasets_2:
      type: object
      properties:
        total_count:
          type: integer
        _links:
          type: array
          items:
            $ref: '#/components/schemas/links'
        results:
          type: array
          items:
            $ref: '#/components/schemas/dataset_2'
  responses:
    bad_request:
      description: Bad Request
      content:
        application/json; charset=utf-8:
          schema:
            type: object
            properties:
              message:
                type: string
                minLength: 1
              error_code:
                type: string
                minLength: 1
            required:
            - message
            - error_code
          examples:
            invalid_odsql:
              value:
                message: 'ODSQL query is malformed: invalid_function() Clause(s) containing the error(s): select.'
                error_code: ODSQLError
    quota:
      description: Too many requests
      content:
        application/json; charset=utf-8:
          schema:
            type: object
            properties:
              errorcode:
                type: number
              reset_time:
                type: string
                minLength: 1
              limit_time_unit:
                type: string
                minLength: 1
              call_limit:
                type: number
              error:
                type: string
                minLength: 1
            required:
            - errorcode
            - reset_time
            - limit_time_unit
            - call_limit
            - error
          examples:
            quota_exceeded:
              value:
                errorcode: 10002
                reset_time: '2021-01-26T00:00:00Z'
                limit_time_unit: day
                call_limit: 10000
                error: Too many requests on the domain. Please contact the domain administrator.
  examples:
    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.0:
      value:
        total_count: 19
        links: []
        datasets:
        - links: []
          dataset:
            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'
                territory:
                - World
                description: <p>This dataset displays level 0 world administrative boundaries. It contains countries as well as non-sovereign territories (like, for instance, French overseas). </p>
                modified_updates_on_metadata_change: false
                shared_catalog: null
                source_domain: null
                attributions: null
                geographic_area_mode: null
                geographic_reference_auto: true
                geographic_area: null
                publisher: World Food Programme (UN agency)
                language: en
                license: Open Government Licence v3.0
                source_dataset: null
                metadata_languages:
                - en
                oauth_scope: null
                federated: true
                license_url: http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/
            features:
            - analyze
            - geo
        - links: []
          dataset:
            dataset_id: geonames-all-cities-with-a-population-1000
            dataset_uid: da_5m8ykr
            attachments:
            - mimetype: application/zip
              url: odsfile://cities1000.zip
              id: cities1000_zip
              title: cities1000.zip
            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: []
            - description: null
              label: ASCII Name
              type: text
              name: ascii_name
              annotations: {}
            - description: null
              label: Alternate Names
              type: text
              name: alternate_names
              annotations:
                multivalued:
                - ','
            - description: see http://www.geonames.org/export/codes.html
              label: Feature Class
              type: text
              name: feature_class
              annotations: {}
            - description: see http://www.geonames.org/export/codes.html
              label: Feature Code
              type: text
              name: feature_code
              annotations: {}
            - description: null
              label: Country Code
              type: text
              name: country_code
              annotations: {}
            - description: null
              label: Country name EN
              type: text
              name: cou_name_en
              annotations:
                facet: []
                facetsort:
                - alphanum
                disjunctive: []
            - description: null
              label: Country Code 2
              type: text
              name: country_code_2
              annotations: {}
            - description: null
              label: Admin1 Code
              type: text
              name: admin1_code
              annotations: {}
            - description: null
              label: Admin2 Code
              type: text
              name: admin2_code
              annotations:
                facetsort:
                - -count
            - description: null
              label: Admin3 Code
              type: text
              name: admin3_code
              annotations: {}
            - description: null
              label: Admin4 Code
              type: text
              name: admin4_code
              annotations: {}
            - description: null
              label: Population
              type: int
              name: population
              annotations: {}
            - description: null
              label: Elevation
              type: text
              name: elevation
              annotations: {}
            - description: null
              label: DIgital Elevation Model
              type: int
              name: dem
              annotations: {}
            - description: null
              label: Timezone
              type: text
              name: timezone
              annotations:
                facet: []
                hierarchical:
                - /
            - description: null
              label: Modification date
              type: date
              name: modification_date
              annotations: {}
            - description: null
              label: LABEL EN
              type: text
              name: label_en
              annotations: {}
            - description: null
              label: Coordinates
              type: geo_point_2d
              name: coordinates
              annotations:
                facetsort:
                - -count
            metas:
              default:
                records_count: 137609
                modified: '2021-06-23T14:37:45+00:00'
                source_domain_address: null
                references: null
                keyword: null
                source_domain_title: null
                geographic_reference:
                - world
                timezone: null
                title: Geonames - All Cities with a population > 1000
                parent_domain: null
                theme: null
                modified_updates_on_data_change: false
                metadata_processed: '2021-06-23T14:49:23.198000+00:00'
                data_processed: '2021-06-23T14:49:23+00:00'
                territory:
                - World
                description: null
                modified_updates_on_metadata_change: false
                shared_catalog: null
                source_domain: null
                attributions: null
                geographic_area_mode: null
                geographic_reference_auto: true
                geographic_area: null
                publisher: null
                language: en
                license: null
                source_dataset: null
                metadata_languages:
                - en
                oauth_scope: null
                federated: false
                license_url: null
            features:
            - geo
            - analyze
            - timeserie
    dataset-v2.0:
      value:
        links: []
        dataset:
          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 &gt; 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: C

# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hydro-quebec/refs/heads/main/openapi/hydro-quebec-catalog-api-openapi.yml