Glowjakt Products API

openapi: 3.2.0
info:
  title: Glowjakt Public Products API
  version: 1.0.0
  summary: Nordic beauty price comparison — read-only public API
  description: Glowjakt compares beauty product prices across 40+ stores in Sweden, Norway, Denmark, Finland and Germany (the German market is branded Glowscout). Products are matched by EAN barcode, so comparisons are exact. Prices refresh daily from store feeds. Each market has its own API host (see servers) with its own catalog and currency. Glowjakt never charges stores for listing and sells no sponsored placements. This specification covers the curated read-only surface intended for AI agents and integrations. Please respect rate limits; contact us for high-volume use. An MCP server is also available at https://mcp.glowjakt.se/mcp — see https://mcp.glowjakt.se/docs.
  contact:
    name: Glowjakt (Sejder AB)
    email: kontakt@glowjakt.se
    url: https://glowjakt.se/se/om-oss/
servers:
- url: https://api.glowjakt.se
  description: Sweden (SEK) — glowjakt.se
- url: https://api.glowjakt.no
  description: Norway (NOK) — glowjakt.no
- url: https://api.glowjagt.dk
  description: Denmark (DKK) — glowjagt.dk
- url: https://api.glowjakt.fi
  description: Finland (EUR) — glowjakt.fi
- url: https://api.glowscout.de
  description: Germany (EUR) — glowscout.de (Glowscout)
security: []
tags:
- name: Products
paths:
  /api/products:
    get:
      operationId: searchProducts
      summary: Search or list products (EAN-grouped, lowest price first)
      description: Each product appears once, at the lowest price among stores that currently have it in stock (or the lowest listed price if it is sold out everywhere). listing_count is the number of stores carrying the product (including sold out); offer_count is the number with it in stock right now. For a barcode query (see q), offer_count counts the store listings with that barcode, including sold-out ones, and listing_count is not set.
      parameters:
      - name: q
        in: query
        description: 'Free-text search (product, brand, type). A query of only digits (spaces and hyphens allowed) with 8-14 digits is first looked up as a barcode: EAN-8, EAN-13, UPC-A or GTIN-14, leading zeros optional, no check-digit validation. A match returns that product regardless of other filters and pagination. Without a match, a query of exactly 8 or 13 digits returns no products and any other digit query is treated as free text. For a barcode match, offer_count counts the store listings with that barcode, including sold-out ones, and listing_count is not set.'
        schema:
          type: string
      - name: category
        in: query
        schema:
          $ref: '#/components/schemas/Category'
      - name: max_price
        in: query
        description: Max price in the market's local currency.
        schema:
          type: number
      - name: key_ingredient
        in: query
        description: Only products containing any of these key-ingredient groups (slugs from /api/ingredients, comma-separated = OR). E.g. "retinol" or "retinol,niacinamide".
        schema:
          type: string
      - name: exclude_ingredient
        in: query
        description: Exclude products containing any of these key-ingredient groups (comma-separated). E.g. "fragrance" or "sls,silicones" for targeted free-from filtering.
        schema:
          type: string
      - name: exclude_controversial
        in: query
        description: If true, exclude products containing any commonly-avoided ingredient (fragrance, parabens, silicones, SLS, mineral oil, formaldehyde, phenoxyethanol, propylene glycol, alcohol denat). Shortcut for exclude_ingredient with all 9 Controversial slugs.
        schema:
          type: boolean
      - name: size
        in: query
        description: Results per page (default 20).
        schema:
          type: integer
          maximum: 100
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: attribute
        in: query
        required: false
        schema:
          type: string
        description: 'Brand-level ethics/values filter (merges third-party certifications and the brand''s own claims per bucket). Slugs: vegansk, djurtestfri, ekologisk, skonsam, hallbar. Comma-separated = AND. See /api/attributes for localized names and counts.'
      responses:
        '200':
          description: Paged product list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductPage'
      tags:
      - Products
  /api/products/deals:
    get:
      operationId: listDeals
      summary: Products currently on sale, biggest genuine discounts first
      description: Discounts are computed against real previous prices; stores known for inflated recommended prices are excluded from discount claims.
      parameters:
      - name: category
        in: query
        schema:
          $ref: '#/components/schemas/Category'
      - name: size
        in: query
        schema:
          type: integer
          maximum: 100
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      responses:
        '200':
          description: Paged deal list (same shape as product search)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductPage'
      tags:
      - Products
  /api/products/{slug}:
    get:
      operationId: getProduct
      summary: Single product with description and category
      parameters:
      - $ref: '#/components/parameters/Slug'
      responses:
        '200':
          description: Product detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductDetail'
        '404':
          description: Unknown product slug
      tags:
      - Products
  /api/products/{slug}/offers:
    get:
      operationId: getProductOffers
      summary: Store offers for one product (the price comparison)
      description: 'Offers are aggregated across the product''s EAN group: the stores selling the same barcode. Listings the catalog classifies as outside its beauty scope are left out whenever the group also has in-scope listings. Sorted by price, in-stock first at equal price. is_cheapest marks the lowest-priced in-stock offer (the lowest-priced offer when none is in stock), the same price the product endpoint shows.'
      parameters:
      - $ref: '#/components/parameters/Slug'
      responses:
        '200':
          description: Offer list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferList'
        '404':
          description: Unknown product slug
      tags:
      - Products
  /api/products/{slug}/price-history:
    get:
      operationId: getPriceHistory
      summary: Daily lowest-price history for a product
      description: 'Default: daily lowest price across the product''s store offers for the last 30 days (daily values follow the same scope rule as /offers). Pass `days` (7-90) for a different daily window, or `range` for long-horizon weekly resolution (weekly lowest price per week; the response then includes `resolution: "weekly"`). The final data point is the product''s current price: the lowest in-stock offer when one exists.'
      parameters:
      - $ref: '#/components/parameters/Slug'
      - name: days
        in: query
        schema:
          type: integer
          default: 30
          minimum: 7
          maximum: 365
        description: Daily-resolution window in days. Raw daily data is retained for 90 days; values above 90 return what exists. Ignored when `range` is set.
      - name: range
        in: query
        schema:
          type: string
          enum:
          - 6m
          - 1y
          - max
        description: 'Long-horizon mode: weekly lowest price for the last 6 months, 1 year, or the full recorded history. Overrides `days`.'
      responses:
        '200':
          description: Price history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceHistory'
        '404':
          description: Unknown product slug
      tags:
      - Products
components:
  schemas:
    PriceHistory:
      type: object
      properties:
        current_price:
          type: number
        lowest_price:
          type: number
        highest_price:
          type: number
        resolution:
          type: string
          enum:
          - weekly
          description: 'Present only when `range` was used: each history point is the lowest price of that ISO week (dated by its Monday).'
        history:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date
              price:
                type: number
    OfferList:
      type: object
      properties:
        ean:
          type:
          - string
          - 'null'
        product_name:
          type: string
        brand:
          type: string
        image_url:
          type:
          - string
          - 'null'
        offer_count:
          type: integer
          description: Total number of store offers listed below, including those out of stock.
        offers:
          type: array
          items:
            type: object
            properties:
              store_name:
                type: string
              price:
                type: number
              original_price:
                type:
                - number
                - 'null'
              in_stock:
                type: boolean
              affiliate_url:
                type: string
                description: Tracked buy link to this store (https://{market-domain}/go/{id}?t=...). Signed and valid for 48 hours from the response; it redirects (302) to the store.
              is_cheapest:
                type: boolean
              content_value:
                type:
                - number
                - 'null'
                description: Package quantity in base unit (ml or g). German market (country=de) only — basis for the Grundpreis unit price (PAngV).
              content_unit:
                type:
                - string
                - 'null'
                description: 'Base unit for content_value: "ml" or "g". German market only.'
    Category:
      type: string
      enum:
      - skincare
      - makeup
      - haircare
      - fragrance
      - nails
      - body
      - accessories
    ProductPage:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        size:
          type: integer
        products:
          type: array
          items:
            $ref: '#/components/schemas/ProductSummary'
    ProductDetail:
      allOf:
      - $ref: '#/components/schemas/ProductSummary'
      - type: object
        properties:
          category:
            $ref: '#/components/schemas/Category'
          subcategory_path:
            type:
            - string
            - 'null'
          description:
            type:
            - string
            - 'null'
          inci:
            type:
            - string
            - 'null'
            description: Full INCI ingredient list (comma-separated). Null for devices/accessories.
          key_ingredients:
            type: array
            description: Notable ingredients with localized name, INCI term and function.
            items:
              type: object
              properties:
                slug:
                  type: string
                name:
                  type: string
                  description: Localized display name.
                note:
                  type: string
                  description: INCI term(s) matched.
                category:
                  type: string
                  description: Function, e.g. Hydration, Exfoliation.
                tier:
                  type: integer
          gallery:
            type: array
            items:
              type: string
            description: Product image URLs.
          certifications:
            type: array
            description: Third-party verified brand certifications from the Glowpedia fact base (Ecocert, Leaping Bunny, The Vegan Society...). Localized note explains each cert.
            items:
              type: object
              properties:
                name:
                  type: string
                note:
                  type: string
          claims:
            type:
            - array
            - 'null'
            description: The brand's OWN unverified marketing claims (localized strings). Always attribute to the brand — never present as verified facts.
            items:
              type: string
          glowpedia_url:
            type:
            - string
            - 'null'
            description: Market-localized URL to the brand article on Glowpedia (the beauty-brand encyclopedia). Null until the market edition is launched.
          guide_slug:
            type:
            - string
            - 'null'
            description: Slug of the price guide for the product's brand when one exists in this market (GET /api/guides/{slug}); null otherwise.
    ProductSummary:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        brand:
          type: string
        brand_slug:
          type: string
        slug:
          type: string
          description: 'Use with /api/products/{slug}/offers. Product page: https://<site>/<country>/product/<slug>/'
        price:
          type: number
          description: Lowest price among stores that currently have the product in stock (or the lowest listed price if it is sold out everywhere), in local currency (EUR prices have decimals).
        currency:
          type: string
        original_price:
          type:
          - number
          - 'null'
        image_url:
          type:
          - string
          - 'null'
        in_stock:
          type: boolean
        store_name:
          type: string
          description: Store offering that price.
        affiliate_url:
          type: string
          description: Tracked buy link to the store offering that price (https://{market-domain}/go/{id}?t=...). Signed and valid for 48 hours from the response; it redirects (302) to the store. Do not store or replay expired links — fetch fresh ones.
        offer_count:
          type: integer
          description: Number of stores with this product in stock right now. For a barcode match (see q on /api/products), the number of store listings with that barcode, including sold-out ones.
        listing_count:
          type: integer
          description: Number of stores carrying this product, including those currently sold out. Equals the number of entries returned by the offers endpoint. Not set for a barcode match (see q on /api/products).
        subcategory_path:
          type:
          - string
          - 'null'
          description: Product type as category/subcategory path, e.g. "makeup/lipstick".
        content_value:
          type:
          - number
          - 'null'
          description: Package quantity in base unit (ml or g), parsed from the product name. Served by the German market (country=de) only; used for the legal unit price (Grundpreis per 1 l / 1 kg, PAngV). Null when the quantity is unknown or the product is sold by piece.
        content_unit:
          type:
          - string
          - 'null'
          description: 'Base unit for content_value: "ml" or "g". German market only.'
  parameters:
    Slug:
      name: slug
      in: path
      required: true
      description: URL slug as returned by search/list endpoints.
      schema:
        type: string