Recipe imports from links and photos: what you must check

A recipe import reads the page's data, not the page you read

Paste a URL into a recipe import and the nutrition calculator on the other side is not reading the page the way you read it. It looks for the structured Recipe data the site published inside the HTML and takes the fields it finds there. That part works well: the title, the ingredient lines, the method, the times and the yield come across cleanly when a site publishes them. What no import can promise is the thing a client's plan runs on, which is grams per portion.

Schema.org's Recipe type is the vocabulary almost every food site uses, because it is what puts a recipe card in search results. It defines recipeIngredient, recipeInstructions, recipeYield, prepTime, cookTime and an optional nutrition block. Read what the specification says an ingredient is allowed to be.

An ingredient or ordered list of ingredients and potentially quantities used in the recipe, e.g. 1 cup of sugar, flour or garlic. The ingredients can be represented as free text or more structured values.

Free text is where the grams go missing

Schema.org's own worked example is a banana bread, and its three published ingredient lines are a fair sample of what arrives: "3 or 4 ripe bananas, smashed", "1 egg" and "3/4 cup of sugar". Only the sugar carries a machine-readable unit, the code G21 for a cup.

Each line fails differently. A count of 3 or 4 bananas is a range, and something has to pick one. An egg has no size in the text, and the grading on the box is not a weight. A cup of sugar is a volume, and a food database stores composition per 100 g, so the importer has to guess a density before it can match anything.

Every importer makes all of those guesses. Most will not show you which ones they made, and that is the part to check, not the spelling of the title.

A photograph of a cookbook page or a handwritten card is the same problem with the structured data taken away. Every quantity is read from prose, and every weight the prose never gave stays missing.

The yield is a loaf, and your client eats a slice

recipeYield is defined as the quantity produced by the recipe, and the specification's example of an acceptable value is "1 loaf". In the same example, the nutrition block declares 240 calories and 9 grams of fat, with no serving size next to them.

So does the loaf hold 240 calories, or does a slice? If you read it as the loaf and it was the slice, a plan built on ten slices is out by 2,160 calories. Nothing in the file settles it. Even when a site does publish servingSize, Schema.org types it as free text and describes it as the serving size in terms of the number of volume or mass, so a perfectly valid value is "1 slice".

Set the number of servings yourself, on every imported recipe, before you look at anything else. It is the one field where a wrong answer scales every macro in the meal.

A label photo carries numbers the law already rounded

A photograph of a Nutrition Facts panel is the other kind of import, and it is close to solved. The layout is fixed, the numbers are labelled, and they are for a stated serving. What a photo cannot give back is precision the label never had. In the United States, 21 CFR 101.9 tells manufacturers to round before printing:

• Calories go to the nearest 5-calorie increment up to and including 50 calories, and to the nearest 10-calorie increment above that. Under 5 calories may be printed as zero.
• Total fat goes to the nearest 0.5 g below 5 g and to the nearest gram above 5 g. Under 0.5 g in a serving is printed as zero.
• Protein and total carbohydrate go to the nearest gram. Under 1 g the panel may say "Contains less than 1 gram" instead, and under 0.5 g it may print zero.

Work that through a cooking spray. Each serving is declared as 0 g of fat, which under the rule can be anything up to 0.49 g, so a bottle of 200 servings can hold nearly 100 g of fat that the label never showed. Or take a pack whose panel reads 150 calories a serving: the true figure is somewhere from 145 to 154, and across a 12 serving pack that is a spread of about 108 calories.

For a client eating to a 1,800 calorie target, the rounding on one label is noise. For a client whose whole week is built from packaged food, it is not.

A label does give you grams, unless the food is a liquid

The same rule is generous in one direction. A serving has to be declared in a common household measure, followed by the equivalent metric quantity in brackets, with fluids in millilitres and everything else in grams. That is why a pack reads "1 cup" with a gram figure in brackets after it, and why a label photo is often the fastest way to get a weight for a food your database holds only per 100 g. The exception is a single-serving container, which does not have to print the bracketed metric quantity at all, because the net weight on the front of the pack already carries it.

For nutrition labeling purposes, a teaspoon means 5 milliliters (mL), a tablespoon means 15 mL, a cup means 240 mL, 1 fl oz means 30 mL, and 1 oz in weight means 28 g.

A cup is 240 mL by definition, for oil and for oats alike. Only the label's own gram figure tells you what that cup weighs. USDA is blunt about the limit on its own side: FoodData Central will not change a portion size and its nutrient values for you, so the step from 100 g to the 140 g a client will actually serve is arithmetic somebody has to do.

Run four checks before an imported recipe goes into a plan

1. The servings. Confirm the yield and set it by hand if the page did not publish one.
2. The heavy ingredients. Convert every count and every cup to grams for the items carrying the calories: oils, nuts, cheese, grains, meat.
3. The zeros. A 0 g on a label is a rounded zero. If a recipe uses ten sprays or ten sachets of something, stop treating it as free.
4. The brand. Branded values belong to one product. Swap the brand and the numbers change with it.

Our rule: weigh and type in the five recipes a client repeats every week, and let the importer stand for everything else. Those five are where an error compounds, and they are the only ones you will still be using in three months.

This is the first ten minutes of building a client's meal plan in under an hour, and a slow import costs the other fifty. Peas & Pans reads a link or a photo and matches each ingredient to USDA data, at 30 imports an hour and 100 a day, which is a batch day rather than one recipe at a time. Whatever you import with, the checks above are the same.