Alcoholic beverage manufacturers, importers, and compliance analysts routinely monitor federal approval records to track competitor SKU rollouts, verify permit validity, and conduct market analysis. The US Treasury Department's Alcohol and Tobacco Tax and Trade Bureau (TTB) mandates that every beer, wine, and distilled spirit sold in the United States hold an approved Certificate of Label Approval (COLA). While the public COLA registry at ttbonline.gov exposes these records, collecting them programmatically requires navigating session constraints, mandatory search filters, and strict server pagination limits.
Programmatic COLA Registry Extraction
The TTB COLA Registry Scraper interfaces directly with the TTB public registry endpoint over HTTP without browser automation overhead. It supports two operating modes determined by the mode parameter: search for querying broad categories or producer permits, and byTtbId for fetching known 14-digit COLA identifiers directly.
When querying via search mode, TTB forces a mandatory "Date Completed" window. The TTB backend rejects queries without a completed date range or queries spanning longer than 15 years. The scraper accepts dateCompletedFrom and dateCompletedTo formatted as MM/DD/YYYY strings.
To isolate target segments, specific input parameters narrow extraction results:
-
permitId: Restricts output to a specific producer's basic permit or plant registry number (for example,DSP-CO-20073). -
classTypeCode: Filters by exact 3-digit TTB class and type codes (such as101for Straight Bourbon Whisky). Setting this overrides broaderproductCategorymappings. -
originCode: Filters by state or country of origin. -
includeApplicantDetails: Toggles secondary requests to retrieve formula details, applicant addresses, contact names, and compliance qualifications. -
includeLabelImages: Directs the scraper to fetch approved artwork files and re-host them on key-value storage so they remain reachable past ephemeral TTB session timeouts.
Bypassing the 1,000-Record Server Truncation
TTB's public registry enforces a hard limit of 1,000 records per search result window, paginated in chunks of 20 records. If a search query matches 4,000 approved COLAs within a given date span, the backend server truncates the result list, making items past record 1,000 unreachable under that specific query structure.
To circumvent this platform ceiling, payload design must segment broad categories into sub-1,000 chunks. Rather than querying a full five-year window for a broad category, divide the target period into smaller time windows using dateCompletedFrom and dateCompletedTo, or combine date spans with specific originCode values.
Below is a payload configuration targeting a specific producer permit over a two-year window, capturing applicant metadata and re-hosted label artwork:
{
"mode": "search",
"permitId": "DSP-CO-20073",
"dateCompletedFrom": "01/01/2023",
"dateCompletedTo": "12/31/2024",
"includeApplicantDetails": true,
"includeLabelImages": true,
"maxItems": 500
}
Executing Extractor Runs via Python
Integrating this workflow into data pipelines requires sending input configurations to the API and processing the resulting dataset records. Each returned record contains 14-digit COLA identifiers (ttbId), class/type descriptions (classTypeDescription), approval status (status), applicant information (applicantName, applicantAddress), and structured label image metadata (labelImages).
The following Python script uses apify-client to execute a search query for approved bourbon labels and prints the extracted COLA details along with re-hosted image URLs:
from apify_client import ApifyClient
client = ApifyClient("YOUR_API_KEY")
run_input = {
"mode": "search",
"productOrFancifulName": "bourbon",
"productNameSearchType": "E",
"dateCompletedFrom": "01/01/2024",
"dateCompletedTo": "12/31/2024",
"includeApplicantDetails": True,
"includeLabelImages": True,
"maxItems": 50
}
run = client.actor("crawlerbros/ttb-cola-registry-scraper").call(run_input=run_input)
dataset = client.dataset(run["defaultDatasetId"])
for item in dataset.iterate_items():
print(f"TTB ID: {item.get('ttbId')}")
print(f"Brand: {item.get('brandName')} | Fanciful: {item.get('fancifulName')}")
print(f"Applicant: {item.get('applicantName')}")
print(f"Status: {item.get('status')}")
images = item.get("labelImages", [])
for img in images:
print(f" Label Image ({img.get('imageType')}): {img.get('imageUrl')}")
print("-" * 40)
How to Set Up a Registry Extraction Pipeline
- Define your extraction scope by selecting either direct COLA lookup (
mode: "byTtbId") or query criteria (mode: "search"). - Set
dateCompletedFromanddateCompletedToto enforce a date window under 15 years, ensuring expected match volume remains under 1,000 items. - Add specific filters like
permitId,classTypeCode, ororiginCodeto isolate relevant approvals. - Set
includeApplicantDetailsandincludeLabelImagestotrueif compliance addresses, formulas, or image storage are required for downstream ingestion. - Execute the run programmatically or via API and extract JSON records from the default dataset.
Billing Model and Operational Boundaries
Running this actor is billed under a pay-per-event pricing structure, with the platform usage of each run billed separately:
-
Actor Start (
apify-actor-start): Charged at $0.005 per GB of memory allocated to the run upon execution. -
Result Output (
apify-default-dataset-item): Charged at $0.005 per event for each result written to the default dataset.
Discount-tier prices apply to result output events: FREE at $0.005, BRONZE at $0.00433, SILVER at $0.00367, and GOLD, PLATINUM, or DIAMOND at $0.003 per event. Disabling includeApplicantDetails or includeLabelImages reduces secondary HTTP requests per record, accelerating run duration (and lowering the run's platform usage) without altering the base per-item result price.
This extraction approach has distinct operational limits. TTB's public backend truncates any single search query result window to 1,000 records regardless of client configuration, making date-slicing necessary for large-scale market ingestions. Furthermore, older historical COLA filings or administrative filings on ttbonline.gov sometimes lack uploaded label image files at the source, yielding an empty labelImages list for those specific records.
TTB COLA Registry Scraper is the Actor behind these examples. If a selector in your own version breaks, compare your output against the fields listed in its README first.
Prices quoted above are this Actor's published pay-per-event rates on the Apify Store, read from the Apify platform API on 2026-09-11. Check the Actor page for the current rates.
Top comments (0)