Electricity North West Dataset API

openapi: 3.2.0
info:
  title: Explore Dataset API
  version: v2.0
  description: The Opendatasoft Explore API v2 is organized around REST.
  contact:
    email: support@opendatasoft.com
  license:
    name: Copyright Opendatasoft
    url: https://legal.huwise.com/en/terms-of-use.html
servers:
- url: https://electricitynorthwest.opendatasoft.com/api/explore/v2.0
security:
- apikey: []
tags:
- name: Dataset
  description: API to work on records
paths:
  /catalog/datasets/{dataset_id}/records:
    get:
      summary: Query dataset records
      operationId: getRecords
      tags:
      - Dataset
      description: Perform a query on dataset records.
      parameters:
      - $ref: '#/components/parameters/dataset_id'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/where'
      - $ref: '#/components/parameters/group_by'
      - $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: Records
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/records'
              examples:
                records:
                  $ref: '#/components/examples/records-v2.0'
                group_by_country:
                  $ref: '#/components/examples/group_by_country-v2.0'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          description: Unauthorized
        '429':
          $ref: '#/components/responses/quota'
        '500':
          description: Internal Server Error
  /catalog/datasets/{dataset_id}/exports:
    get:
      summary: List export formats
      operationId: listDatasetExportFormats
      tags:
      - Dataset
      description: List available export formats
      parameters:
      - $ref: '#/components/parameters/dataset_id'
      responses:
        '200':
          description: A list of available export formats
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  links:
                    type: array
                    items:
                      $ref: '#/components/schemas/links'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          description: Unauthorized
        '429':
          $ref: '#/components/responses/quota'
        '500':
          description: Internal Server Error
  /catalog/datasets/{dataset_id}/exports/{format}:
    get:
      summary: Export a dataset
      operationId: exportRecords
      tags:
      - Dataset
      description: 'Export a dataset in the desired format.

        **Note:** The `group_by` parameter is only available on exports starting with the v2.1'
      parameters:
      - $ref: '#/components/parameters/dataset_id'
      - $ref: '#/components/parameters/format-datasets'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/where'
      - $ref: '#/components/parameters/order_by'
      - $ref: '#/components/parameters/limit_export'
      - $ref: '#/components/parameters/refine'
      - $ref: '#/components/parameters/exclude'
      - $ref: '#/components/parameters/lang'
      - $ref: '#/components/parameters/timezone'
      - $ref: '#/components/parameters/use_labels'
      - $ref: '#/components/parameters/compressed'
      - $ref: '#/components/parameters/epsg'
      responses:
        '200':
          description: Return a file
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          description: Unauthorized
        '429':
          $ref: '#/components/responses/quota'
        '500':
          description: Internal Server Error
  /catalog/datasets/{dataset_id}/exports/csv:
    get:
      summary: Export a dataset in CSV
      operationId: exportRecordsCSV
      tags:
      - Dataset
      description: Export a dataset in CSV (Comma Separated Values). Specific parameters are described here
      parameters:
      - $ref: '#/components/parameters/dataset_id'
      - 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
  /catalog/datasets/{dataset_id}/exports/parquet:
    get:
      summary: Export a dataset in Parquet
      operationId: exportRecordsParquet
      tags:
      - Dataset
      description: Export a dataset in Parquet. Specific parameters are described here
      parameters:
      - $ref: '#/components/parameters/dataset_id'
      - name: parquet_compression
        in: query
        required: false
        schema:
          type: string
          enum:
          - snappy
          - zstd
          default: snappy
        description: Sets the compression parameter for the Parquet export file
      responses:
        '200':
          description: Return a file
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          description: Unauthorized
        '429':
          $ref: '#/components/responses/quota'
        '500':
          description: Internal Server Error
  /catalog/datasets/{dataset_id}/exports/gpx:
    get:
      summary: Export a dataset in GPX
      operationId: exportRecordsGPX
      tags:
      - Dataset
      description: Export a dataset in GPX. Specific parameters are described here
      parameters:
      - $ref: '#/components/parameters/dataset_id'
      - name: name_field
        in: query
        required: false
        schema:
          type: string
        description: Sets the field that is used as the 'name' attribute in the GPX output
      - name: description_field_list
        in: query
        required: false
        schema:
          type: string
        description: Sets the fields to use in the 'description' attribute of the GPX output
      - name: use_extension
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: 'Set it to true to use the `<extension>` tag for attributes (as GDAL does). Set it to false to use the `<desc>` tag for attributes.

          **Warning:** the default value of this parameter is `false` in v2.0 and `true` starting with v2.1'
      responses:
        '200':
          description: Return a file
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          description: Unauthorized
        '429':
          $ref: '#/components/responses/quota'
        '500':
          description: Internal Server Error
  /catalog/datasets/{dataset_id}/facets:
    get:
      summary: List dataset facets
      operationId: getRecordsFacets
      tags:
      - Dataset
      description: 'Enumerates facet values for records and returns a list of values for each facet.

        Can be used to implement guided navigation in large result sets.'
      parameters:
      - $ref: '#/components/parameters/dataset_id'
      - $ref: '#/components/parameters/where'
      - $ref: '#/components/parameters/refine'
      - $ref: '#/components/parameters/exclude'
      - $ref: '#/components/parameters/facet'
      - $ref: '#/components/parameters/lang'
      - $ref: '#/components/parameters/timezone'
      responses:
        '200':
          description: Facets enumeration
          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:
                facets:
                  $ref: '#/components/examples/facets'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          description: Unauthorized
        '429':
          $ref: '#/components/responses/quota'
        '500':
          description: Internal Server Error
  /catalog/datasets/{dataset_id}/attachments:
    get:
      summary: List dataset attachments
      operationId: getDatasetAttachments
      tags:
      - Dataset
      description: Returns a list of all available attachments for a dataset.
      parameters:
      - $ref: '#/components/parameters/dataset_id'
      responses:
        '200':
          description: List of all available attachments
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  links:
                    type: array
                    items:
                      $ref: '#/components/schemas/links'
                  attachments:
                    type: array
                    items:
                      $ref: '#/components/schemas/attachment'
              examples:
                attachments:
                  $ref: '#/components/examples/attachments'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          description: Unauthorized
        '429':
          $ref: '#/components/responses/quota'
        '500':
          description: Internal Server Error
  /catalog/datasets/{dataset_id}/records/{record_id}:
    get:
      summary: Read a dataset record
      operationId: getRecord
      tags:
      - Dataset
      description: Reads a single dataset record based on its identifier.
      parameters:
      - $ref: '#/components/parameters/dataset_id'
      - $ref: '#/components/parameters/record_id'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/lang'
      - $ref: '#/components/parameters/timezone'
      responses:
        '200':
          description: A single record
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/record'
              examples:
                record:
                  $ref: '#/components/examples/record-v2.0'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          description: Unauthorized
        '429':
          $ref: '#/components/responses/quota'
        '500':
          description: Internal Server Error
components:
  parameters:
    limit_export:
      name: limit
      in: query
      description: 'Number of items to return in export.


        Use -1 (default) to retrieve all records

        '
      schema:
        minimum: -1
        type: integer
        default: -1
    offset:
      name: offset
      in: query
      description: 'Index of the first item to return (starting at 0).


        To use with the `limit` parameter to implement pagination.


        **Note:** the maximum value depends on the type of query, see the note on `limit` for the details

        '
      schema:
        minimum: 0
        type: integer
        default: 0
    epsg:
      name: epsg
      in: query
      description: 'This parameter sets the EPSG code to project shapes into for formats that support geometric features.

        '
      schema:
        type: integer
        default: 4326
    order_by:
      name: order_by
      in: query
      description: 'Example: `order_by=sum(age) desc, name asc`


        A comma-separated list of field names or aggregations to sort on, followed by an order (`asc` or `desc`).


        Results are sorted in ascending order by default. To sort results in descending order, use the `desc` keyword.'
      style: form
      explode: false
      schema:
        type: string
    group_by:
      name: group_by
      in: query
      description: "Example: `group_by=city_field as city`\n\nA group by expression defines a grouping function for an aggregation.\nIt can be:\n - a field name: group result by each value of this field\n - a range function: group result by range\n - a date function: group result by date\n\nIt is possible to specify a custom name with the 'as name' notation."
      style: form
      explode: false
      schema:
        type: string
    exclude:
      name: exclude
      in: query
      description: 'Examples:

        - `exclude=city:Paris` - Exclude the value `Paris` from the `city` facet. Facets enumeration will display `Paris` as `excluded` without any count information.

        - `exclude=modified:2019/12` - Exclude the value `2019/12` from the `modified` facet. Facets enumeration will display `2020` as `excluded` without any count information.


        A facet filter used to exclude a facet value from the result set.

        Using this parameter, you can filter your query to exclude the selected facet value in the response.


        `exclude` uses the following syntax: `exclude=<FACETNAME>:<FACETVALUE>`


        **`exclude` must not be confused with a `where` filter. Excluding a facet value is equivalent to removing an entry in the left navigation panel.**'
      style: form
      explode: true
      schema:
        type: string
    format-datasets:
      name: format
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/enum-format-datasets'
      style: simple
    select:
      name: select
      in: query
      description: "Examples:\n- `select=size` - Example of select, which only return the \"size\" field.\n- `select=size * 2 as bigger_size` - Example of a complex expression with a label, which returns a new field named \"bigger_size\" and containing the double of size field value.\n- `select=dataset_id, fields` - Example of a select in catalog ODSQL query to only retrieve dataset_id and schema of datasets.\n\nA select expression can be used to add, remove or change the fields to return.\nAn expression can be:\n  - a wildcard ('*'): all fields are returned.\n  - A field name: only the specified field is returned.\n  - An include/exclude function: All fields matching the include or exclude expression are included or excluded. This expression can contain wildcard.\n  - A complex expression. The result of the expression is returned. A label can be set for this expression, and in that case, the field will be named after this label."
      schema:
        type: string
    refine:
      name: refine
      in: query
      description: 'Example: `refine=modified:2020` - Return only the value `2020` from the `modified` facet.


        A facet filter used to limit the result set.

        Using this parameter, you can refine your query to display only the selected facet value in the response.


        Refinement uses the following syntax: `refine=<FACETNAME>:<FACETVALUE>`


        For date, and other hierarchical facets, when refining on one value, all second-level values related to that entry will appear in facets enumeration. For example, after refining on the year 2019, the related second-level month will appear. And when refining on August 2019, the third-level day will appear.


        **`refine` must not be confused with a `where` filter. Refining with a facet is equivalent to selecting an entry in the left navigation panel.**'
      style: form
      explode: true
      schema:
        type: string
    record_id:
      name: record_id
      in: path
      required: true
      schema:
        type: string
      description: Record identifier
    limit:
      name: limit
      in: query
      description: "Number of items to return.\n\nTo use with the `offset` parameter to implement pagination.\n\nThe maximum possible value depends on whether the query contains a `group_by` clause or not.\n\nFor a query **without** a `group_by`:\n  - the maximum value for `limit` is 100,\n  - `offset+limit` should be less than 10000\n\nFor a query **with** a `group_by`:\n  - the maximum value for `limit` is 20000,\n  - `offset+limit` should be less than 20000\n\n**Note:** If you need more results, please use the /exports endpoint.\n"
      schema:
        maximum: 100
        minimum: -1
        type: integer
        default: 10
    timezone:
      name: timezone
      in: query
      description: 'Set the timezone for datetime fields.


        Timezone IDs are defined by the [Unicode CLDR project](https://github.com/unicode-org/cldr). The list of timezone IDs is available in [timezone.xml](https://github.com/unicode-org/cldr/blob/master/common/bcp47/timezone.xml).'
      schema:
        type: string
        default: UTC
      examples:
        UTC:
          summary: UTC timezone
          value: UTC
        Europe/Paris:
          summary: Paris timezone
          value: Europe/Paris
        US/Eastern:
          summary: Eastern timezone
          value: US/Eastern
        Europe/London:
          summary: London timezone
          value: Europe/London
        Europe/Berlin:
          summary: Berlin timezone
          value: Europe/Berlin
    use_labels:
      name: use_labels
      in: query
      description: 'If set to `true`, this parameter will make exports output the label of each field rather than its name.


        This parameter only makes sense for formats that contain a list of the fields in their output.

        '
      schema:
        type: boolean
        default: false
    where:
      name: where
      in: query
      description: 'A `where` filter is a text expression performing a simple full-text search that can also include logical operations

        (NOT, AND, OR...) and lots of other functions to perform complex and precise search operations.


        For more information, see [Opendatasoft Query Language (ODSQL)](<https://help.huwise.com/apis/ods-explore-v2/#section/Opendatasoft-Query-Language-(ODSQL)/Where-clause>) reference documentation.'
      schema:
        type: string
    dataset_id:
      name: dataset_id
      in: path
      description: 'The identifier of the dataset to be queried.


        You can find it in the "Information" tab of the dataset page or in the dataset URL, right after `/datasets/`.'
      required: true
      schema:
        type: string
    compressed:
      name: compressed
      in: query
      description: 'If set to `true`, this parameter can compress the output file of a specific export format with GZIP, e.g. `.csv.gzip`.

        '
      required: false
      schema:
        type: boolean
        default: false
    lang:
      name: lang
      in: query
      description: 'A language value.


        If specified, the `lang` value override the default language, which is "fr".

        The language is used to format string, for example in the `date_format` function.'
      schema:
        type: string
        enum:
        - en
        - fr
        - nl
        - pt
        - it
        - ar
        - de
        - es
        - ca
        - eu
        - sv
      style: form
    facet:
      name: facet
      in: query
      description: "A facet is a field used for simple filtering (through the `refine` and `exclude` parameters) or exploration (with the `/facets` endpoint).\n\nIt can also be a function such as `facet=facet(name=\"field_name\")` which is identical to `facet=field_name`. But this `facet()` function\ncan also take some optional arguments such as `disjunctive`, `hierarchical`, `separator`, `sort` and `limit`.\n\n* `disjunctive`: a boolean `true/false`, whether multiple values can be selected for the facet\n* `hierarchical`: a boolean `true/false` if the field is hierarchical. The separator must be given as the argument.\n   For instance, you can do `facet=facet(name=\"filepath\", hierarchical=true, separator=\"/\")` to retrieve facets related to this field which might look like `\"/home/user/file.txt\"`\n* `separator`: a string, e.g. `/`, `-`, `;`\n* `sort`: a string which describes how to sort the facets. Possible arguments are `count` and `-count` for all field types, `alphanum` and `-alphanum` for `date`, `datetime` and `text`, `num` and `-num` for `decimal` and `int`\n* `limit`: an integer to limit the number of results\n"
      style: form
      explode: true
      schema:
        type: string
  examples:
    facets:
      value:
        links: []
        facets:
        - facets:
          - count: 68888
            state: displayed
            name: Europe
            value: Europe
          - count: 36276
            state: displayed
            name: America
            value: America
          name: timezone
        - facets:
          - count: 313
            state: displayed
            name: Afghanistan
            value: Afghanistan
          - count: 356
            state: displayed
            name: Albania
            value: Albania
          name: cou_name_en
    group_by_country-v2.0:
      value:
        links: []
        records:
        - count: 16729
          cou_name_en: United States
        - count: 9945
          cou_name_en: Italy
        - count: 8981
          cou_name_en: Mexico
    record-v2.0:
      value:
        links: []
        record:
          id: 5ce430b62d47a400a495c30345fb6fdfac5550f0
          timestamp: '2021-06-23T14:46:05.881Z'
          size: 190
          fields:
            timezone: Europe/Brussels
            elevation: null
            name: Fraire
            modification_date: '2020-04-05'
            dem: 238
            cou_name_en: Belgium
            feature_class: P
            admin3_code: '93'
            alternate_names:
            - Fraire
            coordinates:
              lat: 50.26127
              lon: 4.5076
            country_code_2: null
            geoname_id: '2798031'
            feature_code: PPL
            label_en: Belgium
            admin4_code: '93088'
            country_code: BE
            ascii_name: Fraire
            admin1_code: WAL
            admin2_code: WNA
            population: 1492
    records-v2.0:
      value:
        total_count: 137611
        links: []
        records:
        - links: []
          record:
            id: 53d4524dcb82c676bacd467cd5ace953f2e0389c
            timestamp: '2021-06-22T08:02:59.954Z'
            size: 194
            fields:
              admin1_code: '27'
              elevation: null
              name: Saint-Leu
              modification_date: '2019-03-26'
              alternate_names:
              - Saint-Leu
              feature_class: P
              admin3_code: '711'
              cou_name_en: France
              coordinates:
                lat: 46.7306
                lon: 4.50083
              country_code_2: null
              geoname_id: '2978771'
              feature_code: PPL
              label_en: France
              dem: 366
              country_code: FR
              ascii_name: Saint-Leu
              timezone: Europe/Paris
              admin2_code: '71'
              admin4_code: '71436'
              population: 29278
        - links: []
          record:
            id: d5251445f329dc74cc5c5e30c95378eb9807a019
            timestamp: '2021-06-22T08:02:59.954Z'
            size: 310
            fields:
              admin1_code: '32'
              elevation: null
              name: Saint-Léger-lès-Domart
              modification_date: '2016-02-18'
              alternate_names:
              - Saint-Leger
              - Saint-Leger-les-Domart
              - Saint-Léger
              - Saint-Léger-lès-Domart
              feature_class: P
              admin3_code: '802'
              cou_name_en: France
              coordinates:
                lat: 50.05208
                lon: 2.14067
              country_code_2: null
              geoname_id: '2978817'
              feature_code: PPL
              label_en: France
              dem: 31
              country_code: FR
              ascii_name: Saint-Leger-les-Domart
              timezone: Europe/Paris
              admin2_code: '80'
              admin4_code: '80706'
              population: 1781
    attachments:
      value:
        links: []
        attachments:
        - href: https://documentation-resources.opendatasoft.com/api/v2/catalog/datasets/geonames-all-cities-with-a-population-1000/attachments/cities1000_zip
          metas:
            mime-type: application/zip
            title: cities1000.zip
  schemas:
    enum-format-datasets:
      type: string
      enum:
      - csv
      - fgb
      - geojson
      - gpx
      - json
      - jsonl
      - jsonld
      - kml
      - n3
      - ov2
      - parquet
      - rdfxml
      - shp
      - turtle
      - xls
    records:
      type: object
      properties:
        total_count:
          type: integer
        links:
          type: array
          items:
            $ref: '#/components/schemas/links'
        records:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/aggregation'
            - $ref: '#/components/schemas/record'
    facet_value_enumeration:
      type: object
      properties:
        name:
          type: string
        count:
          type: integer
        value:
          type: string
        state:
          type: string
    attachment:
      type: object
      properties:
        href:
          type: string
        metas:
          type: object
          properties:
            mime-type:
              type: string
            title:
              type: string
            url:
              type: string
            id:
              type: string
    links:
      type: object
      properties:
        href:
          type: string
          format: uri
        rel:
          type: string
          enum:
          - self
          - first
          - last
          - next
          - dataset
          - catalog
    aggregation:
      type: object
      properties:
        count:
          type: integer
        cou_name_en:
          type: string
    record:
      type: object
      properties:
        record:
          type: object
          properties:
            id:
              type: string
            timestamp:
              type: string
              format: dateTime
            size:
              type: integer
              format: int64
            fields:
              type: object
              additionalProperties:
                type: any
        links:
          type: array
          items:
            $ref: '#/components/schemas/links'
    facet_enumeration:
      type: object
      properties:
        name:
          type: string
        facets:
          type: array
          items:
            $ref: '#/components/schemas/facet_value_enumeration'
  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.
  securitySchemes:
    apikey:
      type: apiKey
      description: API key to make authenticated requests.
      name: apikey
      in: query