Metadata-Version: 2.1
Name: cookielessaudiences
Version: 1.0.0
Summary: Python client for the Cookieless Audiences API: page-level audience segmentation (demographics, interests, purchase intent, B2B firmographics, personas) and IAB content categorization for any URL, with no cookies and no PII.
Home-page: https://www.cookielessaudiences.com
Author: Alpha Quantum
Author-email: info@alpha-quantum.com
License: MIT
Project-URL: Homepage, https://www.cookielessaudiences.com
Project-URL: Documentation, https://www.cookielessaudiences.com/api.php
Project-URL: Source, https://github.com/explainableaixai/cookielessaudiences
Project-URL: Mirror, https://gitlab.com/url-classifications/cookielessaudiences
Project-URL: Tracker, https://www.cookielessaudiences.com/contact.php
Project-URL: Pricing, https://www.cookielessaudiences.com/pricing.php
Description: # cookielessaudiences (Python)
        
        Cookieless audience data for a URL, as a Python call. You pass a page and receive demographics, interests, purchase intent, B2B firmographics and personas, with no cookies and no personal data involved.
        
        Built on `requests`, works on Python 3.7 and later.
        
        ## Setup
        
        ```bash
        pip install cookielessaudiences
        ```
        
        An API key comes with any plan. If you are still comparing options, read how [cookieless audience segmentation](https://www.cookielessaudiences.com/features/cookieless-audience-segmentation.php) works before you buy.
        
        ## Quick start
        
        ```python
        from cookielessaudiences import CookielessAudiences, labels_for
        
        client = CookielessAudiences("YOUR_API_KEY")
        result = client.segment("https://example.com/blog")
        
        print(result["audience_type"])
        print(result["demographics"]["income_level"])
        print(labels_for(result))
        ```
        
        ## Reading the response
        
        Think of the structured result as five questions about the reader of a page:
        
        1. Who are they? `demographics` and `b2b`
        2. What do they like? `interests`, two tiers of `INT.*` codes
        3. What might they buy? `purchase_intent`, `PI.*` codes
        4. Which named audiences fit? `personas`
        5. What kind of page is it? `content_context`
        
        `labels_for(result)` turns the codes in questions 2 and 3 into names you can show to a person.
        
        ## API surface
        
        ```python
        client.segment(url, structured=True)
        client.categorize(url, confidence=True, root_fallback=False)
        client.categorize_text(text, confidence=True)
        client.segment_many(urls, workers=8)
        CookielessAudiences.vocabularies()
        ```
        
        `segment_many` returns a dict of url to result. A URL that failed holds its exception instead, so one bad page never stops a batch.
        
        ## Errors
        
        ```python
        from cookielessaudiences import CookielessAudiencesError
        
        try:
            client.segment(url)
        except CookielessAudiencesError as exc:
            print(exc.status, exc.body)
        ```
        
        The HTTP layer is plain; the signal lives in `status` inside the JSON. 401 is a bad key, 403 means the key is inactive or credits are gone, 410 and 411 mean the page could not be read.
        
        ## Example: audience report for a media plan
        
        ```python
        import csv
        from cookielessaudiences import CookielessAudiences, labels_for
        
        client = CookielessAudiences("YOUR_API_KEY")
        sites = [line.strip() for line in open("sites.txt") if line.strip()]
        results = client.segment_many(sites, workers=10)
        
        with open("plan.csv", "w", newline="") as fh:
            out = csv.writer(fh)
            out.writerow(["site", "type", "age", "income", "top_interest", "top_intent"])
            for site, res in results.items():
                if isinstance(res, Exception):
                    out.writerow([site, "error", "", "", "", ""])
                    continue
                names = labels_for(res)
                out.writerow([
                    site,
                    res.get("audience_type"),
                    "|".join(res["demographics"].get("age_bracket", [])),
                    res["demographics"].get("income_level"),
                    (names["interests"] or [""])[0],
                    (names["purchase_intent"] or [""])[0],
                ])
        ```
        
        This is the shape most [website audience demographics](https://www.cookielessaudiences.com/features/website-audience-demographics.php) work takes: many sites in, one row per site out.
        
        ## Example: pandas enrichment
        
        ```python
        import pandas as pd
        
        df = pd.read_csv("accounts.csv")           # column: url
        found = client.segment_many(df["url"].tolist())
        df["audience_type"] = [r.get("audience_type") if isinstance(r, dict) else None for r in found.values()]
        df["seniority"] = [
            ",".join(r.get("b2b", {}).get("seniority", [])) if isinstance(r, dict) else None
            for r in found.values()
        ]
        ```
        
        ## Example: IAB categories for a text snippet
        
        ```python
        snippet = "Best budget laptops for students heading to university"
        cats = client.categorize_text(snippet)
        for name, score in cats["iab_classification"]:
            print(name, score)
        ```
        
        ## Frequently asked
        
        **Can I get the full word list for a field?** Yes. `CookielessAudiences.vocabularies()` returns every enumerated value and needs no key.
        
        **What about scale?** The service accepts up to 50 parallel threads by default, about 270 URLs a minute.
        
        **Which fields are free text?** None in the structured shape. Small fields are closed lists; open-ended signals are mapped to canonical codes or dropped.
        
        ## Package notes
        
        MIT licensed. Questions go to info@alpha-quantum.com. Version 1.0.0.
        
Keywords: cookieless,audience segmentation,iab audience taxonomy,iab categorization,contextual targeting,seller defined audiences,purchase intent,adtech,media planning,inventory curation,audience data,privacy-safe advertising,domain audience data
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.7
Description-Content-Type: text/markdown
