{"openapi":"3.1.0","info":{"title":"HuntPrice Canadian Grocery API","description":"Grocery prices, product search, and multi-store basket comparison across major Canadian supermarket chains.","version":"1.0.0"},"servers":[{"url":"https://huntprice.ca","description":"Production server"}],"paths":{"/api/v1/search":{"get":{"tags":["Groceries"],"summary":"Search grocery prices across Canadian stores","description":"Search live grocery prices by product name or keyword. Returns price, unit price, size, and store.","operationId":"api_search_api_v1_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"description":"Search query, e.g. 'butter', 'milk 4L', 'eggs', 'chicken breast'","title":"Q"},"description":"Search query, e.g. 'butter', 'milk 4L', 'eggs', 'chicken breast'"},{"name":"store","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional store chain to filter (e.g. 'Food Basics', 'Walmart')","title":"Store"},"description":"Optional store chain to filter (e.g. 'Food Basics', 'Walmart')"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Max number of items to return","default":15,"title":"Limit"},"description":"Max number of items to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/cheapest":{"get":{"tags":["Groceries"],"summary":"Find the single cheapest store for an item","description":"Returns the store offering the single lowest price for the requested grocery item.","operationId":"api_cheapest_api_v1_cheapest_get","parameters":[{"name":"item","in":"query","required":true,"schema":{"type":"string","minLength":2,"description":"Item name, e.g. 'butter', 'eggs', 'milk 4l'","title":"Item"},"description":"Item name, e.g. 'butter', 'eggs', 'milk 4l'"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/compare":{"post":{"tags":["Groceries"],"summary":"Compare shopping basket across stores in a city","description":"Compare a full grocery basket across supermarket chains in a given Canadian city to find the cheapest store and total cost.","operationId":"api_compare_api_v1_compare_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/weekly":{"get":{"tags":["Weekly Rankings"],"summary":"Get this week's cheapest grocery store report","description":"Returns the weekly scorecard showing the cheapest store based on the standard basket for a city.","operationId":"api_weekly_api_v1_weekly_get","parameters":[{"name":"city","in":"query","required":false,"schema":{"type":"string","description":"City to get weekly rankings for","default":"Ottawa, ON","title":"City"},"description":"City to get weekly rankings for"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/stores":{"get":{"tags":["Stores"],"summary":"List supported grocery chains and branches for a city","description":"Lists all supported supermarket chains and branch addresses for the given city.","operationId":"api_stores_api_v1_stores_get","parameters":[{"name":"city","in":"query","required":false,"schema":{"type":"string","description":"City to list stores for (e.g. 'Ottawa', 'Toronto')","default":"Ottawa","title":"City"},"description":"City to list stores for (e.g. 'Ottawa', 'Toronto')"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/cities":{"get":{"tags":["Stores"],"summary":"List all supported cities","description":"Returns all 14 Canadian metropolitan areas supported by HuntPrice.","operationId":"api_cities_api_cities_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"BasketItemRequest":{"properties":{"name":{"type":"string","title":"Name","description":"Item name or query, e.g. '2% milk', 'large white eggs', 'bananas', 'butter'"},"qty":{"type":"integer","minimum":1.0,"title":"Qty","description":"Quantity of the item","default":1}},"type":"object","required":["name"],"title":"BasketItemRequest"},"Body_handle_contact_submit_contact_post":{"properties":{"name":{"type":"string","title":"Name","default":""},"email":{"type":"string","title":"Email","default":""},"subject":{"type":"string","title":"Subject","default":""},"message":{"type":"string","title":"Message","default":""},"website":{"type":"string","title":"Website","default":""}},"type":"object","title":"Body_handle_contact_submit_contact_post"},"Body_search_items_search_items_post":{"properties":{"query":{"type":"string","title":"Query","default":""},"target_store":{"type":"string","title":"Target Store"}},"type":"object","title":"Body_search_items_search_items_post"},"CompareRequest":{"properties":{"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/BasketItemRequest"},{"type":"string"}]},"type":"array","title":"Items","description":"List of grocery items to compare across stores"},"city":{"type":"string","title":"City","description":"City to search in (e.g. 'Ottawa', 'Toronto', 'Vancouver')","default":"Ottawa"},"user_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Address","description":"User address or neighborhood (e.g. 'Kanata', 'Downtown')"},"user_lat":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"User Lat","description":"User latitude (optional for driving distance calculation)"},"user_lon":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"User Lon","description":"User longitude (optional for driving distance calculation)"},"online_shopping":{"type":"boolean","title":"Online Shopping","description":"Whether to include store delivery fees instead of in-store pricing","default":false},"factor_distance":{"type":"boolean","title":"Factor Distance","description":"Whether to include driving distance cost ($1.50/km) in total score","default":false},"ranking_mode":{"type":"string","title":"Ranking Mode","description":"'value' for best unit price per 100g, or 'price' for cheapest raw package price","default":"value"},"allowed_stores":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Stores","description":"Optional list of store chains to filter (e.g. ['Walmart', 'Costco', 'Food Basics'])"}},"type":"object","required":["items"],"title":"CompareRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}