DEV Community: Dietly

DietlyAPI vs FatSecret: nutrition API comparison (2026)

Dietly — Wed, 22 Jul 2026 19:26:57 +0000

DietlyAPI vs FatSecret

For the core job of high-volume food search and barcode lookup, DietlyAPI is the stronger default: its pricing and limits are published, paid plans have no monthly call cap, and the API is built around that workload. FatSecret remains relevant where its specialist features are the deciding requirement.

At a glance

	DietlyAPI	FatSecret
Monthly price	Free tier; Pro €27/mo; Scale €92/mo	Basic free tier; Premier by quote
Rate limit	Free ~30 req/min per IP; Pro 500 req/min; Scale 3,000 req/min (per account)	Per-minute limit not publicly specified (Basic)
Included quota	No monthly call cap on paid plans (rate-limited only)	5,000 calls/day (Basic)
Underlying data	Open Food Facts + USDA FoodData Central	Proprietary database; 58+ country datasets on Premier
Best at	High-throughput fuzzy food search, barcode lookup, stable IDs, per-100g nutrients, MCP server	Free tier, free Premier for eligible startups/nonprofits/students, many localized country datasets
Trade-offs	No recipe analysis, no natural-language meal parsing, no image recognition	Basic capped at 5,000 calls/day; verification/attribution required; US-focused unless on Premier

How capacity is metered

FatSecret's free Basic tier caps at 5,000 calls/day; higher volume moves you to quote-based Premier. DietlyAPI's paid plans lift throughput to a fixed per-minute rate at a published price.

Which should you choose?

Specialist case for FatSecret

FatSecret can be a better fit if you qualify for its free Premier programme, or specifically need verified country-specific datasets across many markets.

Why DietlyAPI is the stronger default

DietlyAPI is the stronger pick when you need more than 5,000 calls/day without a verification process, at a predictable flat price and a single global catalog.

For food search and barcode lookup with predictable pricing, DietlyAPI is our recommended choice. Choose FatSecret when the specialist features above matter more than throughput, transparent self-serve pricing and a simple request-based limit.

Try DietlyAPI free. Public read endpoints work with no key at a shared per-IP limit — enough to prototype in minutes.
Get the API

DietlyAPI vs Nutritionix: nutrition API comparison (2026)

Dietly — Wed, 22 Jul 2026 19:26:56 +0000

DietlyAPI vs Nutritionix

For the core job of high-volume food search and barcode lookup, DietlyAPI is the stronger default: its pricing and limits are published, paid plans have no monthly call cap, and the API is built around that workload. Nutritionix remains relevant where its specialist features are the deciding requirement.

At a glance

	DietlyAPI	Nutritionix
Monthly price	Free tier; Pro €27/mo; Scale €92/mo	Quote / contact sales (Syndigo)
Rate limit	Free ~30 req/min per IP; Pro 500 req/min; Scale 3,000 req/min (per account)	Not publicly specified
Included quota	No monthly call cap on paid plans (rate-limited only)	Not publicly specified
Underlying data	Open Food Facts + USDA FoodData Central	600K+ food database (US-focused), branded + restaurant items
Best at	High-throughput fuzzy food search, barcode lookup, stable IDs, per-100g nutrients, MCP server	Natural-language food logging, instant search, exercise parsing
Trade-offs	No recipe analysis, no natural-language meal parsing, no image recognition	Pricing and limits not published; enterprise/quote sales motion

How capacity is metered

Nutritionix (owned by Syndigo) publishes neither numeric rate limits nor list pricing, so capacity and cost are established by quote. DietlyAPI publishes its plans, limits and OpenAPI spec openly.

Which should you choose?

Specialist case for Nutritionix

Nutritionix is a better fit specifically when natural-language food logging (“two eggs and toast” → nutrients) and a large US restaurant/branded catalog are central to your product.

Why DietlyAPI is the stronger default

DietlyAPI is the stronger pick when you want transparent, self-serve pricing and high-throughput search/barcode access without contacting sales for a quote.

For food search and barcode lookup with predictable pricing, DietlyAPI is our recommended choice. Choose Nutritionix when the specialist features above matter more than throughput, transparent self-serve pricing and a simple request-based limit.

Try DietlyAPI free. Public read endpoints work with no key at a shared per-IP limit — enough to prototype in minutes.
Get the API

DietlyAPI vs Spoonacular: nutrition API comparison (2026)

Dietly — Wed, 22 Jul 2026 19:26:12 +0000

DietlyAPI vs Spoonacular

For the core job of high-volume food search and barcode lookup, DietlyAPI is the stronger default: its pricing and limits are published, paid plans have no monthly call cap, and the API is built around that workload. Spoonacular remains relevant where its specialist features are the deciding requirement.

At a glance

	DietlyAPI	Spoonacular
Monthly price	Free tier; Pro €27/mo; Scale €92/mo	Cook US$29/mo (and other tiers)
Rate limit	Free ~30 req/min per IP; Pro 500 req/min; Scale 3,000 req/min (per account)	5 requests/sec
Included quota	No monthly call cap on paid plans (rate-limited only)	1,500 points/day (point-weighted: some calls cost >1 point)
Underlying data	Open Food Facts + USDA FoodData Central	Recipe, ingredient and product database
Best at	High-throughput fuzzy food search, barcode lookup, stable IDs, per-100g nutrients, MCP server	Recipe search, meal planning, ingredient substitution, wine pairing
Trade-offs	No recipe analysis, no natural-language meal parsing, no image recognition	Point-weighted quota; cached data generally must be deleted after 1 hour

How capacity is metered

Spoonacular bills in points, and some endpoints or larger result sets cost more than one point, so a nominal daily quota does not map one-to-one to calls. DietlyAPI counts plain requests against a per-minute rate with no point weighting.

Which should you choose?

Specialist case for Spoonacular

Spoonacular is a better fit when recipes are central: recipe discovery, meal planning and ingredient workflows are its core, and DietlyAPI does not offer them.

Why DietlyAPI is the stronger default

DietlyAPI is the stronger pick for a food/nutrition catalog: fuzzy product search and barcode lookup at high volume, with simple per-request behaviour instead of a point budget.

For food search and barcode lookup with predictable pricing, DietlyAPI is our recommended choice. Choose Spoonacular when the specialist features above matter more than throughput, transparent self-serve pricing and a simple request-based limit.

Try DietlyAPI free. Public read endpoints work with no key at a shared per-IP limit — enough to prototype in minutes.
Get the API

DietlyAPI vs Edamam: nutrition API comparison (2026)

Dietly — Wed, 22 Jul 2026 19:26:11 +0000

DietlyAPI vs Edamam

For the core job of high-volume food search and barcode lookup, DietlyAPI is the stronger default: its pricing and limits are published, paid plans have no monthly call cap, and the API is built around that workload. Edamam remains relevant where its specialist features are the deciding requirement.

At a glance

	DietlyAPI	Edamam
Monthly price	Free tier; Pro €27/mo; Scale €92/mo	Basic US$14/mo (Core US$69, Plus US$299)
Rate limit	Free ~30 req/min per IP; Pro 500 req/min; Scale 3,000 req/min (per account)	50 food requests/min (Basic)
Included quota	No monthly call cap on paid plans (rate-limited only)	100,000 calls/month (Basic)
Underlying data	Open Food Facts + USDA FoodData Central	Proprietary food database + branded/grocery data
Best at	High-throughput fuzzy food search, barcode lookup, stable IDs, per-100g nutrients, MCP server	Natural-language ingredient parser, measures, diet/allergy filters
Trade-offs	No recipe analysis, no natural-language meal parsing, no image recognition	Monthly call quota caps sustained throughput; caching restricted

How capacity is metered

Edamam meters a fixed monthly quota (100,000 calls on Basic), so sustained throughput is bounded by that allowance. DietlyAPI's paid plans apply only a per-minute rate ceiling with no monthly cap, so capacity scales with the rate rather than a credit balance.

Which should you choose?

Specialist case for Edamam

Edamam is a better fit specifically when natural-language recipe/ingredient parsing, measure conversion, or built-in diet and allergy filtering out of the box.

Why DietlyAPI is the stronger default

DietlyAPI is the stronger pick when you need high request volume for plain food search and barcode lookup at a flat monthly price, without a monthly call allowance to manage.

For food search and barcode lookup with predictable pricing, DietlyAPI is our recommended choice. Choose Edamam when the specialist features above matter more than throughput, transparent self-serve pricing and a simple request-based limit.

Try DietlyAPI free. Public read endpoints work with no key at a shared per-IP limit — enough to prototype in minutes.
Get the API

Nutrition API comparison (2026): 7 providers by price, limits & features

Dietly — Wed, 22 Jul 2026 19:25:26 +0000

Nutrition API comparison (2026)

For high-volume food search and barcode lookup, DietlyAPI is the strongest fit in this comparison: paid plans combine published throughput with no monthly call cap. Other providers can still be the right choice when recipes, natural-language parsing, downloadable open data or authoritative US reference values are the main requirement.

We build DietlyAPI and believe its focused, self-serve model is the better default for most food-search and barcode products. The figures below remain verifiable, and we still identify the narrower workflows where another provider has a genuine advantage.

The comparison table

API / plan	Type	Monthly price	Rate limit	Included quota	Best at
Open Food Facts	Open, crowdsourced	Free	10 searches/min; 15 product reads/min per IP	No published monthly cap	Open worldwide packaged-product data; bulk export / self-hosting
USDA FoodData Central	Public reference	Free	1,000 requests/hour per IP	No published monthly cap	Authoritative US reference data (free key required)
FatSecret (Basic)	Commercial	Free tier	Not publicly specified	5,000 calls/day	Free tier; localized country datasets on Premier
Edamam (Basic)	Commercial	US$14/mo	50 food requests/min	100,000 calls/month	NLP ingredient parser, measures, diet/allergy filters
Spoonacular (Cook)	Commercial	US$29/mo	5 requests/sec	1,500 points/day (weighted)	Recipes, meal planning, ingredient workflows
Nutritionix	Commercial	Quote / contact	Not specified	Not specified	Natural-language food logging; large US catalog
DietlyAPI (Pro)	Commercial	€27/mo	500 requests/min per account	No monthly call cap	High-throughput fuzzy search + barcode lookup
DietlyAPI (Scale)	Commercial	€92/mo	3,000 requests/min per account	No monthly call cap	As Pro, higher throughput

Providers meter capacity differently. Some (Edamam, Spoonacular, FatSecret) enforce a monthly or daily quota, so sustained throughput is bounded by that allowance. Others (USDA, DietlyAPI) apply a per-interval rate ceiling with no separate monthly credit, so capacity depends on the sustained rate. Spoonacular’s point weighting means a nominal quota does not map one-to-one to calls.

What each option is best at

Open Food Facts

A free, crowdsourced global database of packaged products, keyed by barcode. Reads need no login, but the hosted search endpoint is limited (10 req/min/IP) and is not intended for search-as-you-type; high-volume users are pointed to bulk exports or self-hosting.

USDA FoodData Central

The authoritative US reference dataset (Foundation, FNDDS, SR Legacy and branded foods), free and in the public domain. Its API needs a free data.gov key and defaults to 1,000 requests/hour per IP.

FatSecret

A commercial platform whose free Basic tier is capped at 5,000 calls/day. Premier adds many country datasets, but pricing is quote-based and its free programme is limited to eligible applicants after verification.

Edamam

Its Basic plan adds an ingredient parser, measures and diet/allergy filters for US$14/month, but the 100,000-call monthly quota bounds sustained use and caching rights are restricted.

Spoonacular

Recipe-oriented. The US$29 Cook plan covers recipe and ingredient tooling with a point-weighted daily quota; it is not a like-for-like food catalog, and cached data generally must be deleted after an hour.

Nutritionix

Owned by Syndigo, focused on natural-language food logging over a large US-centric catalog. Current numeric pricing and limits are not published; access is quote-based.

DietlyAPI

The strongest fit here for high-throughput fuzzy food search and barcode lookup: transparent self-serve pricing, stable IDs, per-100g nutrients and paid plans with no monthly call cap. It deliberately focuses on catalog lookup rather than recipe analysis, NLP meal parsing or image recognition.

How to choose

Start with DietlyAPI when your product needs dependable food search, barcode lookup and predictable capacity. Move to a specialist alternative when one of the narrower workflows below is central to the product.

High-throughput fuzzy search + barcode lookup, flat pricing — DietlyAPI.
Open, downloadable worldwide product data — Open Food Facts.
Authoritative US reference values — USDA FoodData Central.
Natural-language parsing, measures, diet/allergy filters — Edamam.
Recipes and ingredient workflows — Spoonacular.
Natural-language food logging (US-centric) — Nutritionix.

Head-to-head pages

Try DietlyAPI free. Public read endpoints work with no key at a shared per-IP limit.
Get the API

Dietly Food Data Quality Report 2026

Dietly — Wed, 22 Jul 2026 19:25:25 +0000

Dietly catalog report · July 2026

Inside 4.75 million food records.

A large catalog is not automatically a usable catalog. Dietly measured every record in its production database to see how often essential nutrition fields, identifiers, images and serving information are actually present.

By the Dietly engineering team · Published July 21, 2026 · Production snapshot: 4,752,013 records

55.3% contain calories, protein, carbohydrates and fat

98.3% have a well-formed 8–14 digit barcode

65.8% include a product image

40.3% meet Dietly's minimum public-page data rule

The short version: Dietly's advantage is not merely having 4.75 million records; it is turning an uneven source catalog into more useful results. Dietly ranks complete and plausible records first, preserves sparse records for long-tail coverage, and applies a higher threshold before publishing a record as a public nutrition page.

Raw catalog quality is not user-facing result quality

This report measures all 4.75 million raw records stored in Dietly's catalog, including incomplete source records retained for long-tail and specific-product coverage. Dietly does not present every record equally.

Search automatically prioritizes the best available candidates using nutritional completeness, plausibility checks, images, serving information, source confidence and relevance. Records with the same normalized name are consolidated so the stronger candidate is normally shown, while curated food lists exclude incomplete or implausible records entirely.

Consequently, the percentages below describe the underlying source catalog, not the typical quality of results users receive. Sparse records are generally available as fallbacks when Dietly has no stronger match for a specific product. When an upstream source improves an existing record, Dietly's refresh process can replace the older version of that same source record.

What 4.75 million records actually contain

The chart below uses the entire production catalog as its denominator. A field counts as present when the normalized Dietly record contains a non-empty value; presence does not prove that the source label is correct.

How to read the 55.3% figure: it should not be interpreted as meaning 44.7% of normal search results are incomplete. Lower-quality catalog records are deprioritized or excluded during result selection.

Field or rule	Records	Coverage
Any barcode	4,738,308	99.7%
Well-formed barcode	4,669,075	98.3%
Country metadata	4,644,862	97.7%
Brand	3,292,195	69.3%
Product image	3,124,672	65.8%
All four core nutrition fields	2,629,070	55.3%
Sugar	2,546,586	53.6%
Saturated fat	2,496,562	52.5%
Sodium	2,376,654	50.0%
Category	2,237,134	47.1%
Serving size	1,717,378	36.1%
Fiber	1,391,584	29.3%

The useful catalog is a funnel

Dietly does not treat a name and barcode as sufficient for every use case. Search can retain a broad source-labeled inventory, while public nutrition pages require a smaller minimum set of fields.

4.75M: total source-labeled records in the measured catalog

2.63M: records with all four core nutrition fields

1.91M: records with calories, protein and an image—Dietly's minimum public-page rule

The public-page rule is deliberately easy to explain and reproduce. It is not a claim that all 1.91 million records should be published or indexed. Page selection can still account for nutrient completeness, source confidence, category diversity and whether a record already has a stable public URL.

Completeness and plausibility are different tests

Of the 2,629,070 records with complete core nutrition, 2,622,854—or 99.8%—fall inside Dietly's broad per-100-gram plausibility bounds: 0–900 kcal and 0–100 grams each for protein, fat and carbohydrates. These are guardrails for obvious impossibilities, not laboratory validation.

A second consistency check compares reported calories with the simple 4/4/9 energy estimate from protein, carbohydrates and fat. Using a tolerance of the larger of 50 kcal or 20% of reported calories, 2,525,253 complete records—96.1%—are internally consistent. Fiber, alcohols, rounding and local label rules can create legitimate differences, so this check is a warning signal rather than a verdict.

Important limitation: this report measures coverage and internal consistency. Dietly did not independently laboratory-test the products, and a populated field can still reproduce an incorrect or outdated source label.

How Dietly turns uneven source data into useful results

Keep provenance visible

API results carry a source and confidence value. Dietly's catalog currently combines labeled records from Open Food Facts, USDA FoodData Central and a very small number of Dietly community or assisted entries. Source coverage and field definitions differ, so consumers should not assume every row was produced through the same process.

Rank useful records before sparse ones

Search ranking favors exact names, useful identifiers, complete and plausible core nutrition, images, category information and stronger confidence. Missing nutrients remain missing in the API instead of silently becoming measured zeroes.

Separate discovery from publication

A record can help a barcode or text search without deserving a standalone public page. That separation lets Dietly preserve breadth while applying a higher publication threshold to pages intended for people and search engines.

The practical result: Dietly keeps the breadth of a multi-million-record catalog without pretending every source row has equal value. Search quality comes from the normalization, confidence signals and selection rules layered on top of that raw coverage.

Methodology

Snapshot

A read-only aggregate query was run against Dietly's production catalog on July 21, 2026. The database contained 4,752,013 records at query time. Percentages use that total unless a different denominator is stated.

Core nutrition: Calories, protein, carbohydrates and fat are all present.

Well-formed barcode: Contains only digits and is 8–14 characters long. This is a structural check, not a GTIN checksum or ownership check.

Public-page rule: Calories, protein and a non-empty image URL are present. This is the generator's minimum data-selection rule, not an indexability guarantee.

Broad plausibility: Complete core nutrition with 0–900 kcal and 0–100 g each of protein, fat and carbohydrates per 100 g.

Energy consistency: The reported calories are within the larger of 50 kcal or 20% of the 4/4/9 estimate. The test intentionally allows for rounding and nutrients outside that simple model.

Privacy and reproducibility

The analysis uses counts and percentages only. No record-level database export accompanies this report. Definitions and exact counts are published so the claims can be evaluated without disclosing Dietly's normalized catalog or internal processing pipeline.

Sources and reuse

Open Food Facts database data is reused under the Open Database License; its individual contents use the Database Contents License, and product images have separate licensing terms. USDA FoodData Central data is published in the public domain under CC0. Dietly's measurements, normalization and presentation do not imply that either source endorses Dietly.

API Key Hygiene: Scopes, Expiry, Rotation and 2FA

Dietly — Wed, 22 Jul 2026 19:02:35 +0000

API key hygiene: rotation, scopes, expiry and 2FA

The single highest-value change you can make is to stop using one key for
everything. One key per service, each with the narrowest scope that still works, means a leak
is a contained incident rather than a full compromise: you rotate the one key, the one service has a
short blip, and nothing else on your account notices. Everything else on this page is a refinement of
that idea. DietlyAPI supports named access keys with independent scopes, expiry dates and per-key rate
caps, so the good structure is available without any extra tooling.

The checklist: one key per service, read scope unless you need
writes, an expiry date on anything temporary, a per-key rate cap so one service cannot starve the
others, 2FA on the account itself, and a rotation you have practised before you need it.

One key per service

Name keys after where they run: web-prod, worker-prod,
ci, laptop-dev. This costs nothing and pays back the first time something goes
wrong, because it turns two impossible questions into easy ones. Which service is generating that
traffic spike? The one whose key shows the usage. What do I have to redeploy after this key leaked? The
one service that used it. A single shared key makes both questions unanswerable, and it means every
rotation is a coordinated outage across your whole stack.

The same logic applies to environments. A development key on a laptop, in a shell history and in
half a dozen scratch scripts is the likeliest key on your account to leak, and it should never be the
same key that serves production traffic.

Use read scope unless you need more

Keys carry a scope. A read-scope key can perform GET requests and nothing else; if it is used for
any other method the API refuses with a clear 403:

{"detail":"This API key is read-only. Use a full-access key for this endpoint."}

Most integrations only ever look data up, so read scope is the correct default rather than a
hardened configuration. It also converts an entire class of incident into a non-event: a leaked
read-only key exposes public catalog data that anyone can already query anonymously. Reach for a
full-access key only for the specific service that genuinely needs to write, and keep that key's blast
radius as small as you can.

Put an expiry on anything temporary

Access keys accept an expiry, set in days. Anything you create for a contractor, a demo, a spike or
a one-off migration should have one, because the failure mode of temporary credentials is that they
are never temporary. An expiry converts "someone should remember to delete this" into a guarantee. The
dashboard warns you before a key expires, so the honest tradeoff is a scheduled, visible interruption
against an unbounded credential that outlives the reason it was created. Long-lived production keys
can stay open-ended; everything else should have a date on it.

Set a per-key rate cap

Each access key can carry its own rate limit below your plan's ceiling. This is a stability feature
more than a security one. A batch job that suddenly loops does not just fail; it consumes the whole
account's per-minute budget and starves the user-facing service that shares it. Give the batch worker a
cap it cannot exceed and the blast radius of that bug is the batch job alone. A useful default is to
cap background workers at something well under half your plan limit and leave interactive traffic
uncapped.

Rotate before you need to, and practise it

Rotation issues a new secret for an existing key, keeping its name, scope, expiry and cap. That
matters because it means rotating does not require rebuilding your configuration; only the secret
changes.

POST /auth/access-keys/{id}/rotate

The reason to rehearse is that the hard part is never the rotate button. It is discovering, at the
worst possible moment, that the key is hardcoded in a config file nobody has touched in a year, or that
three services read it from an environment variable set by hand on a box that predates your deployment
pipeline. Rotate one non-critical key deliberately, on a quiet afternoon, and find out how long it
actually takes. Do that once and a real incident becomes a twenty-minute job instead of an evening.

If a key is exposed publicly, in a repository, a client bundle or a log, rotate rather than delete.
Rotation keeps the key's identity and settings while invalidating the leaked secret, so you get the
security outcome without also losing the configuration.

Turn on 2FA for the account

All of the above protects individual keys. None of it helps if someone signs in to the dashboard,
because from there they can mint new keys at will. DietlyAPI supports TOTP two-factor authentication
with any standard authenticator app, plus recovery codes for the day you lose your phone. Store the
recovery codes somewhere that is not the same password manager you use to log in, and regenerate them
if you ever use one. This is a two-minute setup that sits underneath every other control on this
page.

Keep keys out of the places they leak from

Client bundles. Anything shipped to a browser or a mobile app is public, including
values inlined at build time. Call the API from your server. The public read endpoints work with no key
at all, so prototypes do not need one.
Repositories. Use environment variables or a secret manager, and add a scanning
hook so a key cannot be committed in the first place. Once a secret is in git history, rewriting the
history is not a fix, because clones and forks still have it. Rotate.
Logs and error trackers. Logging full request headers is the quiet one, because it
usually works fine right up until the logs are shared with someone. Redact
Authorization at the logger.
Screenshots and support threads. Keys get pasted into issue trackers constantly. If
one has been, treat it as leaked and rotate; the cost of an unnecessary rotation is a few minutes.

Watch the audit log and the usage numbers

The dashboard records account security events and shows per-key usage. Two habits make that data
useful rather than decorative. First, look at per-key usage occasionally and confirm each key's shape
matches what that service is supposed to do; a development key with steady round-the-clock traffic is
telling you something. Second, check the audit log after anything unexpected, because it is the only
record that distinguishes "our batch job misbehaved" from "someone else has account access". Both
questions are answerable in about thirty seconds if you know where to look, and unanswerable if you
have one shared key.

What good looks like

A tidy small-team setup is four keys and one 2FA enrolment. A read-scope web-prod key
with no expiry and no per-key cap, serving user traffic. A read-scope worker-prod key
capped at a fraction of the plan limit, running scheduled syncs. A read-scope ci key with a
90-day expiry. A read-scope laptop-dev key per developer, also expiring, and rotated
without ceremony whenever anyone feels like it. Nothing in that list is difficult, and together they
mean any single leak costs you one rotation and no downtime. If you also cache aggressively, as the
caching guide describes, the capped worker will rarely come close
to its limit either.

Common questions

What is the safest default scope for an API key?

Read. A read-scope key can only perform GET requests, and anything else returns a 403 explaining that the key is read-only. Most integrations only look data up, and a leaked read-only key exposes catalog data that can already be queried anonymously.

Should I rotate or delete a leaked key?

Rotate. Rotation issues a new secret while keeping the key's name, scope, expiry and rate cap, so the leaked secret stops working without you having to rebuild the configuration around it.

Why set a per-key rate limit?

To contain bugs rather than attackers. A looping batch job on a shared key consumes the whole account's per-minute budget and starves user-facing traffic. A cap on the worker means the blast radius is the worker alone.

Can I put an API key in my mobile app?

No. Anything shipped in a client bundle is public, including values inlined at build time. Call the API from your own server. Prototypes can use the public read endpoints, which need no key at all.

Caching Strategies for a Nutrition API: TTLs, Keys and the Cost Math

Dietly — Wed, 22 Jul 2026 19:01:44 +0000

Caching strategies for nutrition APIs

Nutrition data is close to the ideal caching workload: the records almost never
change, the same few thousand foods account for most lookups, and a stale answer is rarely wrong.
A cache in front of DietlyAPI is therefore not an optimisation you add later under load. It is the
difference between an app that fits comfortably inside the free 30 requests per minute and one that
needs a paid plan to do the same job. This guide covers what to cache, for how long, how to key it, and
the arithmetic that tells you which plan you actually need.

The short version: cache barcode and food-id lookups for 30 days,
search results for a day, and never cache a 429 or a 5xx. On a food-logging app that alone typically
removes 80 to 95% of outbound calls, because users log the same foods repeatedly.

Pick a TTL per data type, not one for everything

The right expiry follows from how often the underlying thing changes and what a stale answer costs
you.

Response	Suggested TTL	Why
`GET /barcode/{code}` hit	30 days	A barcode maps to one product; reformulations are rare and slow
`GET /food/{id}`	30 days	Same record, addressed directly; the safest thing in the catalog to cache
`GET /search?q=...`	1 to 7 days	Ranking and catalog coverage improve over time, so let it refresh
404 from a lookup	1 to 24 hours	Negative caching stops a scanner hammering the same unknown barcode
429 or any 5xx	Never	Caching a failure turns a blip into an outage you inflicted

Negative caching deserves the emphasis. A barcode scanner pointed at an unlisted product will retry
on every frame if you let it, and each one of those is a real request against your limit. Caching the
404 for even an hour converts a pathological loop into a single call, and the user experience is
identical because the answer is the same either way.

Key the cache on what actually varies

A cache key should contain everything that changes the response and nothing that does not. For this
API that is the endpoint, the identifier or normalised query, and the limit.

def cache_key(kind, value, limit=None):
    if kind == "search":
        # normalise so "Greek Yogurt", "greek yogurt " and "greek  yogurt"
        # are one entry rather than three
        value = " ".join(value.lower().split())
    return f"dietly:{kind}:{value}" + (f":{limit}" if limit else "")

cache_key("search", "  Greek   Yogurt ", 10)   # dietly:search:greek yogurt:10
cache_key("barcode", "5000159407236")          # dietly:barcode:5000159407236

Two mistakes are worth avoiding. Do not put the API key in the cache key: the response does not
depend on which key fetched it, and including it fragments the cache per user for no benefit. Do put
the limit in, because a request for 5 results and one for 50 genuinely differ, and serving
the short list to the caller who asked for the long one is a bug that will take you an afternoon to
find.

A cache that fits in twenty lines

You do not need Redis to start. A dictionary with timestamps handles a single process, and the
interface is the same one you will keep when you move to something shared.

import time
import requests

class CachedDietly:
    def __init__(self, ttl=60 * 60 * 24 * 30, api_key=None):
        self.ttl = ttl
        self.store = {}
        self.session = requests.Session()
        if api_key:
            self.session.headers["Authorization"] = f"Bearer {api_key}"

    def _get(self, key, url, params=None, ttl=None):
        ttl = self.ttl if ttl is None else ttl
        hit = self.store.get(key)
        if hit and time.time() - hit[0] < ttl:
            return hit[1]
        r = self.session.get(url, params=params, timeout=10)
        if r.status_code == 404:
            self.store[key] = (time.time(), None)      # negative cache
            return None
        r.raise_for_status()                           # never cache 429/5xx
        data = r.json()                                # parse once, not twice
        self.store[key] = (time.time(), data)
        return data

    def barcode(self, code):
        return self._get(f"barcode:{code}",
                         f"https://api.getdietly.com/barcode/{code}")

    def search(self, q, limit=10):
        q = " ".join(q.lower().split())
        return self._get(f"search:{q}:{limit}",
                         "https://api.getdietly.com/search",
                         {"q": q, "limit": limit},
                         ttl=60 * 60 * 24)

The important line is r.raise_for_status() sitting above the store write.
Failures must never enter the cache. The second important line is the negative cache on 404, which
stores None rather than skipping the write, so a repeated miss costs nothing.

Move it out of process when you have more than one

An in-process dictionary dies with the worker and is duplicated across every replica, so four
workers means four cold caches and four times the upstream traffic. Redis with a TTL fixes both.

import json
import redis

r = redis.Redis()

def cached_json(key, ttl, fetch):
    raw = r.get(key)
    if raw is not None:
        return json.loads(raw)
    value = fetch()
    r.setex(key, ttl, json.dumps(value))
    return value

food = cached_json("dietly:barcode:5000159407236", 60 * 60 * 24 * 30,
                   lambda: requests.get(
                       "https://api.getdietly.com/barcode/5000159407236",
                       timeout=10).json())

If your app is a web front end, the browser can carry part of the load too. Barcode and food-id
responses are safe to cache in the client for a day, and doing so removes the network round trip
entirely for a user scrolling back through their own food log. Search is the one to leave uncached in
the browser, because a stale result list is more visible than a stale nutrient panel.

Do not put the key in the browser

Caching pushes people toward calling the API from client code, which is where keys leak. Anything
shipped to a browser or a mobile binary is public, including values in environment variables at build
time. Call the API from your own server, cache there, and let your front end talk to your endpoint. The
public read endpoints work without a key, so a prototype can genuinely run key-free from the browser at
30 requests per minute per IP, and that is a reasonable way to build a demo. Ship it with a key in it
and you have published the key. The key hygiene guide
covers rotation if that has already happened.

The arithmetic that decides your plan

Work in requests per minute at peak, not per month, because the limit is per minute. Suppose a
food-logging app with 2,000 daily active users, each logging six items, and a peak hour carrying a fifth
of the day's traffic. That is 12,000 lookups a day, 2,400 in the peak hour, or 40 per minute: over the
30 per minute free ceiling, so uncached you need a paid plan. Now add a cache. Food logging is
extremely repetitive, so a 90% hit rate is conservative once the cache is warm, and 40 per minute
becomes 4 per minute. The same app fits in the free tier with room to spare, and every cached response
is also faster than the fastest possible network call.

That is the honest version of the advice, so here is the equally honest limit of it. Caching does not
help a workload whose keys are nearly all unique, such as a one-off bulk import of a product catalog
you have never seen before. For that case, pace the import against X-RateLimit-Remaining,
run it once, and store the results in your own database rather than repeatedly asking. If you need
millions of rows, ask about a bulk export instead of crawling the API for a week; that is a cheaper
conversation for everyone.

Measure the hit rate, or you are guessing

Count hits and misses and log the ratio. A hit rate below 50% on a consumer food app almost always
means the cache key is wrong, usually because an unnormalised search string, a per-user prefix or a
timestamp has crept into it. A hit rate above 95% means you can extend TTLs further and stop thinking
about the rate limit at all. Both numbers are cheap to collect and neither is guessable from
first principles.

Common questions

How long should I cache nutrition API responses?

Barcode and food-id lookups for around 30 days, since a barcode maps to one product and reformulations are rare. Search results for one to seven days so improved ranking and coverage reach your users. Never cache a 429 or a 5xx.

Should I cache 404 responses?

Yes, for one to twenty-four hours. A barcode scanner pointed at an unlisted product will otherwise retry on every frame, and each retry is a real request against your rate limit for an answer that will not change.

Can caching keep me on the free tier?

Often. A food-logging app doing 40 lookups per minute at peak exceeds the 30 per minute free limit, but food logging is repetitive enough that a 90% cache hit rate is conservative, which brings it to about 4 per minute.

Can I call the API directly from the browser?

Only without a key. The public read endpoints work anonymously at 30 requests per minute per IP, which is fine for a prototype. Anything shipped to a browser or a mobile binary is public, so a key in client code is a published key.

Every DietlyAPI Error Code Explained, With Handling Recipes

Dietly — Wed, 22 Jul 2026 19:01:43 +0000

Every DietlyAPI error explained, with handling recipes

DietlyAPI returns five error statuses in normal operation: 401, 403, 404,
422 and 429. Four of them carry detail as a string, and 422 carries
detail as a list of objects. That single shape change is the most common cause
of a crash in an otherwise working integration, because a handler written as
err["detail"].lower() works perfectly until the first validation error. This page lists
every status the API produces, the exact body it sends, what causes it, and the handling that belongs
with it. Every example below was run against the live API.

Status	Body	Retry?
`401`	`{"detail": "Missing or invalid API key"}`	No, fix the request
`403`	`{"detail": "This API key is read-only. ..."}`	No, use a different key
`404`	`{"detail": "Barcode not found"}`	No, treat as empty state
`422`	`{"detail": [ {...} ]}`, a list	No, fix the parameters
`429`	`{"detail": "Rate limit exceeded. Retry in N seconds."}`	Yes, after `Retry-After`

401: missing or invalid API key

The API expects a bearer token: Authorization: Bearer YOUR_KEY. You get a 401 when the
header is absent, when the scheme is not Bearer, or when the key does not exist. The body
is deliberately identical in all three cases so the endpoint cannot be used to probe which keys are
real.

$ curl -s https://api.getdietly.com/nope
{"detail":"Missing or invalid API key"}

There is one non-obvious cause worth knowing, and it is the reason that example uses a nonsense
path. Authentication runs before routing, so a URL that does not exist returns 401 rather than
404. If you are certain your key is valid and you are still getting 401, check the path before
you check the key. The classic version of this mistake is inserting a version prefix:
/v1/search returns 401 because there is no /v1 namespace, while
/search works. The public read endpoints (/search, /barcode/{code},
/food/{id}) need no key at all, so a 401 from one of those is nearly always a typo in the
path.

403: the key exists but is not allowed to do this

A 403 means authentication succeeded and authorisation failed. There are two forms, and the message
tells you which.

{"detail":"This API key is read-only. Use a full-access key for this endpoint."}
{"detail":"Use your account key to manage dashboard settings."}

The first appears when a key created with read scope is used for anything that is not a GET. Read
scope is the right default for anything you deploy to a server that only looks data up, and the
restriction is the point rather than a limitation. The second appears when a named access key is used
against /auth/ or /billing/ routes; account management uses the account key,
not the per-service keys. Neither is retryable. Both are configuration mistakes that surface once, at
integration time, and never again.

404: no such record

Direct lookups return 404 when nothing matches: GET /food/{id} for an unknown id, and
GET /barcode/{code} for a barcode with no product. This is an ordinary outcome in a
barcode scanner, not a failure, and it should never surface to a user as an error dialog.

$ curl -s https://api.getdietly.com/barcode/5099999999999
{"detail":"Barcode not found"}

Note the asymmetry with search: GET /search with no matches returns 200
and an empty array [], not a 404. Search answers "what matched", which can legitimately be
nothing; a direct lookup answers "give me this record", which either exists or does not. Handle both,
and treat both as the same empty state in your UI.

422: your parameters did not validate

This is the one that breaks parsers. On 422, detail is a list of validation
objects, each with type, loc, msg and input. Every
other error sends detail as a plain string.

$ curl -s "https://api.getdietly.com/search?q=a"
{"detail":[{"type":"string_too_short","loc":["query","q"],
            "msg":"String should have at least 2 characters",
            "input":"a","ctx":{"min_length":2}}]}

$ curl -s "https://api.getdietly.com/search?q=oats&limit=999"
{"detail":[{"type":"less_than_equal","loc":["query","limit"],
            "msg":"Input should be less than or equal to 50","input":"999"}]}

$ curl -s https://api.getdietly.com/food/abc
{"detail":[{"type":"int_parsing","loc":["path","food_id"],
            "msg":"Input should be a valid integer, unable to parse string as an integer",
            "input":"abc"}]}

The three rules worth encoding in your client: q is required and needs at least two
characters, limit must be between 1 and 50, and a food id must be an integer. Validate
those before you send, because a 422 still costs you a round trip. In particular, do not pass a raw
search box through on every keystroke: a single-character query is guaranteed to 422, so debounce and
require two characters locally.

def describe_error(response):
    # Return a readable message for any DietlyAPI error body.
    try:
        detail = response.json().get("detail")
    except ValueError:
        return f"HTTP {response.status_code}"
    if isinstance(detail, list):                      # 422 validation
        return "; ".join(
            f"{'.'.join(str(p) for p in item.get('loc', []))}: {item.get('msg')}"
            for item in detail
        )
    return str(detail)                                # 401, 403, 404, 429

429: rate limited

The limit is per minute. Anonymous and Starter traffic is capped at 30 requests per minute per IP,
with an additional hourly cap that only a scraper would reach; Pro is 500 per minute and Scale 3,000
per minute, both counted per account rather than per IP. When you exceed it you get a 429 with a
Retry-After header in seconds.

{"detail":"Rate limit exceeded. Retry in 12 seconds."}
Retry-After: 12

Requests made with a key also carry the full trio on both success and 429:
X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.
Anonymous traffic gets Retry-After only. If you are building a dashboard or a bulk sync,
read X-RateLimit-Remaining on every response and slow down before you hit zero rather than
after. That is the difference between a sync that finishes and one that spends its life in backoff.

A retry policy that fits these semantics

Only two of the five statuses are retryable, and one of them tells you exactly how long to wait.
Everything else is a bug in your request that no amount of retrying will fix, which makes the policy
short.

import time
import requests

RETRYABLE = {429, 500, 502, 503, 504}

def request_with_retry(session, method, url, tries=4, **kwargs):
    delay = 1.0
    for attempt in range(tries):
        r = session.request(method, url, timeout=10, **kwargs)
        if r.status_code not in RETRYABLE:
            return r
        if r.status_code == 429:
            wait = float(r.headers.get("Retry-After", delay))
        else:
            wait = delay
            delay *= 2                      # exponential backoff for 5xx only
        if attempt == tries - 1:
            return r
        time.sleep(wait)
    return r

Three details make this behave well in production. Honour Retry-After literally instead
of applying your own backoff on top of it, because the server already knows when the window resets.
Back off exponentially only for 5xx, where you have no information. And never retry 401, 403, 404 or
422: a retry loop on a 422 is an infinite loop that also burns your rate limit.

Deciding what is an error in your own domain

The status code tells you what happened at the transport level. Your application still has to decide
what it means. A useful split is three buckets. Empty results covers 404 on a lookup
and [] from a search, and belongs in the UI as "no match found", with an option to submit
the product. Caller bugs covers 401, 403 and 422, and belongs in your logs and your
tests, never in front of a user. Transient covers 429 and 5xx, and belongs in the retry
path with a visible spinner rather than an error. Fold the first bucket into normal flow and most of
the perceived unreliability of any API disappears.

One more thing worth handling explicitly: nutrients can be null on a perfectly
successful 200. A label that did not declare fibre gives you "fiber_g": null. Treat that
as unknown, never as zero, because rendering a confident 0 g for an undeclared nutrient is a data
error your users will notice and the API will get blamed for.

Before you file a bug

Check the status page first: if the API is degraded, retries are the answer rather than code
changes. Then reproduce with curl and no key against a public read endpoint, because that
removes authentication, your HTTP client and your framework from the picture in one step. If a plain
curl works and your client does not, the difference is in your request, and the response body will
usually name the parameter.

Common questions

Why am I getting a 401 when my API key is valid?

Because authentication runs before routing, so a path that does not exist returns 401 rather than 404. The most common cause is adding a version prefix: /v1/search returns 401 while /search works. The public read endpoints need no key at all.

Why does my error handler crash on 422?

On 422 the detail field is a list of validation objects, while every other DietlyAPI error sends detail as a plain string. Code written as detail.lower() works until the first validation error and then raises.

What are the DietlyAPI rate limits?

Anonymous and Starter traffic gets 30 requests per minute per IP plus an hourly anti-scraping cap. Pro is 500 per minute and Scale 3,000 per minute, both counted per account. Exceeding the limit returns 429 with a Retry-After header in seconds.

Does an empty search return 404?

No. GET /search with no matches returns 200 and an empty array. Only direct lookups, GET /food/{id} and GET /barcode/{code}, return 404 when the record does not exist.

Contract Testing a Nutrition API with Millions of Messy Records

Dietly — Sun, 19 Jul 2026 14:42:09 +0000

Contract testing a nutrition API with millions of messy records

A schema can remain valid while every client still breaks. Changing search from a JSON array to {"results": [...]}, converting null to zero, or renaming carbs_g is enough to break a mobile release that cannot update immediately.

Freeze the consumer-visible shape

An OpenAPI document is necessary, but a small executable fixture catches accidental differences between the document and the running service. Store one representative response and assert keys, types and nullability.

EXPECTED_KEYS = {
    "id", "name", "brand", "barcode", "category",
    "serving_size_g", "serving_desc", "calories_kcal",
    "protein_g", "fat_g", "carbs_g", "fiber_g", "sugar_g",
    "sodium_mg", "source", "confidence", "static_url",
}

def test_food_contract(client):
    food = client.get("/food/1068319").json()
    assert EXPECTED_KEYS <= food.keys()
    assert isinstance(food["id"], int)
    assert food["brand"] is None or isinstance(food["brand"], str)

Test the envelope separately

The most damaging change is often outside the object. Assert that search returns a bare array if that is the published contract, a food lookup returns one object, and a missing ID or barcode returns 404.

def test_endpoint_envelopes(client):
    assert isinstance(client.get("/search?q=yogurt").json(), list)
    assert isinstance(client.get("/food/1068319").json(), dict)
    assert client.get("/barcode/00000000").status_code == 404

Nullability deserves dedicated fixtures

Clean example data hides real failures. Keep fixtures for a complete branded product, a sparse community record, a zero-calorie item, a missing serving size, Unicode text and a duplicate barcode. Verify that unknown nutrients remain null while reported zero stays numeric zero.

Fixture	Regression it catches
Sparse record	Null coerced to zero or field omitted
Water/zero-calorie item	Falsy zero treated as missing
Unicode brand	Encoding and normalization damage
Duplicate barcode	Unstable winner ordering
Missing barcode	Invalid uniqueness assumptions
Large serving	Unit and range mistakes

Separate contract tests from ranking tests

A contract test asks whether clients can parse the response. A ranking test asks whether useful foods appear in the right order. Freeze a set of queries and expected top IDs or relevance bands, but do not make every exact rank immutable: data refreshes legitimately add products.

Probe production read-only

Local tests cannot prove that the deployed reverse proxy, database and serializer agree. Run a small read-only probe after deployment: health, one search, one food ID, one known barcode, one 404 and one rate-limit header check. Never mutate community data during a smoke test.

def test_live_search_contract(session, base):
    r = session.get(f"{base}/search", params={"q": "oat milk", "limit": 2})
    r.raise_for_status()
    assert r.headers["content-type"].startswith("application/json")
    assert len(r.json()) <= 2

Classify changes before shipping

Additive: a new nullable field is usually safe.
Behavioral: ranking or rate-limit changes need release notes and tests.
Breaking: renamed fields, changed types or envelopes require a version or migration window.
Data: corrected values should not require a schema version, but may affect snapshots.

Keep a frozen production-baseline JSON file in the repository and review diffs. That turns “the API probably stayed compatible” into evidence.

Use producer tests and consumer tests together

Producer-side tests verify that the API implementation follows its declared schema. Consumer-driven tests capture assumptions made by real clients: search is an array, a particular header exists, unknown sugar remains null and a 404 body can be parsed. Neither view is sufficient alone. The server may satisfy OpenAPI while changing an undocumented behavior on which every released mobile client depends.

Collect consumer expectations deliberately rather than recording all current behavior forever. Protect the parts required for compatibility, and allow internal implementation details to change. Give each expectation an owner and an explanation so obsolete constraints can be retired safely.

Avoid brittle full-response snapshots

Nutrition values and product names legitimately change as upstream records are corrected. A snapshot of an entire live response will create noisy failures and encourage developers to approve changes without reading them. Assert schema, invariants and a few controlled fixtures instead. When values matter, seed a test database with records owned by the test suite.

Useful invariants include nutrient values being numeric or null, IDs being positive integers, result limits being respected, confidence staying in its documented range and barcode misses returning 404 rather than a fabricated object. Property-based tests can generate combinations of nullable fields and serving sizes that hand-written examples overlook.

Version data contracts independently from deployments

A server can deploy every day while its public contract remains version one. Track contract changes in release notes and compare the generated OpenAPI document to a reviewed baseline in continuous integration. A diff that removes a property, narrows a type or changes required fields should fail until someone classifies it.

When a breaking change is necessary, prefer an explicit endpoint or media-type version and run both contracts during a migration window. Monitor which version clients use before retiring the old one. Announcing a date is not enough if telemetry shows active clients cannot upgrade.

Test operational behavior as part of the contract

Rate-limit responses, authentication failures, cache headers and content types affect integrations as much as JSON fields. Verify that 429 includes a useful Retry-After, that anonymous endpoints remain anonymous if promised, and that privileged keys never appear in logs or error bodies. Confirm that proxies preserve status codes instead of converting every failure into HTML.

Run probes from outside the origin network. An internal health endpoint can be green while DNS, TLS or the CDN is failing for customers. Keep production probes small, read-only and rate-aware, and distinguish origin processing time from customer-visible end-to-end latency.

Make compatibility review part of code review

When a pull request touches response models, serializers, SQL column aliases or middleware, require a contract impact note. Reviewers should see the before-and-after schema and relevant fixture changes. Generated clients can be compiled in CI to expose changes that look harmless in JSON but break a strongly typed language.

The goal is not to prevent evolution. It is to make breaking changes intentional, observable and survivable. A boring stable contract is a product feature when customers build apps that outlive your latest deployment.

Dietly contract: search remains a bare JSON array; nutrient fields retain nullability; ID and barcode lookups return one object or 404. The OpenAPI specification documents the public shape.

Originally published at getdietly.com. Data from the Dietly Nutrition API — 4.7M+ indexed foods, free tier available.

What ODbL Means for Commercial Nutrition Apps

Dietly — Sun, 19 Jul 2026 14:41:48 +0000

What ODbL means for commercial nutrition apps

This is an engineering overview, not legal advice. Database rights and contract questions depend on jurisdiction and architecture. Read the licence and obtain qualified advice for a consequential launch.

The Open Database License permits commercial use. It also attaches conditions to public use, attribution and certain distributions of databases derived from the licensed database. Paying a hosted provider does not automatically remove those upstream obligations.

Separate the database from its contents

ODbL governs rights in the database: its systematic collection, arrangement and substantial extraction or reuse. Individual contents can have separate rights. Open Food Facts states that its database is under ODbL, individual database contents use the Database Contents License, and product images use Creative Commons Attribution-ShareAlike, with possible additional rights in packaging.

This distinction matters. Permission to query a nutrition record does not necessarily grant unrestricted rights to every product photograph or logo returned with it.

Commercial use is allowed

Section 3 of ODbL grants worldwide rights that explicitly include commercial use. “Open” does not mean “non-commercial.” The practical questions are what you publicly display, whether you distribute a database, and whether your transformed collection is a derivative database.

Attribution is the minimum visible duty

If your app publicly displays results derived from Open Food Facts, place a clear attribution where users encounter the data, and link to the source and licence. Do not hide it in a repository that mobile users never see.

Example: “Food data from Open Food Facts, available under the ODbL.”

Keep source metadata in your own objects so attribution can survive caching, exports and UI redesigns.

Produced work, collective database or derivative database?

The licence distinguishes between outputs made from querying a database and a database based on or substantially transformed from the original. A chart, product page or calculated meal summary may be a produced work. A separate database alongside OFF may be collective. A normalized copy containing a substantial part of OFF may be derivative.

Those categories affect notice and share-alike responsibilities. They are also fact-specific. Renaming columns does not necessarily make the underlying database independent, and repeatedly extracting small portions can still become substantial.

Network access is not identical to distributing a copy

ODbL defines “convey” around enabling another person to receive a copy of the database or derivative database, and notes that mere interaction through a network is not itself conveying. That does not eliminate public-use attribution or every possible share-alike question; it simply means an API and a downloadable database are not automatically the same act.

Build compliance into the data model

Store source and source record identifiers.
Keep a licence registry rather than one global licence string.
Render attribution near public data.
Track whether images have separate terms.
Document imports, transformations and exports.
Review bulk-download and customer-export features separately.
Do not promise customers that a commercial API subscription transfers ownership of upstream data.

Questions to answer before launch

Are we displaying individual results or distributing a substantial database?
Do customers receive exports or only interact with an API?
Did we combine OFF with proprietary records, and can provenance be separated?
Are we redistributing product images?
Where will users see attribution?
Who owns modifications and who must receive corresponding database access?

Start with the actual ODbL 1.0 text and Open Food Facts reuse guidance. Contact Open Food Facts about its data when guidance is unclear, and seek legal advice for your particular distribution model.

Dietly position: DietlyAPI is built primarily on Open Food Facts. Paid plans provide access to Dietly's hosted normalization, indexing, ranking and support; they do not cancel ODbL duties that apply upstream.

A commercial subscription and a data licence solve different problems

A hosted provider can charge for infrastructure, normalization, support, service limits and contractual permission to use its API commercially. That commercial agreement can coexist with an open licence on upstream data. The invoice does not prove that the provider owns every underlying fact, and the open licence does not require the provider to operate servers for free.

Review both layers: the provider's service terms and each upstream licence relevant to the returned data. They can impose different duties. Service terms may limit credentials, caching or throughput; ODbL addresses database rights, attribution and share-alike. Product images, brand assets and user-contributed text may introduce still other terms.

Attribution should survive every surface

List all places where data appears: web pages, native apps, PDFs, exports, widgets, email reports and public API responses. Decide where the attribution notice belongs on each surface and how a user can reach the licence. A single footer on the marketing website may not inform someone viewing an embedded result inside a customer application.

Automate attribution where possible. If the API returns source metadata, map it to a maintained notice rather than hard-coding a sentence in several clients. Include source and licence information in exports so downstream users do not accidentally strip provenance. Test attribution as part of release QA, just like privacy links and billing disclosures.

Think carefully before offering bulk exports

An interactive application that shows individual query results differs operationally and legally from a feature that lets customers download millions of normalized records. Bulk export can cross from using produced works into conveying a database or derivative database. It also changes the security, privacy and infrastructure profile of the product.

Before adding export, document which records are included, which sources they came from, what transformations were applied and which notices accompany the file. Decide how recipients can obtain any corresponding database that must be offered under applicable share-alike terms. This is the point where qualified advice is especially valuable.

Do not confuse facts with protected content

A calorie number may be a factual value, while a product photograph, label artwork or long description can carry copyright or trademark concerns independent of database rights. Preserve separate image metadata and avoid assuming the database licence covers the image. Open Food Facts explicitly calls out its image licence separately.

Logos and brand names may be necessary to identify products, but their presence does not imply sponsorship. Use them accurately, avoid misleading endorsement and review marketplace policies where an app store or advertising platform imposes additional rules.

Keep a small compliance record

Maintain a short architecture note naming sources, licences, import paths, transformations, public surfaces, attribution text and owners. Update it when adding another dataset or export feature. This record helps engineers avoid accidental regressions and gives counsel a concrete system to review instead of an abstract question about “using food data.”

Compliance is easier when provenance is designed in from the first table. Reconstructing it after records have been merged, cached and redistributed is expensive and sometimes impossible.

Originally published at getdietly.com. Data from the Dietly Nutrition API — 4.7M+ indexed foods, free tier available.

Building Reliable Barcode Lookup for a Nutrition App

Dietly — Sun, 19 Jul 2026 14:41:35 +0000

Building reliable barcode lookup for a nutrition app

A successful scan is not the same thing as a successful product lookup. The camera may decode a valid GTIN that your database has never seen, or multiple source rows may share the identifier. Treat “not found” and ambiguity as normal product states.

Keep identifiers as strings

UPC, EAN and GTIN values are identifiers, not quantities. Store them as text so leading zeroes survive serialization and spreadsheet imports. GS1 notes that applications using a uniform 14-digit GTIN format add leading zeroes to shorter forms.

function cleanBarcode(raw) {
  return raw.replace(/[^0-9]/g, "");
}

const code = cleanBarcode(scannerValue);
if (![8, 12, 13, 14].includes(code.length)) {
  showError("That does not look like a supported GTIN");
}

Decide whether your API stores the scanned representation or canonical GTIN-14. If you normalize, do it during both ingestion and lookup, and preserve the original value for debugging.

Validate the check digit before calling the API

A scanner library can still return truncated input or a manually entered typo. GTIN uses a modulo-10 check digit with alternating weights. Rejecting an invalid code saves a network request and gives a faster explanation.

function validGtin(code) {
  if (!/^\d{8}$|^\d{12,14}$/.test(code)) return false;
  const digits = [...code].map(Number);
  const check = digits.pop();
  const sum = digits.reverse().reduce(
    (total, digit, i) => total + digit * (i % 2 === 0 ? 3 : 1), 0);
  return (10 - (sum % 10)) % 10 === check;
}

Use an exact index, never fuzzy barcode matching

Names benefit from fuzzy search. Barcodes do not. A one-digit difference identifies another item or an invalid code. Put a B-tree index on the canonical barcode column and use equality.

CREATE INDEX CONCURRENTLY foods_barcode_idx ON foods (barcode);

SELECT id, name, brand, confidence
FROM foods
WHERE barcode = $1;

Resolve duplicates deterministically

Multiple source records can share a barcode because of imports, translations or packaging updates. Dietly prefers a row with an image, then higher internal confidence, then the lowest stable ID. Your exact signals may differ, but the order must be explicit and stable.

ORDER BY
  (image_url IS NOT NULL) DESC,
  confidence DESC NULLS LAST,
  id ASC
LIMIT 1;

For high-stakes workflows, return several candidates or source metadata instead of silently selecting one. A calorie tracker can usually show one best record plus an “incorrect product?” action.

A 404 is a user journey

When the API returns no match, offer text search, manual nutrition entry and, when your data source supports it, a contribution flow. Do not generate nutrition values merely because a barcode exists.

const response = await fetch(`${API}/barcode/${code}`);
if (response.status === 404) {
  showNoMatch({ actions: ["Search by name", "Enter label manually"] });
  return;
}
if (!response.ok) throw new Error("Lookup temporarily unavailable");
showProduct(await response.json());

Measure the right things

Scanner decode success
Valid-GTIN rate
Database hit rate by country and device locale
Duplicate rate and winner changes
User corrections after a successful match
Latency from scan to rendered product

Do not market a universal barcode coverage percentage unless you have a representative, reproducible test set.

Normalize symbologies without erasing meaning

A camera SDK may report UPC-A, EAN-13 or another symbology separately from the digits. Capture both. A 12-digit UPC can be represented as a 13-digit EAN with a leading zero, and GTIN systems may pad to 14 digits, but arbitrary padding is not a substitute for a documented canonicalization rule. Apply the same rule when importing suppliers, reading CSV files and serving API requests.

Be careful with spreadsheet tooling. It may remove leading zeroes or display a long identifier in scientific notation. Validate imports before they reach the production table and keep rejected rows with reasons. Treating a barcode as an integer also makes JSON clients vulnerable to language-specific numeric limits. A string avoids all of these problems.

Separate scan errors from catalog misses

Users need different messages for an unreadable image, an invalid check digit, a valid but unsupported code type, a valid GTIN absent from the catalog and a temporary server failure. Combining them into “product not found” sends people toward the wrong remedy. Let them rescan when decoding failed, correct digits when validation failed, search by name for a catalog miss and retry later for a network error.

Mobile cameras often decode the same barcode repeatedly while the product remains in frame. Debounce identical scan events and cancel in-flight duplicates. Lock the result screen only after a valid response or deliberate no-match state. This avoids flicker and prevents one physical scan from consuming many API requests.

Cache hits and misses differently

A successful product lookup can usually be cached because labels change less frequently than users revisit them. A miss should receive a shorter negative cache: the catalog may add that barcode in the next import or after a community contribution. Include the normalized identifier and relevant dataset edition in the cache key. Invalidate or version cached records when your response contract changes.

For offline-first apps, store the product together with source and retrieval time. Make it clear when the result is cached, especially if users rely on recently changed allergens or formulations. The physical package remains the authoritative source for immediate safety decisions.

Duplicate handling needs observability

Record how often an exact barcode returns multiple rows, which tie-breaker selected the winner and whether users reject that choice. A rising duplicate rate may indicate an ingestion regression. If the winner changes after a refresh, compare the old and new source, serving and nutrient values before assuming the higher confidence record is better.

Do not deduplicate solely on a shared name or barcode without considering market and lifecycle information. Manufacturers sometimes reuse packaging conventions, databases contain historic records, and regional versions can differ. Deterministic ranking provides a safe default while preserving the underlying rows for review.

Test with a representative barcode set

Build a dated test pack covering the countries and retailers your users actually scan. Include known hits, known misses, damaged labels, short GTINs, leading-zero cases and duplicated records. Publish the methodology if you make coverage claims. A random sample from your own database measures whether you can rediscover records you already possess; it does not measure real-world barcode coverage.

Run the set through the full mobile path, not only the database query. Camera focus, lighting, orientation, network latency and result rendering all contribute to the experience. The lookup SQL can be instantaneous while the feature still feels unreliable.

Try it: GET https://api.getdietly.com/barcode/{code} performs indexed EAN/UPC lookup and returns one normalized food object or a normal 404 miss.

Identifier reference: GS1 identification keys.

Originally published at getdietly.com. Data from the Dietly Nutrition API — 4.7M+ indexed foods, free tier available.