US Wine Reference API

The reference data a US wine label points at — permit holders, appellations, grape varieties and TTB codes — as clean JSON. Free, no key, public domain.

What this is

Four public datasets that a US wine label depends on, normalised into one API. Who holds the federal permit. Which appellation, and what sits inside it. Which grape names may legally appear on a label, including the ones that only show up on older bottles. What TTB's class/type and origin codes actually mean.

All of it is published by TTB and the Code of Federal Regulations, and all of it is awkward to use: a weekly FOIA file, an ArcGIS service, prose inside 27 CFR part 4, and two code tables that exist only behind a legacy lookup screen. The work here is the normalising, the decoding, the nesting and the name resolution — not the download.

Live lookup

Real requests against the live API, from your browser. No key.

Call the API

No key. No signup.

# Who holds this TTB permit?
curl https://apis.allanninal.dev/wine/v1/producers/CA-I-4310

# Which AVAs sit inside Napa Valley?
curl "https://apis.allanninal.dev/wine/v1/appellations?within=Napa%20Valley"

# What is "Napa Gamay" actually called?  -> Valdiguié
curl "https://apis.allanninal.dev/wine/v1/varieties?q=napa%20gamay"

# Decode a class/type code (case-sensitive!)
curl https://apis.allanninal.dev/wine/v1/class-types/80

# What changed since last week?
curl "https://apis.allanninal.dev/wine/v1/changes?dataset=producers&since=2026-09-18"

Endpoints

Full contract: openapi.yaml · agent index: llms.txt

Reference data (static, free, no auth)

The complete datasets as plain files. Cacheable, no key, and the same data the API serves — nothing is held back for a paid plan. Add ?asOf= on the API if you want a past state instead.

The data, and where it comes from

Every dataset is CC0 or a US federal government work. No share-alike, no non-commercial clause, no attribution obligation — you may redistribute this data, including in a commercial product. The clearance register, including what was deliberately excluded and why, is on the data licence page.

History nobody else keeps

TTB overwrites its permittee file in place and keeps no archive. The previous version is simply gone — the Internet Archive holds two accidental captures, eight months apart. So a time series of who was licensed to make wine in America does not exist anywhere, and cannot be reconstructed after the fact.

This service takes a snapshot on every refresh and keeps it. That makes ?asOf= and /v1/changes possible, and it is the one thing here that is genuinely created rather than republished.

# Every producer as the registry stood on a past date
curl "https://apis.allanninal.dev/wine/v1/producers?asOf=2026-09-19"

# Added, amended and removed since then
curl "https://apis.allanninal.dev/wine/v1/changes?dataset=producers&since=2026-09-19"

Ask for a date before retention began and you get a 422 naming the coverage start — never current data dressed as history. See the real window.

Three things worth knowing

Alcohol by volume is not in the data

A COLA record carries no ABV field. ABV appears only as printed text on the label image. So this API returns a derived regulatory band from the class/type code under 27 CFR 4.21 — table wine 7–14%, dessert 14–24% — marked "derived": true with the basis spelled out in the payload. It is never presented as a measurement of any particular wine.

No applicant contact details, ever

TTB's COLA detail pages carry an applicant contact name, phone number, and for sole proprietors a home address — a one-person winery's premises is their residence. None of that is served here. Business name, city, state and county are what a lookup needs.

A bonded-winery number will never resolve

Labels cite two permit shapes. Importer permits (CA-I-4310) resolve. Bonded winery registry numbers (BWN-TX-21850) do not, and never will: IRC §6103 bars TTB from publishing bonded-cellar lists. The 404 says exactly that instead of leaving you to guess.

Access & rate limits

Every plan has every feature. Plans differ only in how much you may use, never in what you may reach — nothing is behind a paywall. Limits are published on every response as RateLimit-*. The price, and how it compares to the competition.

Free for public-interest work

This is public data about a regulated industry. The people most likely to do something useful with it are the least likely to have a budget for an API, and charging them would select against exactly the use this data exists for. The rate limits protect one small shared server; they are not there to ration public records.

How to ask: message me on LinkedIn with who you are and roughly what you are looking into. One or two sentences is enough. No proposal, no procurement, no annual review. LinkedIn rather than email purely so I can see I am talking to a real person.

Versioning

/v1/ changes only on a breaking change, and a version gets at least 12 months of support with 6 months' notice before sunset. Dataset versions move independently and are never breaking on their own — every response carries datasetVersions so you can pin, cache and reproduce a result. The full algorithm.

FAQ

Do I need a key?

No. Every read path is anonymous. A free key only raises your budget; it unlocks nothing.

Can I use this commercially?

Yes, including redistributing the data. Everything served is CC0 or a US federal government work: no share-alike, no non-commercial clause, no attribution required.

Why isn't the label data here?

The TTB Public COLA Registry publishes no bulk feed and no API, and this service does not scrape it. That is a deliberate scope decision, not a gap waiting to be filled.

How fresh is it?

Permits, appellations and varieties are re-fetched daily; TTB itself republishes the permittee file about weekly. Every response carries datasetVersions, and /healthz reports what is loaded right now.

Can I query what the data looked like in the past?

Yes. TTB overwrites its files and keeps no archive, so this service retains a snapshot on every refresh. Use ?asOf= for a past state and /v1/changes for what was added, amended or removed since a date.

Is alcohol by volume included?

No. A COLA record carries no ABV field; it appears only as printed text on the label image. The API returns a regulatory alcohol band derived from the TTB class/type code under 27 CFR 4.21, explicitly marked as derived — never as a measurement.

What does it cost?

The free tier needs no signup: 60 requests a minute, 5,000 a day. Pro is $19/month and Business $49/month. Journalists, academics, nonprofits and public-interest researchers get Pro-level access free by application.

What if I need more than the limits allow?

Don't buy a plan — self-host. The complete datasets are published above and the server is MIT licensed. A rate limit is a property of my hardware, not of the data.

Something here is wrong. Who do I tell?

Message me on LinkedIn. Data errors, security issues and personal-information concerns are all welcome — see the disclaimer.