Coffee Addict Beans.json API

openapi: 3.2.0
info:
  title: Coffeeaddict Nz Beans.json API
  version: '2026-11-04'
  contact:
    url: https://coffeeaddict.nz/api/
  description: 'Operations tagged Beans.json across 2 of this provider''s published API definitions: coffeeaddict-nz-openapi.json, coffeeaddict-nz-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://coffeeaddict.nz
tags:
- name: Beans.json
paths:
  /api/beans.json:
    get:
      operationId: listBeans
      summary: Every bag we track, cheapest per 100g first
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated_at:
                    type: string
                    format: date-time
                  next_update_after:
                    type: string
                    format: date-time
                    description: Nothing here changes before this time.
                  source:
                    type: string
                  documentation:
                    type: string
                  citation:
                    type: string
                  terms:
                    type: string
                  currency:
                    type: string
                  count:
                    type: integer
                  roaster_count:
                    type: integer
                  order:
                    type: string
                  beans:
                    type: array
                    items:
                      $ref: '#/components/schemas/Bean'
      tags:
      - Beans.json
    servers:
    - url: https://coffeeaddict.nz
components:
  schemas:
    Bean:
      type: object
      title: Bean
      description: One bag of coffee.
      additionalProperties: false
      required:
      - id
      - roaster
      - roaster_slug
      - roaster_url
      - name
      - url
      - shop_url
      - page
      - price_nzd
      - weight_g
      - price_per_100g
      - in_stock
      - origin
      - roast_style
      - roast_level
      - flavour_notes
      - flavours
      - shipping
      - first_seen
      - last_seen
      - last_price_change
      - previous_price_nzd
      properties:
        id:
          type: string
          description: Stable id, `<roaster-slug>:<product>-<weight>`. Survives price changes.
        roaster:
          type: string
          description: The roaster's name, as they write it.
        roaster_slug:
          type: string
          description: Their key here, and the last part of their page URL.
        roaster_url:
          type: string
          description: Short link to their shop's home page, on our domain.
        name:
          type: string
          description: The coffee's name, as the roaster writes it.
        url:
          type: string
          description: 'Where to send a reader: a short link on our domain that redirects to the roaster''s product page and counts the click.'
        shop_url:
          type: string
          description: The roaster's own product page, unredirected — so you can see exactly where `url` lands.
        page:
          type: string
          description: Our page for this roaster, where this bag is listed.
        price_nzd:
          type:
          - number
          - 'null'
          description: Shelf price in NZD. Null when we could not read one.
        weight_g:
          type:
          - integer
          - 'null'
          description: Bag weight in grams. Null when the roaster does not state it.
        price_per_100g:
          type:
          - number
          - 'null'
          description: Shelf price per 100g. Null when price or weight is null.
        in_stock:
          type: boolean
          description: Whether the roaster showed it as available at the last check.
        origin:
          type:
          - string
          - 'null'
          description: Country or region, where the roaster names one.
        roast_style:
          type:
          - string
          - 'null'
          description: '`espresso`, `filter` or `omni`, from the roaster''s own words.'
        roast_level:
          type:
          - string
          - 'null'
          description: Light/medium/dark, only where the roaster states it.
        flavour_notes:
          type: array
          items:
            type: string
          description: The roaster's own tasting notes, verbatim.
        flavours:
          type: array
          items:
            type: string
          description: Those notes mapped onto our 18-key flavour vocabulary.
        shipping:
          type: object
          title: Shipping
          description: What a roaster charges to deliver, as they publish it.
          additionalProperties: false
          required:
          - published
          - free_over_nzd
          - free_over_g
          - flat_nzd
          - flat_min_g
          - flat_varies
          - ships_free
          - delivered_price_nzd
          - delivered_price_exact
          - source
          - note
          - last_verified
          properties:
            published:
              type: boolean
              description: Whether the roaster publishes a rate outside checkout. Several do not.
            free_over_nzd:
              type:
              - number
              - 'null'
              description: Order total they ship free at, where they publish one.
            free_over_g:
              type:
              - number
              - 'null'
              description: Order WEIGHT they ship free at, for the roasters whose threshold is a weight rather than a basket total. Either threshold alone is enough.
            flat_nzd:
              type:
              - number
              - 'null'
              description: Their flat rate below that, where they publish one.
            flat_min_g:
              type:
              - number
              - 'null'
              description: Minimum order weight for `flat_nzd` to apply, where they set one. Below it their rate is unpublished — do not apply the flat rate to a lighter order.
            flat_varies:
              type: boolean
              description: True where the rate depends on the island; `flat_nzd` is then the cheaper.
            ships_free:
              type: boolean
              description: Whether this single bag already clears a free-shipping threshold of either kind — the basket total or the weight.
            delivered_price_nzd:
              type:
              - number
              - 'null'
              description: 'This bag at the door: price plus shipping. Null when the roaster publishes no rate this bag can use (unmet free-shipping threshold, under-threshold rate unpublished) — the door price is unknowable then, and null cannot be misquoted the way a ''floor'' price was.'
            delivered_price_exact:
              type: boolean
              description: False when `delivered_price_nzd` is a FLOOR — their rate varies by island and we quote its cheapest. Never treat a floor as a price.
            source:
              type:
              - string
              - 'null'
              description: The roaster page a human read the terms off.
            note:
              type:
              - string
              - 'null'
              description: Their terms in their own words, where they publish any.
            last_verified:
              type:
              - string
              - 'null'
              description: The day a human last read that page. Nothing re-checks it.
        first_seen:
          type: string
          description: ISO-8601 UTC. When WE first saw it, not when the roaster listed it.
        last_seen:
          type: string
          description: ISO-8601 UTC. The last check that found it.
        last_price_change:
          type:
          - string
          - 'null'
          description: ISO-8601 UTC of the last price MOVE. Null means it has never moved since we started watching — not that we have no history.
        previous_price_nzd:
          type:
          - number
          - 'null'
          description: What it cost before that move. Null if it has never moved.
x-refined-from:
- coffeeaddict-nz-openapi.json
- coffeeaddict-nz-openapi.yml