🔑

Getting Your API Keys

A step-by-step guide to the three data services The Receipts uses. All of them are free.

What is an API key? It's like a password that lets The Receipts talk to an outside service on your behalf. Each service issues you your own key when you sign up.

The Receipts uses up to three services: USDA FoodData Central for nutrition data, Open Food Facts for product lookups (no key needed!), and Google Gemini for reading your receipt photos.

🔒 Prefer to keep everything on your own machine? You don't need a key to read receipt photos. The Receipts can run a local vision model instead, so your receipts never leave your computer — and it's free.

Set OCR_BACKEND in your .env to one of:

local — the default. A vision model such as LLaVA or Qwen2.5-VL via Ollama or LM Studio. Point OCR_BACKEND_URL at it.
gemini — Google's hosted model. Fastest and most accurate; needs the key below.
openrouter — your own OpenRouter account.

Digital PDF invoices (Whole Foods, Amazon Fresh) are parsed directly and need no vision model at all, whichever backend you pick.

✨

Google Gemini

The AI that reads your receipt photos and helps categorize items.

You'll need a regular (free) Google account — the same kind used for Gmail.
Go to Google AI Studio and sign in.
Click Get API key (top left), then Create API key.
A key beginning with AIza… is generated. Click the copy icon and save it somewhere safe.

💡 Gemini has a free tier that is plenty for scanning household receipts.

⚠️ Treat this key like a password — anyone who has it can use AI services billed to your Google account if you later enable paid usage.

🔬

USDA FoodData Central

Powers nutrition facts (calories, protein, sodium…) for your grocery items.

Open the signup page: fdc.nal.usda.gov/api-key-signup
Enter your first name, last name, and email address. That's all — no credit card, no account password.
Click Signup. Your key appears on screen and is also emailed to you. It looks like a long string of random letters and numbers.
Copy the key and save it somewhere safe (you'll paste it into your .env file — see below).

💡 The free key allows 1,000 requests per hour — far more than The Receipts will ever need for a household.

🥫

Open Food Facts

A free, community-run product database used for barcode and product lookups.

✅ Good news — no API key needed. Open Food Facts is an open database, free for everyone to read. The Receipts simply identifies itself politely when it asks for data, and that's it. There is nothing for you to sign up for or configure.

If you'd ever like to contribute product data back to the community (photos, corrections), you can create a free account at world.openfoodfacts.org — but The Receipts doesn't require it.

📄

Where do the keys go?

Both keys live in a plain-text file called .env in the project's root folder.

Open (or create) the .env file next to grocery.db and add one line per key:

FDC_API_KEY=paste-your-usda-key-here
GEMINI_API_KEY=paste-your-gemini-key-here

No quotes, no spaces around the = sign.
Restart the app after editing the file — keys are read at startup.
Never share this file or commit it to version control. It's your keys' home, and it should stay private.

⚙️

Back to Settings

Return to exclusions, rules, and data management.

←