Gas Québec Fair Price API

openapi: 3.2.0
info:
  title: Gas Quebec public Fair Price API
  version: 1.6.0
  summary: Live Quebec fuel prices (regular, premium, diesel) by station, city, and region.
  description: 'Public, unauthenticated read API behind gasquebec.ca. All prices are in Canadian cents per litre (¢/L). Data is sourced from Régie Essence Québec (Régie de l''énergie du Québec) and must be attributed as: "Fuel-price data from Régie Essence Québec (Régie de l''énergie du Québec), presented by Gas Quebec (gasquebec.ca)". Wherever API data is displayed publicly (a website, an app''s public screens, a widget on a public page), that credit must include a visible link to https://www.gasquebec.ca/ or to the page of the city the data covers. Every data response carries a ready-to-use `attribution` field ({ url, text, html }, French and English) and a `Link: ; rel="describedby"` header. Copy-paste snippet: `Prix : Régie de l''énergie du Québec, via Gas Québec` (EN: `Prices: Régie de l''énergie du Québec, via Gas Quebec`). Private use (Home Assistant, personal widgets, scripts) is exempt from the link. Every endpoint is rate-limited to 120 requests/minute per IP and returns 429 with a Retry-After header when exceeded.'
  termsOfService: https://www.gasquebec.ca/en/terms
  contact:
    url: https://www.gasquebec.ca/contact
  license:
    name: CC BY 4.0 (Gas Quebec original content only; underlying price facts remain subject to the Régie's terms)
    url: https://creativecommons.org/licenses/by/4.0/
servers:
- url: https://www.gasquebec.ca
tags:
- name: Fair Price
paths:
  /api/fair-price:
    get:
      operationId: getFairPrice
      summary: Fair-price assessment for a city (is the current price fair, high, or a deal?)
      parameters:
      - name: citySlug
        in: query
        required: true
        schema:
          type: string
        description: City slug from /api/cities
      - name: includeTrend
        in: query
        schema:
          type: boolean
          default: false
        description: Also return the market-trend verdict (rising/falling/stable and fill-up advice)
      responses:
        '200':
          description: Assessment (fields are null for unknown cities or during data gaps)
          content:
            application/json:
              schema:
                type: object
                properties:
                  assessment:
                    type:
                    - object
                    - 'null'
                    description: Comparison of the city's average price to the computed fair price
                  fairPrice:
                    type:
                    - object
                    - 'null'
                  trendVerdict:
                    type:
                    - object
                    - 'null'
                    description: Present when includeTrend=true
                  regieUrl:
                    type: string
                    format: uri
                  attribution:
                    $ref: '#/components/schemas/Attribution'
          headers:
            Link:
              description: 'Points at the attribution rule: <https://www.gasquebec.ca/api#attribution>; rel="describedby"'
              schema:
                type: string
        '400':
          description: Missing citySlug
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Fair Price
components:
  responses:
    RateLimited:
      description: Rate limit exceeded. Honour the Retry-After header. Public data endpoints allow 120 requests/minute and 20,000/day per address, counting only requests the edge cache does not answer; the daily 429 adds a `hint` and a `Retry-After` to midnight UTC.
  schemas:
    Attribution:
      type: object
      description: 'Ready-to-use link-back credit. Required wherever the data is displayed publicly (API terms: https://www.gasquebec.ca/en/terms); private use is exempt.'
      properties:
        url:
          type: string
          format: uri
          description: 'Page to link to: the city page for city data, otherwise https://www.gasquebec.ca/'
        text:
          type: object
          properties:
            fr:
              type: string
            en:
              type: string
        html:
          type: object
          description: '`text` with "Gas Québec" as a link to `url`, ready to paste'
          properties:
            fr:
              type: string
            en:
              type: string
      required:
      - url
      - text
      - html
      example:
        url: https://www.gasquebec.ca/villes/levis
        text:
          fr: 'Prix : Régie de l''énergie du Québec, via Gas Québec'
          en: 'Prices: Régie de l''énergie du Québec, via Gas Quebec'
        html:
          fr: 'Prix : Régie de l''énergie du Québec, via <a href="https://www.gasquebec.ca/villes/levis">Gas Québec</a>'
          en: 'Prices: Régie de l''énergie du Québec, via <a href="https://www.gasquebec.ca/villes/levis">Gas Quebec</a>'