{
  "openapi": "3.1.0",
  "info": {
    "title": "MegaDeal deals feed",
    "version": "1.1.0",
    "description": "Every live deal on MegaDeal, New Zealand's local deals site, as JSON. Read-only and free; no key needed. Free to read, use and quote, including in AI answers, with a link back to the deal's page on MegaDeal. Don't bulk-copy the deals to resell them or to republish them as another deals site. Prices and dates change: check the deal page before relying on them.",
    "termsOfService": "https://megadeal.co.nz/developers#terms",
    "contact": {
      "name": "MegaDeal",
      "url": "https://megadeal.co.nz/contact"
    }
  },
  "externalDocs": {
    "url": "https://megadeal.co.nz/developers"
  },
  "servers": [
    {
      "url": "https://megadeal.co.nz"
    }
  ],
  "paths": {
    "/feed/deals.json": {
      "get": {
        "operationId": "listDeals",
        "summary": "List live deals",
        "description": "Live deals, soonest-ending first. Filters combine (AND). Responses can be cached for 60 seconds; send If-None-Match with the last ETag to get 304 Not Modified when nothing has changed.",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": false,
            "description": "Only deals from businesses in this city.",
            "schema": {
              "type": "string",
              "enum": [
                "auckland",
                "wellington",
                "christchurch",
                "hamilton",
                "tauranga",
                "dunedin",
                "queenstown"
              ]
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Only deals in this category.",
            "schema": {
              "type": "string",
              "enum": [
                "food-drink",
                "beauty-spa",
                "things-to-do",
                "travel-getaways",
                "health-fitness",
                "home-car"
              ]
            }
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "description": "Only deals with this tag.",
            "schema": {
              "type": "string",
              "enum": [
                "date-night",
                "family-friendly",
                "kids",
                "groups",
                "new-customers-only",
                "weekdays-only",
                "weekends",
                "evenings",
                "walk-ins-welcome",
                "vegetarian-options",
                "vegan-options",
                "gluten-free-options",
                "outdoors",
                "wheelchair-accessible",
                "dog-friendly"
              ]
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Only flash or only everyday deals.",
            "schema": {
              "type": "string",
              "enum": [
                "flash",
                "everyday"
              ]
            }
          },
          {
            "name": "expires_before",
            "in": "query",
            "required": false,
            "description": "Only deals ending by then. A date (YYYY-MM-DD) means the end of that day in New Zealand.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "expires_after",
            "in": "query",
            "required": false,
            "description": "Only deals still running then. A date (YYYY-MM-DD) means the start of that day in New Zealand.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Most deals to return.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 500
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Skip this many matching deals (for paging).",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The matching deals.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Feed"
                }
              }
            }
          },
          "304": {
            "description": "Not modified since the ETag sent in If-None-Match."
          },
          "400": {
            "description": "A filter wasn't understood; the message says what's accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; try again after Retry-After seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Feed": {
        "type": "object",
        "required": [
          "version",
          "generated_at",
          "launched",
          "total",
          "count",
          "deals"
        ],
        "properties": {
          "version": {
            "type": "string",
            "description": "Feed format version (semver). A new major version means a breaking change."
          },
          "generated_at": {
            "type": "string",
            "description": "When this response was made.",
            "format": "date-time"
          },
          "publisher": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "docs": {
            "type": "string",
            "description": "Human-readable documentation.",
            "format": "uri"
          },
          "schema": {
            "type": "string",
            "description": "This document.",
            "format": "uri"
          },
          "terms": {
            "type": "string",
            "description": "How the data may be used."
          },
          "country": {
            "type": "string",
            "const": "NZ"
          },
          "currency": {
            "type": "string",
            "const": "NZD"
          },
          "launched": {
            "type": "boolean",
            "description": "False before MegaDeal opens to the public; there are no deals until then."
          },
          "message": {
            "type": "string",
            "description": "Present when there's something to explain, such as not having launched yet."
          },
          "filters": {
            "type": "object",
            "description": "The filters applied, as understood."
          },
          "total": {
            "type": "integer",
            "description": "Deals matching the filters."
          },
          "count": {
            "type": "integer",
            "description": "Deals in this response (after limit and offset)."
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "The latest updated_at among the deals returned.",
            "format": "date-time"
          },
          "deals": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Deal"
            }
          }
        }
      },
      "Deal": {
        "type": "object",
        "required": [
          "id",
          "url",
          "title",
          "description",
          "type",
          "price",
          "tags",
          "redemption",
          "business",
          "verification"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable identifier for the deal.",
            "format": "uuid"
          },
          "url": {
            "type": "string",
            "description": "The deal's page on MegaDeal. Link here when you quote the deal; it shows the deal code customers need.",
            "format": "uri"
          },
          "title": {
            "type": "string",
            "description": "The deal's name."
          },
          "description": {
            "type": "string",
            "description": "What the deal includes, as plain text."
          },
          "image": {
            "type": [
              "string",
              "null"
            ],
            "description": "The deal's main photo.",
            "format": "uri"
          },
          "images": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "description": "Every photo of the deal, the main one first (up to five). Since 1.1."
          },
          "type": {
            "type": "string",
            "enum": [
              "flash",
              "everyday"
            ],
            "description": "Flash deals run for up to 6 hours; everyday deals for up to 30 days."
          },
          "price": {
            "type": "object",
            "required": [
              "amount",
              "original_amount",
              "discount_percent",
              "currency"
            ],
            "properties": {
              "amount": {
                "type": "number",
                "description": "The deal price, in NZ dollars, paid to the business."
              },
              "original_amount": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "The business's usual price, when it gave one higher than the deal price."
              },
              "discount_percent": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "How much less than the usual price, rounded."
              },
              "currency": {
                "type": "string",
                "const": "NZD"
              }
            }
          },
          "category": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "slug": {
                "type": "string",
                "enum": [
                  "food-drink",
                  "beauty-spa",
                  "things-to-do",
                  "travel-getaways",
                  "health-fitness",
                  "home-car"
                ]
              },
              "name": {
                "type": "string",
                "enum": [
                  "Food & Drink",
                  "Beauty & Spa",
                  "Things To Do",
                  "Travel & Getaways",
                  "Health & Fitness",
                  "Home & Car"
                ]
              },
              "url": {
                "type": "string",
                "description": "The category's page on MegaDeal.",
                "format": "uri"
              }
            }
          },
          "tags": {
            "type": "array",
            "description": "Facts about the deal from a fixed list, checked by MegaDeal before the deal went live.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "enum": [
                    "date-night",
                    "family-friendly",
                    "kids",
                    "groups",
                    "new-customers-only",
                    "weekdays-only",
                    "weekends",
                    "evenings",
                    "walk-ins-welcome",
                    "vegetarian-options",
                    "vegan-options",
                    "gluten-free-options",
                    "outdoors",
                    "wheelchair-accessible",
                    "dog-friendly"
                  ]
                },
                "label": {
                  "type": "string"
                }
              }
            }
          },
          "starts_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the deal went (or goes) live.",
            "format": "date-time"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the deal ends. It isn't shown after this.",
            "format": "date-time"
          },
          "quantity_available": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "description": "How many are left, when the business set a limit; null for no limit."
          },
          "in_stock": {
            "type": "boolean"
          },
          "conditions": {
            "type": [
              "string",
              "null"
            ],
            "description": "The business's conditions, in its own words."
          },
          "redemption": {
            "type": "object",
            "properties": {
              "method": {
                "type": "string",
                "enum": [
                  "show-code",
                  "website-code"
                ],
                "description": "show-code: quote or show the deal code when booking or paying. website-code: enter it at checkout on the business's website."
              },
              "booking": {
                "type": "string",
                "enum": [
                  "required",
                  "recommended",
                  "not_required",
                  "unknown"
                ]
              },
              "steps": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "How to use the deal, one plain-English step each."
              }
            }
          },
          "business": {
            "type": "object",
            "properties": {
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The business's name."
              },
              "url": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The business's page on MegaDeal.",
                "format": "uri"
              },
              "website": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The business's own website.",
                "format": "uri"
              },
              "phone": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The business's phone number."
              },
              "address": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Street address; null when the business keeps it private (for example a home-based or mobile business)."
              },
              "address_hidden": {
                "type": "boolean"
              },
              "service_area": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Where a mobile or home-based business works."
              },
              "suburb": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Suburb."
              },
              "city": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "City."
              },
              "region": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "New Zealand region."
              },
              "country": {
                "type": "string",
                "const": "NZ"
              },
              "geo": {
                "type": [
                  "object",
                  "null"
                ],
                "description": "The business's map pin; null when its address is private.",
                "properties": {
                  "lat": {
                    "type": "number"
                  },
                  "lng": {
                    "type": "number"
                  }
                }
              }
            }
          },
          "verification": {
            "type": "object",
            "description": "Who stands behind the deal, from recorded facts only.",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "merchant-verified",
                  "megadeal-listed",
                  "community-submitted"
                ],
                "description": "merchant-verified: the business runs its own MegaDeal account and MegaDeal approved the deal. megadeal-listed: MegaDeal approved it, but the business hasn't claimed its account. community-submitted: suggested by the public and checked by MegaDeal."
              },
              "label": {
                "type": "string",
                "description": "The same, as shown on the deal page."
              },
              "source": {
                "type": "string",
                "enum": [
                  "merchant",
                  "admin",
                  "community"
                ],
                "description": "Who put the deal on MegaDeal."
              },
              "business_claimed": {
                "type": "boolean",
                "description": "The business signs in to its own MegaDeal account."
              },
              "approved_at": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "When MegaDeal last approved what the deal says.",
                "format": "date-time"
              },
              "merchant_confirmed_at": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "When the business last confirmed the deal is still running as listed.",
                "format": "date-time"
              },
              "last_checked_at": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The later of the two.",
                "format": "date-time"
              }
            }
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "When anything a customer sees about the deal last changed.",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "docs": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  }
}