{ "openapi": "3.0.3", "info": { "title": "Plate Pal", "version": "1.2.0", "description": "Calories, protein, carbs, fat, sugar and salt for everyday foods, restaurant and fast-food dishes, whole meals and packaged products, scaled to the amount the user says (grams, servings, sizes, or items like 2 eggs). Barcode lookups with UK traffic-light flags, and simple meal ideas by goal and diet, including halal. Every answer has a ready-to-read `say` line and a `note` that this is general information, not medical or dietetic advice. Read only, no account, nothing stored. Data: USDA FoodData Central (built-in typical values and the FNDDS survey foods with real portion weights) and Open Food Facts.", "contact": { "email": "hello@askmizan.com" } }, "servers": [ { "url": "https://platepal.pages.dev" } ], "paths": { "/v1/food": { "get": { "operationId": "getFoodNutrition", "summary": "Calories and macros for a food, dish or product, for the amount the user says", "description": "Use for \"how many calories in a Big Mac?\", \"protein in 200g chicken breast\", \"calories in chicken biryani\", \"a slice of pepperoni pizza\", \"a large latte\" or a whole meal like \"2 eggs, 2 slices of toast and a coffee\". Put the whole amount and food in q, or pass grams or servings separately. Generic foods and dishes (thousands, including fast food and restaurant dishes) use USDA values with real portion weights (slice, cup, small, medium, large, one item); brands come from Open Food Facts. For a chain item USDA doesn't list, a typical version is used and the say line says so. A whole meal returns items (each food with its amount and nutrition) and total. Returns nutrition for the amount, per_100 values, portions, UK traffic lights (per 100 g, or per 100 ml for drinks) and caffeine_mg for drinks that have it. Read out `say`, then the `note`.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "The food or meal, optionally with amounts, for example 200g chicken breast, a large banana, or 2 eggs and a slice of toast.", "schema": { "type": "string", "maxLength": 160 } }, { "name": "grams", "in": "query", "required": false, "description": "Amount in grams (1 to 5000). Overrides any amount in q.", "schema": { "type": "number", "minimum": 1, "maximum": 5000 } }, { "name": "servings", "in": "query", "required": false, "description": "Number of servings or items (0.25 to 20).", "schema": { "type": "number", "minimum": 0.25, "maximum": 20 } }, { "name": "country", "in": "query", "required": false, "description": "Two-letter country code, used to prefer local versions of branded products. Default from the request.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Nutrition with say and note" }, "400": { "description": "Missing or bad input" }, "404": { "description": "Food not found" }, "503": { "description": "Food database not answering" } } } }, "/v1/barcode": { "get": { "operationId": "getBarcodeNutrition", "summary": "Nutrition for a packaged product by barcode, with UK traffic lights", "description": "Use for \"is this barcode high in sugar?\", \"how many calories in this?\" after a scan, or \"what's the salt in 5000157024886?\". Returns per 100 g (or 100 ml) and per serving values, traffic lights for fat, saturates, sugars and salt, Nutri-Score, allergens and a Halal or Not? link for checking the ingredients.", "parameters": [ { "name": "code", "in": "query", "required": true, "description": "Barcode digits (8 to 14).", "schema": { "type": "string" } }, { "name": "servings", "in": "query", "required": false, "description": "Number of servings to total up (0.25 to 20).", "schema": { "type": "number", "minimum": 0.25, "maximum": 20 } } ], "responses": { "200": { "description": "Product nutrition" }, "400": { "description": "Bad barcode" }, "404": { "description": "Not in Open Food Facts" } } } }, "/v1/meals": { "get": { "operationId": "getMealIdeas", "summary": "Simple meal ideas by goal, diet and meal, with rough macros", "description": "Use for \"give me a high protein halal dinner idea\", \"a quick vegan lunch\", \"cheap vegetarian breakfast ideas\". Goals: high protein, low carb, budget, quick, high fibre. Diets: vegetarian, vegan, pescatarian, halal. Meals: breakfast, lunch, dinner, snack. You can pass the user's words in q instead. Ideas rotate daily. It does not set calorie or weight targets. Also returns shop (up to two Amazon links: a cookbook that fits the request and meal prep kit) with a disclosure; offer those only after the ideas, never instead of them.", "parameters": [ { "name": "goal", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "diet", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "meal", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Free text, for example high protein halal dinner.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "n", "in": "query", "required": false, "description": "How many ideas, 1 to 8. Default 3.", "schema": { "type": "integer", "minimum": 1, "maximum": 8 } }, { "name": "country", "in": "query", "required": false, "description": "Two-letter country code for the shop links (US, GB and IE get local Amazon links). Default from the request.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Meal ideas", "content": { "application/json": { "schema": { "type": "object", "properties": { "say": { "type": "string", "description": "A short answer to read to the user." }, "shop": { "type": "array", "maxItems": 2, "description": "Optional shop links, only shown if the user wants them: a cookbook matching the goal and diet, and meal prep containers. Not part of the answer. Absent on weight or calorie target requests.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "buy": { "type": "string", "description": "Amazon search link (affiliate link in the US, UK and Ireland)." } } } }, "disclosure": { "type": "string", "description": "Plain-words affiliate disclosure. Present whenever shop links are." } } } } } }, "400": { "description": "Bad input" } } } }, "/v1/health": { "get": { "operationId": "health", "summary": "Service status", "responses": { "200": { "description": "OK" } } } } } }