Coffee Addict Roasters.json API

openapi: 3.2.0
info:
  title: Coffeeaddict Nz Roasters.json API
  version: '2026-11-04'
  contact:
    url: https://coffeeaddict.nz/api/
  description: 'Operations tagged Roasters.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: Roasters.json
paths:
  /api/roasters.json:
    get:
      operationId: listRoasters
      summary: 'Every NZ roaster we have found: the ones we price-track, and the ones we only…'
      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
                  roasters:
                    type: array
                    items:
                      $ref: '#/components/schemas/Roaster'
                  listed_count:
                    type: integer
                  listed:
                    type: array
                    items:
                      $ref: '#/components/schemas/ListedRoaster'
      tags:
      - Roasters.json
    servers:
    - url: https://coffeeaddict.nz
components:
  schemas:
    ListedRoaster:
      type: object
      title: ListedRoaster
      description: A New Zealand roaster we know of and do not price-track.
      additionalProperties: false
      required:
      - name
      - url
      - website
      - town
      - region
      - tracked
      - reason
      - sells_online
      - platform
      properties:
        name:
          type: string
          description: Their name, as our sources write it.
        url:
          type:
          - string
          - 'null'
          description: Short link to their own site, on our domain (redirects, counts). Null where we have found no website for them.
        website:
          type:
          - string
          - 'null'
          description: Their own URL, unredirected. Null where we have none.
        town:
          type:
          - string
          - 'null'
          description: The town or suburb we have them in.
        region:
          type:
          - string
          - 'null'
          description: Their New Zealand region.
        tracked:
          type: boolean
          description: Always false here. See `reason` for why.
        reason:
          type: string
          description: 'Why we do not price-track them, in plain words: no website we could find, their site did not answer our check, their robots.txt asks us not to read it, their shop is password-protected, or simply not yet.'
        sells_online:
          type:
          - boolean
          - 'null'
          description: Whether they appear to sell beans online at all. Null where we could not tell.
        platform:
          type:
          - string
          - 'null'
          description: What their shop is built on, where we could tell (`shopify`, `woocommerce`, `squarespace`, …). This is how we decide who is cheap to onboard next.
    Roaster:
      type: object
      title: Roaster
      description: One roaster.
      additionalProperties: false
      required:
      - slug
      - name
      - url
      - shop_url
      - page
      - bean_count
      - coffee_count
      - cheapest_per_100g
      - last_checked
      - ok
      - stale
      - city
      - place
      - lat
      - lng
      - location_source
      - shipping
      - tracked
      properties:
        slug:
          type: string
          description: Their key here.
        name:
          type: string
          description: Their name.
        url:
          type: string
          description: Short link to their shop, on our domain (redirects, counts).
        shop_url:
          type: string
          description: Their own URL, unredirected.
        page:
          type: string
          description: Our page for them.
        bean_count:
          type: integer
          description: Bags of theirs we are tracking. One per size, so a coffee sold in three sizes counts three.
        coffee_count:
          type: integer
          description: Distinct coffees behind those bags, sizes collapsed. Never more than `bean_count`.
        cheapest_per_100g:
          type:
          - number
          - 'null'
          description: Their cheapest bag per 100g.
        last_checked:
          type:
          - string
          - 'null'
          description: ISO-8601 UTC of our last successful read of their shop.
        ok:
          type: boolean
          description: Whether that last read succeeded.
        stale:
          type: boolean
          description: True when we have not managed to check them for 3 days.
        city:
          type:
          - string
          - 'null'
          description: Where they roast, where we have confirmed it.
        place:
          type:
          - string
          - 'null'
          description: Suburb and city, as one line.
        lat:
          type:
          - number
          - 'null'
          description: Latitude, for distance sorting. Null where we could not confirm one.
        lng:
          type:
          - number
          - 'null'
          description: Longitude.
        location_source:
          type:
          - string
          - 'null'
          description: The page a human read the address off.
        shipping:
          type: object
          title: Terms
          description: A roaster's published shipping terms.
          additionalProperties: false
          required:
          - published
          - free_over_nzd
          - free_over_g
          - flat_nzd
          - flat_min_g
          - flat_varies
          - source
          - note
          - last_verified
          properties:
            published:
              type: boolean
              description: Whether they publish a rate outside checkout. Several roasters 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.
            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.
        tracked:
          type: boolean
          description: 'Always true in `roasters`: we read this roaster''s shop every night. The `listed` array is the roasters we know of and do not price-track, and every row there is false.'
x-refined-from:
- coffeeaddict-nz-openapi.json
- coffeeaddict-nz-openapi.yml