{"openapi":"3.1.0","info":{"title":"Spill API","version":"1.0.0","description":"Free, read-only API of current Singapore promotions. No key needed. Please link to `url` or `promo_url` when you show a deal."},"servers":[{"url":"https://spill.sg/api/v1"}],"paths":{"/promotions":{"get":{"operationId":"searchPromotions","summary":"Search current promotions","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Words to match"},{"name":"category","in":"query","schema":{"type":"string","enum":["food","grocery","shopping","fashion","beauty","health","electronics","home","entertainment","travel","finance","insurance","telco","car","property","education"]},"description":"Category"},{"name":"brand","in":"query","schema":{"type":"string"},"description":"Brand name or slug"},{"name":"deal_type","in":"query","schema":{"type":"string","enum":["percent_off","one_for_one","fixed_price","free_gift","cashback","voucher","bundle","new_launch","other"]},"description":"Deal type"},{"name":"status","in":"query","schema":{"type":"string","enum":["live","ends_today","starting_soon","upcoming","undated"]},"description":"Status today"},{"name":"active_on","in":"query","schema":{"type":"string","format":"date"},"description":"Valid on this date (YYYY-MM-DD, SGT)"},{"name":"near","in":"query","schema":{"type":"string","example":"1.3521,103.8198"},"description":"lat,lng: sort by distance; deals without mapped outlets are left out"},{"name":"radius_km","in":"query","schema":{"type":"number"},"description":"With near: max distance"},{"name":"intent","in":"query","schema":{"type":"string","enum":["breakfast","lunch","dinner","coffee","drinks","shopping","fun","money"]},"description":"What they want: breakfast, lunch, dinner, coffee, drinks, shopping, fun, money"},{"name":"when","in":"query","schema":{"type":"string","enum":["now","today","tonight","tomorrow","weekend"]},"description":"Only deals usable then (Singapore time), reading each deal's hours"},{"name":"include_all_outlets","in":"query","schema":{"type":"boolean"},"description":"With near: also return island-wide deals valid at all outlets"},{"name":"eligibility","in":"query","schema":{"type":"string","enum":["student","senior","nsmen","member","cardholder","new_customer"]},"description":"Only deals limited to this group (e.g. student)"},{"name":"exclude_eligibility","in":"query","schema":{"type":"string","example":"student,member"},"description":"Comma-separated groups to leave out"},{"name":"sort","in":"query","schema":{"type":"string","enum":["newest","ending","nearest","top"]},"description":"newest (default) = latest announced first; top = best picks (fits the meal, ends soon, has a photo, nearby)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Page size"},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"Skip this many"}],"responses":{"200":{"description":"Matching promotions","content":{"application/json":{"schema":{"type":"object","properties":{"today":{"type":"string","format":"date"},"data_updated_at":{"type":"string","format":"date-time"},"total":{"type":"integer"},"offset":{"type":"integer"},"limit":{"type":"integer"},"promotions":{"type":"array","items":{"$ref":"#/components/schemas/Promotion"}}}}}}},"400":{"description":"Bad parameter"}}}},"/promotions/{id}":{"get":{"operationId":"getPromotion","summary":"One promotion","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"near","in":"query","schema":{"type":"string","example":"1.3042,103.8318"},"description":"lat,lng: sort outlets nearest first and add nearest_outlet"}],"responses":{"200":{"description":"The promotion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Promotion"}}}},"404":{"description":"Not found"}}}},"/recommendations":{"get":{"operationId":"recommendPromotions","summary":"Deals like the ones someone liked","parameters":[{"name":"liked","in":"query","schema":{"type":"string","example":"id1,id2"},"description":"Comma-separated promotion ids the person liked"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":12},"description":"How many"}],"responses":{"200":{"description":"Recommended promotions, each with a short reason"},"400":{"description":"Bad parameter"}}}},"/brands":{"get":{"operationId":"listBrands","summary":"Brands with current promotions","responses":{"200":{"description":"Brands"}}}}},"components":{"schemas":{"Promotion":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri","description":"Canonical page on this site"},"brand":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string","description":"Our own short summary"},"deal_type":{"type":"string","enum":["percent_off","one_for_one","fixed_price","free_gift","cashback","voucher","bundle","new_launch","other"]},"badge":{"type":"string","example":"1-for-1"},"price_sgd":{"type":["number","null"]},"original_price_sgd":{"type":["number","null"]},"start_date":{"type":["string","null"],"format":"date","description":"Singapore date; null if not stated"},"end_date":{"type":["string","null"],"format":"date"},"time_note":{"type":["string","null"]},"conditions":{"type":["string","null"]},"category":{"type":"string","enum":["food","grocery","shopping","fashion","beauty","health","electronics","home","entertainment","travel","finance","insurance","telco","car","property","education"]},"status":{"type":"string","enum":["live","ends_today","starting_soon","upcoming","undated"]},"all_outlets":{"type":"boolean"},"outlets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"address":{"type":"string"},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]}}}},"distance_km":{"type":"number","description":"Only when searching near a point"},"source_url":{"type":["string","null"],"format":"uri","description":"The brand page where the deal was announced (null when we found it on another deal site)"},"confidence":{"type":"string","enum":["high","low"],"description":"low = some details were inferred"},"sponsored":{"type":"boolean","description":"A paid placement running today (shown with a Sponsored label)"},"sponsored_until":{"type":"string","format":"date","description":"Last day of the paid placement, when set"},"verified_by_brand":{"type":"boolean","description":"The brand sent us this deal itself"},"updated_at":{"type":"string","format":"date-time"},"nearest_outlet":{"type":"object","description":"Only when a point was given: the closest outlet, with distance_km"},"links":{"type":"object","description":"Links to hand to a person","properties":{"page":{"type":"string","format":"uri"},"markdown":{"type":"string","format":"uri"},"json":{"type":"string","format":"uri"},"calendar_ics":{"type":"string","format":"uri","description":"Calendar file with a reminder on the start day"},"save":{"type":"string","format":"uri","description":"Opens the deal and saves it in the app"},"save_and_remind":{"type":"string","format":"uri","description":"Saves it and turns on a reminder when it starts"}}}}}}}}