post:
  operationId: getDashboardEnvironmentalRanking
  summary: Get dashboard environmental ranking
  description: |
    Release 1: **US-80**. Requires a POST_LOGIN JWT.

    Ranks accessible stations by either avoided CO2 or saved coal. The two
    request examples correspond to the two Web Dashboard API calls in the
    Release 1 Postman collection.
  tags: [webDashboard]
  security:
    - bearerAuth: []
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: "../../components.yaml#/components/schemas/DashboardRankingRequest"
        examples:
          co2Avoided:
            summary: Environmental ranking - CO2
            value:
              timezone: "Asia/Ho_Chi_Minh"
              metric: "co2_avoided"
              date_from: "2026-05-01T06:00:00.000Z"
              date_to: "2026-06-01T05:59:59.000Z"
          coalSaved:
            summary: Environmental ranking - coal
            value:
              timezone: "Asia/Ho_Chi_Minh"
              metric: "coal_saved"
              date_from: "2026-05-01T06:00:00.000Z"
              date_to: "2026-06-01T05:59:59.000Z"
  responses:
    "200":
      description: Environmental ranking returned directly.
      content:
        application/json:
          schema:
            $ref: "../../components.yaml#/components/schemas/DashboardRankingResponse"
    "400":
      $ref: "../../components.yaml#/components/responses/Failure"