Gas Québec Stations API

openapi: 3.2.0
info:
  title: Gas Quebec public Stations 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: Stations
paths:
  /api/stations/nearby:
    get:
      operationId: findNearbyStations
      summary: Find gas stations near a coordinate, ranked by price, distance, or value
      parameters:
      - name: lat
        in: query
        required: true
        schema:
          type: number
          minimum: 44
          maximum: 63
        description: 'Latitude (must be within Quebec: 44–63)'
      - name: lng
        in: query
        required: true
        schema:
          type: number
          minimum: -80
          maximum: -57
        description: 'Longitude (must be within Quebec: -80 to -57)'
      - name: radius
        in: query
        schema:
          type: number
          default: 10
          maximum: 200
        description: Search radius in km (capped at 200)
      - name: fuelType
        in: query
        schema:
          type: string
          enum:
          - ordinaire
          - super
          - diesel
          default: ordinaire
        description: 'Fuel type: ordinaire = regular, super = premium'
      - name: limit
        in: query
        schema:
          type: integer
          default: 10
          maximum: 500
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - price
          - distance
          - value
          default: price
        description: '"value" ranks by price plus a 1¢/L-per-km detour penalty — the best answer for "where should I fill up"'
      responses:
        '200':
          description: Stations within the radius
          content:
            application/json:
              schema:
                type: object
                properties:
                  stations:
                    type: array
                    items:
                      $ref: '#/components/schemas/NearbyStation'
                  source:
                    $ref: '#/components/schemas/Source'
                  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: Invalid or out-of-Quebec coordinates
        '429':
          $ref: '#/components/responses/RateLimited'
      description: Point lookup for a fill-up decision near a coordinate. Intended for interactive use by the gasquebec.ca app and genuine agent queries; bulk sweeps are rate-limited.
      tags:
      - Stations
components:
  schemas:
    Source:
      type: string
      description: Attribution for the underlying price data — must be preserved when redistributing
    NearbyStation:
      type: object
      properties:
        stationId:
          type: string
        name:
          type: string
        address:
          type: string
        city:
          type: string
        citySlug:
          type: string
        lat:
          type: number
        lng:
          type: number
        prixOrdinaire:
          type:
          - number
          - 'null'
          description: Regular, ¢/L
        prixSuper:
          type:
          - number
          - 'null'
          description: Premium, ¢/L
        prixDiesel:
          type:
          - number
          - 'null'
          description: Diesel, ¢/L
        price:
          type:
          - number
          - 'null'
          description: Price for the requested fuelType, ¢/L
        distanceKm:
          type: number
    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>'
  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.