Reconstructing Prism Frameworks

Purchase the same Explorer frameworks that power public Carbon Arc Prisms — on a daily cadence — using the Python SDK.

This page explains the shared workflow. Category sub-guides list every live Prism in that category with the full framework JSON ready to paste into your job:

Category	Guide
Advertising	Advertising Prism Frameworks
App	App Prism Frameworks
Credit Card	Credit Card Prism Frameworks
Foot Traffic	Foot Traffic Prism Frameworks
Healthcare Credit Card	Healthcare Credit Card Prism Frameworks
Point of Sale	Point of Sale Prism Frameworks
Streaming	Streaming Prism Frameworks
TikTok Shop	TikTok Shop Prism Frameworks

For relative growth/share series without purchasing, use the public Prisms API. Product overview: Prisms guide.

1. Overview

Every public Prism is one framework purchase:

One Insight
A curated set of entities
Day grain (date_resolution: "day")
A location resolution (often us)
Optional dimension filters
A rolling date window

The platform recomputes that purchase on refresh. You can do the same with the Carbon Arc SDK.

What to remember

Use each Prism’s JSON for entities, insight, location, and dimension filters — not a frozen date range.
Recompute the window every day: first day of the current month minus 24 months → today.
Always keep date_resolution: "day" and aggregate: "sum".
buy_frameworks charges your account. Price first with check_framework_price.
After purchase, load data with get_framework_data.

2. Framework shape

Piece	Prism rule	In the JSON
Entities	One or more `(carc_id, representation)` pairs	`framework.entities`
Insight	Single insight id + label	`framework.insight`
Aggregate	Always `sum`	`framework.aggregate`
Date grain	Always `day`	`framework.filters.date_resolution`
Location	Stored on the Prism (often `us`)	`framework.filters.location_resolution`
Extra filters	Rare (e.g. `transaction_method`)	Other keys under `framework.filters`
Date window	Derived at purchase time	Refresh `date_range` daily

Under the hood this is the same path Builder uses: client.explorer.buy_frameworks.

3. Setup

pip install carbonarc pandas

from carbonarc import CarbonArcClient

client = CarbonArcClient(
    host="https://api.carbonarc.co",
    token="YOUR_API_TOKEN",  # https://app.carbonarc.ai/my/profile
)

Store the token in an environment variable (for example CARBONARC_API_TOKEN), not in source control.

4. Reconstruct a framework

4.1 Recompute the rolling window

from datetime import date

def prism_compute_window(today: date | None = None) -> dict[str, str]:
    """Same bounds Prism refresh uses: month-start − 24 months → today."""
    today = today or date.today()
    months = 24
    total = (today.year * 12 + (today.month - 1)) - months
    start = date(total // 12, total % 12 + 1, 1)
    return {"start_date": start.isoformat(), "end_date": today.isoformat()}

4.2 Build from a category guide payload

Copy a framework object from a category page (for example Coffee Foot Traffic), then:

fw = {
    # paste framework JSON from a category guide
}

owned = {"date_resolution", "date_range", "location_resolution", "aggregate"}
filters = {k: v for k, v in fw["filters"].items() if k not in owned}
filters["date_resolution"] = "day"
filters["location_resolution"] = fw["filters"]["location_resolution"]
filters["date_range"] = prism_compute_window()

framework = client.explorer.build_framework(
    entities=[
        {"carc_id": e["carc_id"], "representation": e["representation"]}
        for e in fw["entities"]
    ],
    insight=fw["insight"]["insight_id"],
    filters=filters,
    aggregate=fw.get("aggregate", "sum"),
)

5. Price, purchase, and retrieve

# 1) Quote (does not commit a purchase)
price = client.explorer.check_framework_price(framework)
print(f"${price:.2f}")

# 2) Purchase (charges your account)
order = client.explorer.buy_frameworks([framework])
framework_id = order["frameworks"][0]

# 3) Pull the series / table
payload = client.explorer.get_framework_data(framework_id=framework_id)
# payload["data"] → rows you can load with pandas

Batch multiple Prism frameworks from one category into a single order:

frameworks = [build_one(fw) for fw in category_payloads]
order = client.explorer.buy_frameworks(frameworks)

Large or busy-period buys may queue briefly. Retry on transient failures; contact support@carbonarc.co if a charge succeeds but data never appears. See the Explorer API.

6. Daily purchases by category

For Prism-equivalent freshness, run once per day after upstream panels settle (many US panels settle by mid-morning ET).

#!/usr/bin/env python3
"""Daily Prism-equivalent framework purchases for one category."""
from __future__ import annotations

import json
import logging
import os
from datetime import date

from carbonarc import CarbonArcClient

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(message)s")
log = logging.getLogger("prism-daily")

OWNED_FILTER_KEYS = frozenset(
    {"date_resolution", "date_range", "location_resolution", "aggregate"}
)

# Paste the list of framework objects from a category guide
CATEGORY_FRAMEWORKS = [
    # e.g. frameworks from Credit Card Prism Frameworks
]


def prism_compute_window(today: date | None = None) -> dict[str, str]:
    today = today or date.today()
    total = (today.year * 12 + (today.month - 1)) - 24
    start = date(total // 12, total % 12 + 1, 1)
    return {"start_date": start.isoformat(), "end_date": today.isoformat()}


def build_from_payload(client: CarbonArcClient, fw: dict) -> object:
    filters = {k: v for k, v in fw["filters"].items() if k not in OWNED_FILTER_KEYS}
    filters["date_resolution"] = "day"
    filters["location_resolution"] = fw["filters"]["location_resolution"]
    filters["date_range"] = prism_compute_window()
    return client.explorer.build_framework(
        entities=[
            {"carc_id": e["carc_id"], "representation": e["representation"]}
            for e in fw["entities"]
        ],
        insight=fw["insight"]["insight_id"],
        filters=filters,
        aggregate=fw.get("aggregate", "sum"),
    )


def main() -> None:
    client = CarbonArcClient(
        host=os.environ.get("CARBONARC_API_HOST", "https://api.carbonarc.co"),
        token=os.environ["CARBONARC_API_TOKEN"],
    )
    for fw in CATEGORY_FRAMEWORKS:
        title = fw.get("insight", {}).get("insight_name", "framework")
        try:
            framework = build_from_payload(client, fw)
            price = client.explorer.check_framework_price(framework)
            log.info("Buying %s (quote $%.2f)", title, price)
            order = client.explorer.buy_frameworks([framework])
            log.info("framework_id=%s", order["frameworks"][0])
        except Exception:
            log.exception("Failed: %s", title)


if __name__ == "__main__":
    main()

Cron example (UTC)

# Weekdays 15:00 UTC ≈ 11:00 ET — adjust to your panel SLAs and budget
0 15 * * 1-5 cd /path/to/job && /path/to/venv/bin/python daily_prism_purchase.py

Cost control tips

Start with one category page (for example Credit Card) before buying the full catalog.
Log and review quotes before enabling purchases in a new environment.
Each successful buy_frameworks is a billed order; add your own idempotency if you must avoid same-day repurchase.

7. Mapping cheat sheet

JSON field	SDK `build_framework` argument
`framework.entities[].carc_id` + `representation`	`entities=[{...}]` (`entity_name` is display-only)
`framework.insight.insight_id`	`insight=<int>`
`framework.filters` (minus stale `date_range`)	`filters={...}` with fresh `date_range`
`framework.aggregate`	`aggregate="sum"`

Do	Don’t
Refresh `date_range` every run	Paste the published `date_range` forever
Keep extra filters (e.g. Gas Station’s `transaction_method`)	Drop unknown filter keys
Use day grain	Switch to month unless you intentionally diverge from Prisms
Price then buy	Buy blind across every category

8. How this relates to public Prisms

Public Prism page	Your SDK job
Definition + scheduled refresh	Category guide JSON + your cron
Service-account purchase	Your API token / wallet
Growth index & share after pull	You get the raw purchased framework; index/share math is Prism UI logic
Trailing months trimmed in charts	Full purchased series unless you trim yourself

You are not calling a special Prism purchase API. You are purchasing the same Explorer framework the Prism pipeline would buy for that definition and window.

9. Troubleshooting

Symptom	What to check
`build_framework` / buy rejects filters	Insight may not support that location or dimension for this entity set — confirm in Builder or `collect_framework_filters`
Empty or short series	Window end is “today,” but panel `data_through` may lag
Unexpected bill	Confirm the job did not run more than once; check Order History
Auth errors	Token and API host must belong to the same environment
Queue / timeout	See Explorer API; retry; contact support if stuck

10. Category guides

SDK docs: Querying Data for Devs · Support: support@carbonarc.co