TTB COLA Registry Scraper

Scrape the TTB COLA Registry — the US Treasury Department's Alcohol and Tobacco Tax and Trade Bureau (TTB) public database of Certificates of Label Approval (COLA) for beer, wine, and distilled spirits sold in the United States. Search by brand/fanciful name, beverage category, TTB class/type code, origin (US state or country), permit number, or date range — or fetch specific records directly by TTB ID. Every record includes the applicant's name and address, approval status, and the actual approved label image(s). HTTP-only against the public ttbonline.gov registry. No auth, no proxy, no login.

What this actor does

• Two modes: search (query the registry) and byTtbId (direct lookup of known COLAs)
• Rich filters: product/brand name, beverage category, exact TTB class/type code, origin (233 US states + countries), permit number, vendor code, TTB ID range, serial number range, approval status, date-completed range
• Applicant & compliance data: approval status, formula, qualifications, applicant name/address, contact name/phone
• Real label images: the actual approved label artwork, re-hosted so it's accessible without a TTB session
• Empty fields are omitted

Output per COLA record

• ttbId — 14-digit TTB identifier for the Certificate of Label Approval
• permitId — producer's plant registry / basic permit / brewer's number
• serialNumber — applicant's internal serial number for this application
• dateCompleted, approvalDate, expirationDate
• status — APPROVED, DENIED, or SURRENDERED/REVOKED
• brandName, fancifulName
• classTypeCode, classTypeDescription — TTB's beverage class/type (e.g. 141 / BOURBON WHISKY)
• originCode, originDescription — US state or country of origin
• vendorCode
• typeOfApplication — e.g. LABEL APPROVAL, CERTIFICATE OF EXEMPTION
• forSaleIn, totalBottleCapacity, formula
• qualifications — TTB's compliance notes on the approval
• applicantName, applicantAddress, contactName, contactPhone
• labelImages[] — { imageUrl, imageUrlOriginal, imageType } for each approved label image (front, back, neck, keg collar, etc.)
• sourceUrl — the public COLA detail page on ttbonline.gov
• recordType: "cola", scrapedAt

Input

Field	Type	Default	Description
mode	string	search	search / byTtbId
productOrFancifulName	string	whiskey	Free-text match on brand/fanciful name (mode=search)
productNameSearchType	string	E	Match productOrFancifulName against brand only (B), fanciful only (F), or either (E)
dateCompletedFrom / dateCompletedTo	string	01/01/2015 / 12/31/2024	Date-completed range, MM/DD/YYYY, max 15-year span (required by TTB for any non-ID search)
productCategory	string	–	Curated beverage category (whisky, gin, vodka, rum, brandy, wine, beer, etc.)
classTypeCode	string	–	Exact 3-digit TTB class/type code; overrides productCategory
originCode	string	–	US state or country code
permitId	string	–	Producer's plant registry / basic permit number
vendorCode	string	–	TTB vendor code
ttbIdFrom / ttbIdTo	string	–	TTB ID range
serialNumFrom / serialNumTo	string	–	Applicant serial number range
statusFilter	string	–	Only emit APPROVED / DENIED / SURRENDERED/REVOKED
ttbIds	array	–	TTB IDs to fetch directly (mode=byTtbId)
includeApplicantDetails	bool	true	Fetch status, applicant, contact, formula, qualifications
includeLabelImages	bool	true	Fetch and re-host approved label images
maxItems	int	20	Hard cap (1–1000; TTB's own search window shows at most 1000 matches)

Example: search by brand/fanciful name

{
  "mode": "search",
  "productOrFancifulName": "bourbon",
  "dateCompletedFrom": "01/01/2023",
  "dateCompletedTo": "12/31/2024",
  "maxItems": 50
}

Example: browse a category by state of origin

{
  "mode": "search",
  "productOrFancifulName": "",
  "productCategory": "WHISKY",
  "originCode": "13",
  "dateCompletedFrom": "01/01/2024",
  "dateCompletedTo": "12/31/2024",
  "maxItems": 100
}

Example: track a producer's approvals by permit number

{
  "mode": "search",
  "productOrFancifulName": "",
  "permitId": "DSP-CO-20073",
  "dateCompletedFrom": "01/01/2020",
  "dateCompletedTo": "12/31/2024",
  "maxItems": 200
}

Example: direct lookup by TTB ID

{
  "mode": "byTtbId",
  "ttbIds": ["24159001000118", "17009001000001"]
}

Use cases

• Label compliance teams — check whether a competitor's or your own label has an active COLA before shipping
• Competitive intelligence — monitor new label approvals from a specific producer or permit number
• New-product tracking — spot new SKUs (fanciful names, flavors, formats) as soon as they're approved
• Market research — analyze approval volume by beverage category, state, or country of origin over time
• Import/export due diligence — verify a foreign producer's US label approval status and formula
• Distributor onboarding — pull applicant name, address, and permit details for a new supplier

FAQ

What is the TTB COLA Registry? It's the US Alcohol and Tobacco Tax and Trade Bureau's public database of Certificates of Label Approval (COLA) — the federal approval required before a beer, wine, or spirits label can be sold in the United States. It's a public, no-login registry at ttbonline.gov.

Is this actor affiliated with TTB? No — this is an independent, third-party actor built on TTB's public search interface. It is not affiliated with or endorsed by the Alcohol and Tobacco Tax and Trade Bureau.

Why does my search need a date range? TTB's own search form requires a "Date Completed" range for every query except a direct TTB ID lookup, and rejects any span longer than 15 years. The actor validates and auto-clamps oversized ranges so your run doesn't fail.

What's the difference between productCategory and classTypeCode? productCategory is a curated shortcut (e.g. WHISKY) mapped to the right TTB class/type code range. classTypeCode is the exact 3-digit TTB code (e.g. 141 = Bourbon Whisky) for users who need a single, precise category. Setting classTypeCode overrides productCategory.

How many results can one search return? TTB's own results window shows at most 1000 matching records per query (paginated 20 at a time), even if more technically match. Narrow your date range, category, or origin to stay under that cap.

Why are some labelImages missing for a record? Not every COLA has an image on file (e.g. some administrative or older filings), and a small number of image fetches can fail transiently. Missing images are simply omitted rather than emitting broken URLs.

How fresh is the data? TTB updates the registry as label applications are processed — typically within days of a decision. The actor always queries live.

Can I fetch applicant/contact details without label images (or vice versa)? Yes — includeApplicantDetails and includeLabelImages are independent toggles. Turning either off skips its extra request per record, which speeds up large runs.