openapi: 3.0.3
info:
  title: Swagger REST API cube - Indicateurs Territoriaux de Transition Ecologique
  description: >-
    We use the single `POST` route `/cubejs-api/v1/load` to fetch the indicators' data.
    
    
    The `GET` route `/cubejs-api/v1/meta` allows for easy access to the indicators' metadata.
    

    [REST API](https://cube.dev/docs/reference/rest-api) enables Cube to deliver data over the HTTP protocol to certain
    kinds of data applications, including but not limited to the following ones:


    - Most commonly, front-end applications

    - Some data notebooks, e.g., Observable

    - Low-code tools, e.g., Retool

    - Automated jobs


    Often, the [REST API](https://cube.dev/docs/reference/rest-api) is used to enable embedded analytics and real-time
    analytics use cases.


    See the [REST API reference](https://cube.dev/docs/reference/rest-api) for the list of supported API endpoints. Also,
    check the [query format](https://cube.dev/docs/product/apis-integrations/rest-api/query-format) for details about query syntax.
  #termsOfService: 
  contact:
    email: indicateurs-transition-ecologique@developpement-durable.gouv.fr
  #license:
  #  name: 
  #  url: 
  version: 1.0.0
externalDocs:
  description: Find out more about cube REST API
  url: https://cube.dev/docs/reference/rest-api
servers:
  - url: https://api.indicateurs.ecologie.gouv.fr
tags:
  - name: data
    description: Everything about the data
  - name: meta
    description: Everything about the metadata
  - name: state
    description: Everything about the deployment state
paths:
  /cubejs-api/v1/load:
    post:
      tags:
        - data
      summary: Get the data for a query.
      description: Get the data for a query with body content
      operationId: getQueryDataBody
      requestBody:
        description: Request the data with http method **POST** (recommended method).
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/query'
            example:
              query:
                measures:
                - prelevement_eau_usage.id_638
                filters: []
                timezone: UTC
                dimensions:
                - prelevement_eau_usage.libelle_region
                - prelevement_eau_usage.usage
                timeDimensions:
                - dimension: prelevement_eau_usage.date_mesure
                  granularity: year
                order:
                  prelevement_eau_usage.date_mesure: asc
                limit: 5
        required: true
      responses:
        '200':
          description: "**[Successful operation]**"
          content:
            application/json:
              schema:
                properties:
                  query:
                    $ref: '#/components/schemas/query'
                  data:
                    description: >-
                            Formatted dataset of query results.
                    type: array
                    items:
                      type: object
                  lastRefreshTime:
                    description: >-
                            Last update time
                    type: string
                  annotation:
                    $ref: '#/components/schemas/annotation'
                  dataSource:
                    description: >-
                      The source of the data
                    type: string
                    default: "default"
                  dbType:
                    description: >-
                      The type of database
                    type: string
                    default: "postgres"
                  extDbType:
                    description: >-
                      The type of exernal database (API-linked)
                    type: string
                    default: "cubestore"
                  external:
                    description: >-
                      `true`if the data is loaded from an external location rather from a folder on disk. Good examples of such locations are an S3 bucket, a database, or an external API. Can also happen when pre-aggregation results are stocked externally.
                    type: boolean
                    default: false
                  slowQuery:
                    description: >-
                      `slowQuery` is `true`if the query is slow and might be accelerated with pre-aggregations.
                    type: boolean
                  total:
                    description: >-
                      The total number of rows returned for the query. Useful for paginating results.
                    type: integer
              example:
                query:
                  measures:
                  - prelevement_eau_usage.id_638
                  filters: []
                  timezone: UTC
                  dimensions:
                  - prelevement_eau_usage.libelle_region
                  - prelevement_eau_usage.usage
                  timeDimensions:
                  - dimension: prelevement_eau_usage.date_mesure
                    granularity: year
                  order:
                  - id: prelevement_eau_usage.date_mesure
                    desc: false
                  limit: 10000
                  rowLimit: 10000
                data:
                - prelevement_eau_usage.libelle_region: Grand Est
                  prelevement_eau_usage.usage: eaux douces superficielles – refroidissement des centrales
                    électriques
                  prelevement_eau_usage.date_mesure.year: '2008-01-01T00:00:00.000'
                  prelevement_eau_usage.date_mesure: '2008-01-01T00:00:00.000'
                  prelevement_eau_usage.id_638: 3385642021.4
                - prelevement_eau_usage.libelle_region: Auvergne-Rhône-Alpes
                  prelevement_eau_usage.usage: eaux saumâtres – refroidissement des centrales électriques
                  prelevement_eau_usage.date_mesure.year: '2008-01-01T00:00:00.000'
                  prelevement_eau_usage.date_mesure: '2008-01-01T00:00:00.000'
                  prelevement_eau_usage.id_638: 0
                - prelevement_eau_usage.libelle_region: Occitanie
                  prelevement_eau_usage.usage: eaux douces souterraines – refroidissement des centrales
                    électriques
                  prelevement_eau_usage.date_mesure.year: '2008-01-01T00:00:00.000'
                  prelevement_eau_usage.date_mesure: '2008-01-01T00:00:00.000'
                  prelevement_eau_usage.id_638: 0
                - prelevement_eau_usage.libelle_region: Centre-Val de Loire
                  prelevement_eau_usage.usage: eaux douces superficielles – agriculture
                  prelevement_eau_usage.date_mesure.year: '2008-01-01T00:00:00.000'
                  prelevement_eau_usage.date_mesure: '2008-01-01T00:00:00.000'
                  prelevement_eau_usage.id_638: 20830581.5
                - prelevement_eau_usage.libelle_region: Provence-Alpes-Côte d'Azur
                  prelevement_eau_usage.usage: eaux douces superficielles – eau potable
                  prelevement_eau_usage.date_mesure.year: '2008-01-01T00:00:00.000'
                  prelevement_eau_usage.date_mesure: '2008-01-01T00:00:00.000'
                  prelevement_eau_usage.id_638: 324024100
                lastRefreshTime: '2025-02-10T10:49:56.320Z'
                annotation:
                  measures:
                    prelevement_eau_usage.id_638:
                      title: Prelevement Eau Usage Id638
                      shortTitle: Id638
                      type: number
                      meta: Cet indicateur représente le prelevement en eau par usage (en m3)
                      drillMembers: []
                      drillMembersGrouped:
                        measures: []
                        dimensions: []
                  dimensions:
                    prelevement_eau_usage.libelle_region:
                      title: Prelevement Eau Usage Libelle Region
                      shortTitle: Libelle Region
                      type: string
                    prelevement_eau_usage.usage:
                      title: Prelevement Eau Usage Usage
                      shortTitle: Usage
                      type: string
                  segments: {}
                  timeDimensions:
                    prelevement_eau_usage.date_mesure.year:
                      title: Prelevement Eau Usage Date Mesure
                      shortTitle: Date Mesure
                      type: time
                    prelevement_eau_usage.date_mesure:
                      title: Prelevement Eau Usage Date Mesure
                      shortTitle: Date Mesure
                      type: time
                dataSource: "default"
                dbType: "postgres"
                extDbType: "cubestore"
                external: false
                slowQuery: true
                total: 
        '400':
          description: "**[Error message]** General error. It may be a database error, timeout, or other issue. Check error message for details."
        '403':
          description: "**[Authorization header isn't set]** You didn't provide an auth token. Provide a valid API Token or disable authorization. **[Invalid token]**The auth token provided is not valid. It may be expired or have invalid signature."
        '404': 
          description: "**[Error: not found]**"
        '500':
          description: "**[Error message]** Cube internal server error. Check error message for details."
  /cubejs-api/v1/meta:
    get:
      tags:
        - meta
      summary: Get meta-information for cubes and views defined in the data model.
      description: "Get meta-information for cubes and views defined in the data model. Information about cubes and views with `public: false` will not be returned."
      operationId: getMeta
      responses:
        '200':
          description: "**[Successful operation]**"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cubes'
              example: 
                cubes:
                  - name: aires_protegees_dpt
                    type: cube
                    title: Aires Protegees Dpt
                    isVisible: true
                    public: true
                    description: Mesure des surfaces et proportions de territoires en aires protégée
                      en lien avec la SNAP (Stratégie National pour les Aires Protégées).
                    measures:
                    - name: aires_protegees_dpt.id_81
                      title: Aires Protegees Dpt Id81
                      shortTitle: Id81
                      cumulativeTotal: false
                      cumulative: false
                      type: number
                      aggType: sum
                      drillMembers: []
                      drillMembersGrouped:
                        measures: []
                        dimensions: []
                      meta: Cet indicateur représente la surface en aire protégée (objectif SNAP 30%)
                        en hectares
                      isVisible: true
                      public: true
                    - name: aires_protegees_dpt.id_832
                      title: Aires Protegees Dpt Id832
                      shortTitle: Id832
                      cumulativeTotal: false
                      cumulative: false
                      type: number
                      aggType: sum
                      drillMembers: []
                      drillMembersGrouped:
                        measures: []
                        dimensions: []
                      meta: Cet indicateur représente la surface sous protection forte (objectif SNAP
                        10%) en hectares
                      isVisible: true
                      public: true
                    - name: aires_protegees_dpt.id_675
                      title: Aires Protegees Dpt Id675
                      shortTitle: Id675
                      cumulativeTotal: false
                      cumulative: false
                      type: number
                      aggType: number
                      drillMembers: []
                      drillMembersGrouped:
                        measures: []
                        dimensions: []
                      meta: Cet indicateur représente la proportion du territoire en aire protégée (objectif
                        SNAP 30%)
                      isVisible: true
                      public: true
                    - name: aires_protegees_dpt.id_348
                      title: Aires Protegees Dpt Id348
                      shortTitle: Id348
                      cumulativeTotal: false
                      cumulative: false
                      type: number
                      aggType: number
                      drillMembers: []
                      drillMembersGrouped:
                        measures: []
                        dimensions: []
                      meta: Cet indicateur représente la proportion du territoire sous protection forte
                        (objectif SNAP 10%)
                      isVisible: true
                      public: true
                    - name: aires_protegees_dpt.id_960
                      title: Aires Protegees Dpt Id960
                      shortTitle: Id960
                      cumulativeTotal: false
                      cumulative: false
                      type: number
                      aggType: sum
                      drillMembers: []
                      drillMembersGrouped:
                        measures: []
                        dimensions: []
                      meta: Surface terrestre protégée
                      isVisible: true
                      public: true
                    - name: aires_protegees_dpt.id_961
                      title: Aires Protegees Dpt Id961
                      shortTitle: Id961
                      cumulativeTotal: false
                      cumulative: false
                      type: number
                      aggType: number
                      drillMembers: []
                      drillMembersGrouped:
                        measures: []
                        dimensions: []
                      meta: Proportion surface terrestre protégée
                      isVisible: true
                      public: true
                    - name: aires_protegees_dpt.id_966
                      title: Aires Protegees Dpt Id966
                      shortTitle: Id966
                      cumulativeTotal: false
                      cumulative: false
                      type: number
                      aggType: sum
                      drillMembers: []
                      drillMembersGrouped:
                        measures: []
                        dimensions: []
                      meta: Surface terrestre sous protection forte
                      isVisible: true
                      public: true
                    - name: aires_protegees_dpt.id_964
                      title: Aires Protegees Dpt Id964
                      shortTitle: Id964
                      cumulativeTotal: false
                      cumulative: false
                      type: number
                      aggType: number
                      drillMembers: []
                      drillMembersGrouped:
                        measures: []
                        dimensions: []
                      meta: Proportion surface terrestre sous protection forte
                      isVisible: true
                      public: true
                    dimensions:
                    - name: aires_protegees_dpt.geocode_departement
                      title: Aires Protegees Dpt Geocode Departement
                      type: string
                      shortTitle: Geocode Departement
                      suggestFilterValues: true
                      isVisible: true
                      public: true
                      primaryKey: false
                    - name: aires_protegees_dpt.libelle_departement
                      title: Aires Protegees Dpt Libelle Departement
                      type: string
                      shortTitle: Libelle Departement
                      suggestFilterValues: true
                      isVisible: true
                      public: true
                      primaryKey: false
                    - name: aires_protegees_dpt.geocode_region
                      title: Aires Protegees Dpt Geocode Region
                      type: string
                      shortTitle: Geocode Region
                      suggestFilterValues: true
                      isVisible: true
                      public: true
                      primaryKey: false
                    - name: aires_protegees_dpt.libelle_region
                      title: Aires Protegees Dpt Libelle Region
                      type: string
                      shortTitle: Libelle Region
                      suggestFilterValues: true
                      isVisible: true
                      public: true
                      primaryKey: false
                    - name: aires_protegees_dpt.date_mesure
                      title: Aires Protegees Dpt Date Mesure
                      type: time
                      shortTitle: Date Mesure
                      suggestFilterValues: true
                      isVisible: true
                      public: true
                      primaryKey: false
                    - name: aires_protegees_dpt.type_aire
                      title: Aires Protegees Dpt Type Aire
                      type: string
                      shortTitle: Type Aire
                      suggestFilterValues: true
                      isVisible: true
                      public: true
                      primaryKey: false
                    segments: []
                    hierarchies: []
        '400':
          description: "**[Error message]** General error. It may be a database error, timeout, or other issue. Check error message for details."
        '403':
          description: "**[Authorization header isn't set]** You didn't provide an auth token. Provide a valid API Token or disable authorization. **[Invalid token]**The auth token provided is not valid. It may be expired or have invalid signature."
        '404': 
          description: "**[Error: not found]**"
        '500':
          description: "**[Error message]** Cube internal server error. Check error message for details."
  /readyz:
    get:
      security: []
      tags:
        - state
      summary: Returns the ready state of the deployment.
      description: "Returns the ready state of the deployment.\n\n **Single-tenant:** Ensures the orchestration layer is operational and tests the connection to the default `dataSource`.\n\n **Multi-tenant:** Tests connections per-tenant. If no connections exist, it will report as successful."
      operationId: ReadyState
      responses:
        '200':
          description: "**[Successful operation]**"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/health'
        '400':
          description: "**[Error message]** General error. It may be a database error, timeout, or other issue. Check error message for details."
        '403':
          description: "**[Authorization header isn't set]** You didn't provide an auth token. Provide a valid API Token or disable authorization. **[Invalid token]**The auth token provided is not valid. It may be expired or have invalid signature."
        '404': 
          description: "**[Error: not found]**"
        '500':
          description: "**[Error message]** Cube internal server error. Check error message for details."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/down'
  /livez:
    get:
      security: []
      tags:
        - state
      summary: Returns the liveness state of the deployment. 
      description: "Returns the liveness state of the deployment.\n\n This is confirmed by testing any existing connections to `dataSource`. If no connections exist, it will report as successful."
      operationId: LiveState
      responses:
        '200':
          description: "**[Successful operation]**"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/health'
        '400':
          description: "**[Error message]** General error. It may be a database error, timeout, or other issue. Check error message for details."
        '403':
          description: "**[Authorization header isn't set]** You didn't provide an auth token. Provide a valid API Token or disable authorization. **[Invalid token]**The auth token provided is not valid. It may be expired or have invalid signature."
        '404': 
          description: "**[Error: not found]**"
        '500':
          description: "**[Error message]** Cube internal server error. Check error message for details."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/down'
components:
  schemas:
    query: #complete
      description: >-
        The query request ([full documentation](https://cube.dev/docs/product/apis-integrations/rest-api/query-format))
      type: object
      properties:
        measures:
          description: >-
            An array of the names of the indicators to query.
          type: array
          items:
            type: string
        filters:
          description: >-
            The filters to do a more specific query. Learn about [filters format](https://cube.dev/docs/product/apis-integrations/rest-api/query-format#filters-format).
          type: array
          items:
            type: object
        timezone:
          description: >-
            A [time zone](https://cube.dev/docs/product/apis-integrations/queries#time-zone) for your query. You can set the desired time zone in the [TZ Database Name](https://en.wikipedia.org/wiki/Tz_database) format.
          example: "Etc/UTC"
          type: string
        dimensions:
          description: >-
            The dimensions over which to group the data.
          type: array
          items:
            type: string
        timeDimensions:
          description: >-
             A convenient way to specify a time dimension with a filter. It is an array of objects in [timeDimension format](https://cube.dev/docs/product/apis-integrations/rest-api/query-format#time-dimensions-format).
          type: array
          items:
            type: object
            properties:
              dimension:
                description: >-
                  The time dimensions over which to group the data.
                type: string
              granularity:
                description: >-
                  The granulaty of the time dimension (time step).
                type: string
        segments:
          description: >-
            An array of segments. A segment is a named filter, created in the data model.
          type: array
          items:
            type: string
        limit:
          description: >-
              A [row limit](https://cube.dev/docs/product/apis-integrations/queries#row-limit) for your query.
          type: integer
          default: 10000
        total:
          description: >-
              If set to `true`, Cube will run a [total query](https://cube.dev/docs/product/apis-integrations/queries#total-query) and return the total number of rows as if no row limit or offset are set in the query.
          type: boolean
          default: false
        offset:
          description: >-
            The number of initial rows to be skipped for your query.
          type: integer
          default: 0
        order:
          description: >-
            An object, where the keys are measures or dimensions to order by and their corresponding values are either `asc` or `desc`. The order of the fields to order on is based on the order of the keys in the object. If not provided, [default ordering](https://cube.dev/docs/product/apis-integrations/queries#order) is applied. If an empty object ([]) is provided, no ordering is applied.
          type: object
        renewQuery:
          description: >-
            If `renewQuery` is set to `true`, Cube will renew all [refreshKey](https://cube.dev/docs/reference/data-model/pre-aggregations#refresh_key) for queries and query results in the foreground. However, if the [refreshKey](https://cube.dev/docs/reference/data-model/pre-aggregations#refresh_key) (or [refreshKey.every](https://cube.dev/docs/reference/data-model/pre-aggregations#every)) doesn't indicate that there's a need for an update this setting has no effect.
            
            **[Warning]** Cube provides only eventual consistency guarantee. Using a small [refreshKey.every](https://cube.dev/docs/reference/data-model/pre-aggregations#every) value together with `renewQuery` to achieve immediate consistency can lead to endless refresh loops and overall system instability.
          type: boolean
          default: false
        ungrouped:
          description: >-
             If set to `true`, Cube will run an [ungrouped query](https://cube.dev/docs/product/apis-integrations/queries#ungrouped-query).
          type: boolean
          default: false
    annotation: #complete
      description: >-
              Metadata for query. Contains descriptions for all query items.
      type: object
      properties:
        measures:
          description: >-
              Contains all measures' metadata of the query
          type: object
          properties:
            measure_name:
              description: >-
                Contains the measure's metadata
              type: object
              properties:
                title: 
                  description: >-
                    Human readable title from the data model
                  type: string
                shortTitle:
                  description: >-
                    Short title for visualization usage
                  type: string
                type:
                  description: >-
                    Data type
                  type: string
                meta:
                  description: >-
                    Metadata of the measure
                  type: string
                drillMembers:
                  description: >-
                    Using the `drillMembers` parameter, you can define a set of [drill down](https://cube.dev/docs/guides/recipes/data-exploration/drilldowns) fields for the measure. `drillMembers` is defined as an array of dimensions. Cube automatically injects dimensions’ names and other cubes’ names with dimensions in the context, so you can reference these variables in the `drillMembers` array. [Learn more about how to define and use drill downs](https://cube.dev/docs/guides/recipes/data-exploration/drilldowns).
                  type: array
                  items:
                    type: string
                drillMembersGrouped:
                  description: >-
                    Using the `drillMembersGrouped` parameter, you can define a set of [drill down](https://cube.dev/docs/guides/recipes/data-exploration/drilldowns) fields for the measure.
                  type: object
                  properties:
                    measures:
                      type: array
                      items:
                        type: string
                    dimensions:
                      type: array
                      items:
                        type: string
        dimensions:
          type: object
          description: >-
            Contains the [dimensions](https://cube.dev/docs/reference/data-model/dimensions) over which the data can be viewed.
          properties:
            dimension_name:
              description: >-
                Contains the dimension caracteristics.
              type: object
              properties:
                title: 
                  description: >-
                    Human readable title from the data model.
                  type: string
                shortTitle:
                  description: >-
                    Short title for visualization usage.
                  type: string
                type:
                  description: >-
                    Data type.
                  type: string
        segments:
          description: >-
            You can use the `segments` parameter within [cubes](https://cube.dev/docs/reference/data-model/cube) to define segments. Segments are predefined filters. You can use segments to define complex filtering logic in SQL.
          type: array
          items:
            description: "Segment name."
            type: string
        timeDimensions:
          type: object
          description: >-
            Contains the time dimensions over which the data can be viewed.
          properties:
            time_dimension_name:
              description: >-
                Contains the time dimension caracteristics.
              type: object
              properties:
                title: 
                  description: >-
                    Human readable title from the data model.
                  type: string
                shortTitle:
                  description: >-
                    Short title for visualization usage.
                  type: string
                type:
                  description: >-
                    Data type.
                  type: string
    cubes: #complete
      description: >-
              Array of cubes and views.
      type: array
      items:
        type: object
        properties:
          name: 
            description: >-
              Codename of the cube/view.
            type: string
          title: 
            description: >-
              Human-readable cube/view name.
            type: string
          type: 
            description: >-
              Type can be "cube" or "view".
            type: string
            enum:
              - cube
              - view
          meta: 
            description: >-
               Custom metadata.
            type: string 
          isVisible: 
            description: >-
              Is the cube/view visible?
            type: boolean
          public: 
            description: >-
              Is the cube/view public?
            type: boolean
          description: 
            description: >-
              A description of the cube.
            type: string
          connectedComponent: 
            description: >-
              An integer representing a join relationship. If the same value is returned for two cubes, then there is at least one join path between them.
            type: integer
          measures: 
            description: >-
               Array of measures in this cube/view.
            type: array
            items:
              type: object
              properties:
                name:
                  description: >-
                    Measure's name.
                  type: string
                title: 
                  description: >-
                    Human readable title from the data model
                  type: string
                shortTitle:
                  description: >-
                    Short title for visualization usage
                  type: string
                cumulativeTotal:
                  description: >-
                    depreciated
                  type: boolean
                cumulative:
                  description: >-
                    depreciated
                  type: boolean
                type:
                  description: >-
                        Data type
                  type: string
                aggType:
                  description: >-
                    The type of aggregation possible for the measure. `sum` if summable.
                  type: string
                drillMembers:
                  description: >-
                        Using the `drillMembers` parameter, you can define a set of [drill down](https://cube.dev/docs/guides/recipes/data-exploration/drilldowns) fields for the measure. `drillMembers` is defined as an array of dimensions. Cube automatically injects dimensions’ names and other cubes’ names with dimensions in the context, so you can reference these variables in the `drillMembers` array. [Learn more about how to define and use drill downs](https://cube.dev/docs/guides/recipes/data-exploration/drilldowns).
                  type: array
                  items:
                    type: string
                drillMembersGrouped:
                  description: >-
                    Using the `drillMembersGrouped` parameter, you can define a set of [drill down](https://cube.dev/docs/guides/recipes/data-exploration/drilldowns) fields for the measure.
                  type: object
                  properties:
                    measures:
                      type: array
                      items:
                        type: string
                    dimensions:
                      type: array
                      items:
                        type: string
                meta:
                  description: >-
                        Metadata of the measure
                  type: string
                isVisible: 
                  description: >-
                    Is the cube/view visible?
                  type: boolean
                public: 
                  description: >-
                    Is the cube/view public?
                  type: boolean
          dimensions: 
            description: >-
               Array of dimensions in this cube/view.
            type: array
            items:
              type: object
          segments: 
            description: >-
               Array of segments in this cube/view.
            type: array
            items:
              type: object
          hierarchies: 
            description: >-
               You can use the `hierarchies` parameter within [cubes](https://cube.dev/docs/reference/data-model/cube) to define hierarchies. You can think about a hierarchy as a means to group [dimensions](https://cube.dev/docs/reference/data-model/dimensions) together and organize them into levels of granularity, allowing users to drill down or roll up for analysis.
            type: array
            items:
              type: object
    health: #complete
      type: object
      properties:
        health:
          type: string
          example: "HEALTH"
    down: #complete
      type: object
      properties:
        health:
          type: string
          example: "DOWN"
  securitySchemes:
    bearerAuth: # name for the security scheme
      type: http
      scheme: bearer
      bearerFormat: JWT # optional, arbitrary value for documentation purposes
security:
  - bearerAuth: [] # use the same name as above
