Skip to main content

​
Installation

pip install colacloud
Requires Python 3.9+.

​
Quick Start

from colacloud import ColaCloud

client = ColaCloud(api_key="cola_xxxx")

# Search COLAs
results = client.colas.list(
    q="Tito's",
    product_type="distilled spirits",
    abv_min=35,
    per_page=10
)

for cola in results.data:
    print(f"{cola.brand_name} - {cola.product_name}")

# Get a specific COLA with images and barcodes
cola = client.colas.get("24001001000001")
print(cola.images[0].image_url)

# Barcode lookup
matches = client.barcode.lookup("012345678901")
print(f"Found {matches.total_colas} COLAs")

​
Filtering

The COLA list endpoint supports generic text search plus structured filters for TTB product type, derived category/subcategory, ABV, package size, container type, permit number, and barcode. 
results = client.colas.list(
    q="molson coors",
    category="Beer",
    derived_subcategory="Beer > Ale",
    container_type="can",
    volume_unit="fluid ounces",
    volume_min=12,
    volume_max=16,
)
Use q when you are not sure whether a word belongs to a brand, product, permit, or applicant/company name.

​
Auto-Pagination

Iterate through all matching results without managing pages: 
for cola in client.colas.iterate(q="bourbon"):
    print(f"{cola.ttb_id}: {cola.brand_name}")

for permittee in client.permittees.iterate(state="CA"):
    print(f"{permittee.company_name}: {permittee.colas} COLAs")

​
Permittees

# Search permittees
results = client.permittees.list(state="NY", is_active=True)
for p in results.data:
    print(f"{p.company_name} ({p.permit_number})")

# Get a single permittee with recent COLAs
permittee = client.permittees.get("NY-I-12345")
print(f"Recent COLAs: {len(permittee.recent_colas)}")

​
Usage Stats

usage = client.get_usage()
print(f"Detail views: {usage.detail_views.used} / {usage.detail_views.limit}")
print(f"List records: {usage.list_records.used} / {usage.list_records.limit}")

​
Async Support

import asyncio
from colacloud import AsyncColaCloud

async def main():
    client = AsyncColaCloud(api_key="cola_xxxx")
    results = await client.colas.list(brand_name="Maker's Mark")
    print(f"Found {results.pagination.total} results")

    # Async iteration
    async for cola in client.colas.iterate(q="bourbon"):
        print(cola.brand_name)

asyncio.run(main())

​
Authentication

Pass your API key directly to the client: 
client = ColaCloud(api_key="cola_xxxx")