Skip to main content

Use Cases & Recipes

Real-world examples you can copy, adapt, and run.

Setup

import pandas as pd
from carbonarc import CarbonArcClient
from datetime import datetime, timedelta
from dateutil.relativedelta import relativedelta

client = CarbonArcClient(
    host="https://api.carbonarc.co",
    token="YOUR_API_TOKEN"
)

Recipe 1: Find a Company by Name

Use the search parameter in get_entities to search for entities by name.

# Find Tesla (company)
results = client.ontology.get_entities(search="Tesla", representation=["company"])

# Find by ticker
results = client.ontology.get_entities(search="TSLA", representation=["ticker"])

Recipe 2: Find a Metric by Name

Use the search parameter in get_insights to search for insights by name.

# Find revenue-related metrics
results = client.ontology.get_insights(search="Revenue")

# Find only metric-type insights matching "spend"
results = client.ontology.get_insights(search="Spend", insight_types=["metric"])

Recipe 3: Single Company Analysis

Get metrics for a single company over a time period.

def analyze_company(client, entity_id, insight_id, start_date, end_date, 
                    date_resolution="month", location_resolution="us"):
    """
    Analyze a single company's metrics over time.
    
    Args:
        entity_id: Company's carc_id (e.g., 64719 for Tesla)
        insight_id: Metric to track
        start_date: Start date (YYYY-MM-DD)
        end_date: End date (YYYY-MM-DD)
    
    Returns:
        Framework ID
    """
    framework = client.explorer.build_framework(
        entity_id=entity_id,
        representation="company",
        insight_id=insight_id,
        start_date=start_date,
        end_date=end_date,
        date_resolution=date_resolution,
        location_resolution=location_resolution
    )
    
    framework_id = framework.get("framework_id")
    
    # Check price
    price = client.explorer.check_framework_price(framework_id=framework_id)
    print(f"Price: {price.get('price')} credits")
    print(f"Data points: {price.get('data_points')}")
    
    return framework_id

# Analyze Tesla's monthly metrics for 2024
framework_id = analyze_company(
    client,
    entity_id=64719,
    insight_id=465,
    start_date="2024-01-01",
    end_date="2024-12-31"
)

Recipe 4: Competitive Comparison

Compare the same metric across multiple companies.

def compare_companies(client, companies, insight_id, start_date, end_date,
                      date_resolution="month", location_resolution="us"):
    """
    Compare multiple companies on the same metric.
    
    Args:
        companies: List of dicts with 'name' and 'entity_id'
        insight_id: Metric to compare
    
    Returns:
        DataFrame with framework info
    """
    frameworks = []
    
    for company in companies:
        framework = client.explorer.build_framework(
            entity_id=company["entity_id"],
            representation="company",
            insight_id=insight_id,
            start_date=start_date,
            end_date=end_date,
            date_resolution=date_resolution,
            location_resolution=location_resolution
        )
        
        framework_id = framework.get("framework_id")
        price = client.explorer.check_framework_price(framework_id=framework_id)
        
        frameworks.append({
            "name": company["name"],
            "entity_id": company["entity_id"],
            "framework_id": framework_id,
            "price": price.get("price", 0),
            "data_points": price.get("data_points", 0)
        })
    
    df = pd.DataFrame(frameworks)
    print(f"Total cost: {df['price'].sum()} credits")
    return df

# Compare EV manufacturers
ev_companies = [
    {"name": "Tesla", "entity_id": 64719},
    {"name": "Rivian", "entity_id": 12345},
    {"name": "Lucid", "entity_id": 67890},
]

comparison = compare_companies(
    client,
    companies=ev_companies,
    insight_id=465,
    start_date="2024-01-01",
    end_date="2024-12-31"
)

Recipe 5: Trend Analysis

Analyze trends with year-over-year or month-over-month comparisons.

def get_trailing_periods(months_back=12):
    """Get date range for trailing N months."""
    end = datetime.now().replace(day=1) - timedelta(days=1)
    start = end - relativedelta(months=months_back-1)
    start = start.replace(day=1)
    return start.strftime("%Y-%m-%d"), end.strftime("%Y-%m-%d")

def analyze_trend(client, entity_id, insight_id, months_back=24):
    """Analyze metric trend over trailing months."""
    start_date, end_date = get_trailing_periods(months_back)
    
    framework = client.explorer.build_framework(
        entity_id=entity_id,
        representation="company",
        insight_id=insight_id,
        start_date=start_date,
        end_date=end_date,
        date_resolution="month",
        location_resolution="us"
    )
    
    framework_id = framework.get("framework_id")
    price = client.explorer.check_framework_price(framework_id=framework_id)
    
    print(f"Period: {start_date} to {end_date}")
    print(f"Price: {price.get('price')} credits")
    
    return framework_id

# 2-year trend analysis
framework_id = analyze_trend(client, entity_id=64719, insight_id=465, months_back=24)

Calculate Growth Rates

def calculate_growth(df, value_col="value", date_col="date"):
    """Add month-over-month and year-over-year growth columns."""
    df = df.sort_values(date_col).copy()
    df["mom_growth"] = df[value_col].pct_change() * 100
    df["yoy_growth"] = df[value_col].pct_change(periods=12) * 100
    return df

Recipe 6: App Analytics

Track mobile app metrics (downloads, MAU, DAU).

def find_app(client, app_name):
    """Search for a mobile app by name."""
    response = client.ontology.get_entities(search=app_name, representation=["app"])
    entities = response.get("entities", [])
    if not entities:
        return pd.DataFrame()
    return pd.DataFrame(entities)[["carc_id", "label", "representation"]]

# Note: returns the first page of results (default size: 100).
# For broad search terms that may match many apps, pass page= and size= to paginate.

def analyze_app(client, app_entity_id, insight_id, start_date, end_date):
    """Analyze app metrics over time."""
    framework = client.explorer.build_framework(
        entity_id=app_entity_id,
        representation="app",
        insight_id=insight_id,
        start_date=start_date,
        end_date=end_date,
        date_resolution="month",
        location_resolution="ww"  # Worldwide for apps
    )
    
    framework_id = framework.get("framework_id")
    price = client.explorer.check_framework_price(framework_id=framework_id)
    
    print(f"Price: {price.get('price')} credits")
    return framework_id

# Find and analyze Instagram
apps = find_app(client, "Instagram")
framework_id = analyze_app(
    client,
    app_entity_id=apps.iloc[0]["carc_id"],
    insight_id=789,
    start_date="2024-01-01",
    end_date="2024-12-31"
)

Recipe 7: Geographic Breakdown

Compare metrics across different regions.

def analyze_by_region(client, entity_id, insight_id, start_date, end_date,
                      location_resolution="state"):
    """
    Get geographic breakdown of a metric.
    
    location_resolution options: "state", "dma", "country", "cbsa", "zip"
    """
    framework = client.explorer.build_framework(
        entity_id=entity_id,
        representation="company",
        insight_id=insight_id,
        start_date=start_date,
        end_date=end_date,
        date_resolution="month",
        location_resolution=location_resolution
    )
    
    framework_id = framework.get("framework_id")
    price = client.explorer.check_framework_price(framework_id=framework_id)
    
    print(f"Resolution: {location_resolution}")
    print(f"Price: {price.get('price')} credits")
    
    return framework_id

# State-by-state analysis
framework_id = analyze_by_region(
    client,
    entity_id=64719,
    insight_id=465,
    start_date="2024-01-01",
    end_date="2024-12-31",
    location_resolution="state"
)

Summarize by Region

def summarize_by_region(df, region_col="state", value_col="value"):
    """Summarize data by region."""
    summary = df.groupby(region_col)[value_col].agg([
        ("total", "sum"),
        ("average", "mean"),
        ("count", "count")
    ]).sort_values("total", ascending=False)
    
    summary["pct_of_total"] = (summary["total"] / summary["total"].sum() * 100).round(1)
    return summary

Recipe 8: Quarter-over-Quarter Comparison

Compare performance across quarters.

def get_quarter_dates(year, quarter):
    """Get start and end dates for a quarter."""
    quarter_starts = {1: f"{year}-01-01", 2: f"{year}-04-01", 3: f"{year}-07-01", 4: f"{year}-10-01"}
    quarter_ends = {1: f"{year}-03-31", 2: f"{year}-06-30", 3: f"{year}-09-30", 4: f"{year}-12-31"}
    return quarter_starts[quarter], quarter_ends[quarter]

def compare_quarters(client, entity_id, insight_id, quarters):
    """
    Compare metrics across multiple quarters.
    
    Args:
        quarters: List of (year, quarter) tuples
                  e.g., [(2024, 1), (2024, 2), (2024, 3), (2024, 4)]
    """
    results = []
    
    for year, q in quarters:
        start_date, end_date = get_quarter_dates(year, q)
        
        framework = client.explorer.build_framework(
            entity_id=entity_id,
            representation="company",
            insight_id=insight_id,
            start_date=start_date,
            end_date=end_date,
            date_resolution="quarter",
            location_resolution="us"
        )
        
        framework_id = framework.get("framework_id")
        price = client.explorer.check_framework_price(framework_id=framework_id)
        
        results.append({
            "quarter": f"Q{q} {year}",
            "framework_id": framework_id,
            "price": price.get("price", 0)
        })
    
    return pd.DataFrame(results)

# Compare all quarters of 2024
quarters = [(2024, 1), (2024, 2), (2024, 3), (2024, 4)]
qoq_comparison = compare_quarters(client, entity_id=64719, insight_id=465, quarters=quarters)

Recipe 9: Discover Available Data

Explore what data assets and insights are available for an entity.

def discover_entity_data(client, entity_id, representation="company"):
    """Discover what data is available for an entity."""
    entity_info = client.ontology.get_entity_information(
        entity_id=entity_id,
        representation=representation
    )
    
    print(f"Entity: {entity_info.get('name')}")
    print(f"   ID: {entity_id}")
    
    insights = entity_info.get("insights", [])
    if insights:
        print(f"\nAvailable Insights ({len(insights)}):")
        for i, insight in enumerate(insights[:10], 1):
            print(f"   {i}. {insight.get('name')} (ID: {insight.get('insight_id')})")
    
    return entity_info

def get_insight_details(client, insight_id):
    """Get detailed information about an insight."""
    info = client.ontology.get_insight_information(insight_id=insight_id)
    
    print(f"Insight: {info.get('name')}")
    print(f"   Description: {info.get('description')}")
    print(f"   Unit: {info.get('unit')}")
    
    return info

# What data is available for Tesla?
entity_info = discover_entity_data(client, entity_id=64719)
insight_info = get_insight_details(client, insight_id=465)

Recipe 10: Full Workflow

Complete end-to-end: Build, Price, Buy, and Retrieve.

def full_analysis_workflow(client, entity_id, insight_id, start_date, end_date,
                           date_resolution="month", location_resolution="us",
                           auto_buy=False):
    """
    Complete workflow: Build -> Price -> Buy -> Retrieve.
    
    Args:
        auto_buy: If True, automatically purchase (use with caution!)
    
    Returns:
        DataFrame with data (if purchased), or framework info (if not)
    """
    # Step 1: Build
    print("1. Building framework...")
    framework = client.explorer.build_framework(
        entity_id=entity_id,
        representation="company",
        insight_id=insight_id,
        start_date=start_date,
        end_date=end_date,
        date_resolution=date_resolution,
        location_resolution=location_resolution
    )
    framework_id = framework.get("framework_id")
    
    # Step 2: Price
    print("2. Checking price...")
    price_info = client.explorer.check_framework_price(framework_id=framework_id)
    print(f"   {price_info.get('price')} credits for {price_info.get('data_points')} data points")
    
    if not auto_buy:
        print("auto_buy=False - returning framework info")
        return {"framework_id": framework_id, **price_info}
    
    # Step 3: Buy
    print("3. Purchasing...")
    client.explorer.buy_frameworks(framework_ids=[framework_id])
    
    # Step 4: Retrieve
    print("4. Retrieving data...")
    all_data = []
    page = 1
    
    while True:
        response = client.explorer.get_framework_data(
            framework_id=framework_id,
            page=page,
            page_size=10000
        )
        data = response.get("data", [])
        if not data:
            break
        all_data.extend(data)
        if len(all_data) >= response.get("total", 0):
            break
        page += 1
    
    print(f"   Retrieved {len(all_data)} rows")
    return pd.DataFrame(all_data)

# Full workflow (without auto-buy for safety)
result = full_analysis_workflow(
    client,
    entity_id=64719,
    insight_id=465,
    start_date="2024-01-01",
    end_date="2024-12-31",
    auto_buy=False
)

Recipe 11: Export for Dashboards

Prepare data for visualization tools (Tableau, Power BI, etc.).

def prepare_for_dashboard(df, entity_name=None, metric_name=None):
    """Clean and prepare data for dashboard tools."""
    df = df.copy()
    
    # Add metadata
    if entity_name:
        df["entity_name"] = entity_name
    if metric_name:
        df["metric_name"] = metric_name
    
    # Parse dates
    if "date" in df.columns:
        df["date"] = pd.to_datetime(df["date"], errors="coerce")
        df["year"] = df["date"].dt.year
        df["month"] = df["date"].dt.month
        df["quarter"] = df["date"].dt.quarter
        df["month_name"] = df["date"].dt.strftime("%b %Y")
    
    return df

def export_dashboard_ready(df, filename, formats=["csv", "parquet"]):
    """Export to multiple formats."""
    for fmt in formats:
        if fmt == "csv":
            df.to_csv(f"{filename}.csv", index=False)
        elif fmt == "parquet":
            df.to_parquet(f"{filename}.parquet", index=False)
        elif fmt == "excel":
            df.to_excel(f"{filename}.xlsx", index=False)
        print(f"Exported: {filename}.{fmt}")

# Prepare and export
df_clean = prepare_for_dashboard(df_raw, entity_name="Tesla", metric_name="Consumer Spend")
export_dashboard_ready(df_clean, "tesla_analysis", formats=["csv", "parquet"])

Quick Reference

Discovery Functions

FunctionDescription
client.ontology.get_entities(search="Tesla", representation=["company"])Search entities by name
client.ontology.get_insights(search="Revenue")Search insights by name
find_app(client, "Instagram")Search apps by name
discover_entity_data(client, 64719)See available insights
get_insight_details(client, 465)Get insight metadata

Analysis Functions

FunctionDescription
analyze_company(...)Single company metrics
compare_companies(...)Multi-company comparison
analyze_trend(..., months_back=24)Historical trend
analyze_app(...)Mobile app analytics
analyze_by_region(..., "state")Geographic breakdown
compare_quarters(...)Quarter-over-quarter

Workflow Functions

FunctionDescription
full_analysis_workflow(...)Build, Price, Buy, Retrieve
prepare_for_dashboard(df)Clean data for viz tools
export_dashboard_ready(df, "file")Export to CSV/Parquet/Excel

Helper Functions

FunctionDescription
get_trailing_periods(12)Last 12 months date range
get_quarter_dates(2024, 1)Q1 2024 start/end dates
calculate_growth(df)Add MoM and YoY growth
summarize_by_region(df)Aggregate by geography

Next Steps