Facteus Core Panel - Framework Setup Guide

This guide shows you how to create frameworks for Facteus Core Panel credit card insights.

Facteus Core Panel Insight IDs

626: Credit Card Spend
627: Credit Card Transactions
628: Credit Card Users
629: Credit Card Average Transaction Amount

Quick Start

Set up authentication
Define your entities and date range
Create frameworks for each insight ID
Purchase and retrieve data

Step 1: Setup and Authentication

Import required libraries and initialize the CarbonArc client:

# Import required libraries
import os
from datetime import datetime, timedelta
import pandas as pd
from carbonarc import CarbonArcClient
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Initialize client
HOST = os.getenv("HOST", "https://api.carbonarc.co")
TOKEN = os.getenv("TOKEN")

if not TOKEN:
    raise ValueError("TOKEN not found. Please set it in your .env file.")

client = CarbonArcClient(host=HOST, token=TOKEN)
print("✅ CarbonArc client initialized")

Step 2: Define Entities and Date Range

Define your entity sets and date range. For Facteus Core Panel, you typically use company entities:

You have two options:

Specific entities: List individual entity IDs
Wildcard (*): Pull data for ALL entities of a given representation

Check out this guide for off the shelf Entity Lists. Lift and shift these lifts for quick setup.

# Option 1: Define specific entity sets (example with company entities)
entity_sets = [
    {"carc_id": 64781, "representation": "company"}, # Walmart Inc
    {"carc_id": 64702, "representation": "company"}, # Target
    {"carc_id": 64127, "representation": "company"}, # Amazon
    {"carc_id": 64152, "representation": "company"}, # Best Buy
    {"carc_id": 58072, "representation": "company"}, # Trader Joes

    # Add more entities as needed
]

# Option 2: Use wildcard to pull ALL entities (uncomment to use)
# entity_sets = {"carc_name": "*", "representation": "company"}
# This will pull data for all companies instead of specific ones
# Highly recommended to check price before purchasing a wildcard framework

# Define date range for example:
start_date = "2024-01-01"
end_date = "2024-12-31"

# Display entity configuration
if isinstance(entity_sets, dict) and entity_sets.get("carc_name") == "*":
    print(f"✅ Using wildcard: All {entity_sets.get('representation', 'entities')}")
else:
    print(f"✅ Defined {len(entity_sets)} entities")
print(f"✅ Date range: {start_date} to {end_date}")

Step 3: Create Frameworks for Facteus Core Panel Insights

Create frameworks for each of the four Facteus Core Panel insights:

# Framework 1: Credit Card Spend (Insight ID 626)
framework_spend = client.explorer.build_framework(
    entities=entity_sets,
    insight=626,  # Credit Card Spend
    filters={
        "location_resolution": "us",
        "date_resolution": "week",  # Options: "day", "week", "month", "quarter", "year"
        "date_range": {
            "start_date": start_date,
            "end_date": end_date
        "transaction_method": "*" # Optional - specify "Online" or "Physical"
        }
    },
    aggregate="sum"  # Use "sum" for spend
)

print("✅ Framework 1: Credit Card Spend (626)")
print(f"   Insight ID: {framework_spend['insight']['insight_id']}")
print(f"   Aggregate: {framework_spend['aggregate']}")

# Framework 2: Credit Card Transactions (Insight ID 627)
framework_transactions = client.explorer.build_framework(
    entities=entity_sets,
    insight=627,  # Credit Card Transactions
    filters={
        "location_resolution": "us",
        "date_resolution": "week",
        "date_range": {
            "start_date": start_date,
            "end_date": end_date
        "transaction_method": "*" # Optional - specify "Online" or "Physical"
        }
    },
    aggregate="sum"  # Use "sum" for transaction count
)

print("✅ Framework 2: Credit Card Transactions (627)")
print(f"   Insight ID: {framework_transactions['insight']['insight_id']}")
print(f"   Aggregate: {framework_transactions['aggregate']}")

# Framework 3: Credit Card Users (Insight ID 628)
framework_users = client.explorer.build_framework(
    entities=entity_sets,
    insight=628,  # Credit Card Users
    filters={
        "location_resolution": "us",
        "date_resolution": "week",
        "date_range": {
            "start_date": start_date,
            "end_date": end_date
        "transaction_method": "*" # Optional - specify "Online" or "Physical"
        }
    },
    aggregate="sum"  # Use "sum" for user count
)

print("✅ Framework 3: Credit Card Users (628)")
print(f"   Insight ID: {framework_users['insight']['insight_id']}")
print(f"   Aggregate: {framework_users['aggregate']}")

# Framework 4: Credit Card Average Transaction Amount (Insight ID 629)
framework_avg_transaction = client.explorer.build_framework(
    entities=entity_sets,
    insight=629,  # Credit Card Average Transaction Amount
    filters={
        "location_resolution": "us",
        "date_resolution": "week",
        "date_range": {
            "start_date": start_date,
            "end_date": end_date
        "transaction_method": "*" # Optional - specify "Online" or "Physical"
        }
    },
    aggregate="mean"  # Use "mean" for average transaction amount
)

print("✅ Framework 4: Credit Card Average Transaction Amount (629)")
print(f"   Insight ID: {framework_avg_transaction['insight']['insight_id']}")
print(f"   Aggregate: {framework_avg_transaction['aggregate']}")

Step 4a: Check Framework Prices (Recommended)

Before purchasing, you can check the price of each framework:

# Check prices for all frameworks
print("Checking framework prices...\n")

frameworks_to_check = {
    'Credit Card Spend (626)': framework_spend,
    'Credit Card Transactions (627)': framework_transactions,
    'Credit Card Users (628)': framework_users,
    'Credit Card Avg Transaction Amount (629)': framework_avg_transaction
}

prices = {}
total_price = 0

for name, framework in frameworks_to_check.items():
    try:
        price = client.explorer.check_framework_price(framework)
        if price is not None:
            prices[name] = price
            total_price += price
            print(f"✅ {name}: ${price}")
        else:
            print(f"ℹ️ {name}: Price information not available")
            prices[name] = None
    except Exception as e:
        print(f"⚠️ {name}: Could not retrieve price - {str(e)}")
        prices[name] = None

if total_price > 0:
    print(f"\n💰 Total price for all frameworks: ${total_price}")
else:
    print("\nℹ️ Total price calculation skipped (some prices unavailable)")

Step 4b: Purchase Frameworks

Purchase all frameworks at once or individually:

# Option 1: Purchase all frameworks at once
all_frameworks = [
    framework_spend,
    framework_transactions,
    framework_users,
    framework_avg_transaction
]

print("🛒 Purchasing all Facteus Core Panel frameworks...")
order = client.explorer.buy_frameworks(all_frameworks)

print("✅ Frameworks purchased successfully")
print(f"   Framework IDs: {order['frameworks']}")

# Store framework IDs
framework_ids = {
    'spend': order['frameworks'][0],           # 626
    'transactions': order['frameworks'][1],    # 627
    'users': order['frameworks'][2],           # 628
    'avg_transaction': order['frameworks'][3]  # 629
}

print("\n💡 Framework IDs saved:")
for key, fid in framework_ids.items():
    print(f"   {key}: {fid}")

Step 5: Check Framework Status

Check the status of your frameworks (they may need time to process):

# Check status of all frameworks
print("📊 Checking framework status...")
for name, framework_id in framework_ids.items():
    status = client.explorer.get_framework_status(framework_id)
    print(f"   {name} ({framework_id}): {status.get('status', 'unknown')}")

Step 6: Retrieve Data

Once frameworks are ready, retrieve data for all insights:

# Retrieve data for all frameworks
dataframes = {}

# Credit Card Spend (626)
df_spend = client.explorer.get_framework_data(
    framework_id=framework_ids['spend'],
    data_type="dataframe",
    fetch_all=True
)
dataframes['spend'] = df_spend
print(f"✅ Credit Card Spend: {df_spend.shape[0]} rows")

# Credit Card Transactions (627)
df_transactions = client.explorer.get_framework_data(
    framework_id=framework_ids['transactions'],
    data_type="dataframe",
    fetch_all=True
)
dataframes['transactions'] = df_transactions
print(f"✅ Credit Card Transactions: {df_transactions.shape[0]} rows")

# Credit Card Users (628)
df_users = client.explorer.get_framework_data(
    framework_id=framework_ids['users'],
    data_type="dataframe",
    fetch_all=True
)
dataframes['users'] = df_users
print(f"✅ Credit Card Users: {df_users.shape[0]} rows")

# Credit Card Average Transaction Amount (629)
df_avg_transaction = client.explorer.get_framework_data(
    framework_id=framework_ids['avg_transaction'],
    data_type="dataframe",
    fetch_all=True
)
dataframes['avg_transaction'] = df_avg_transaction
print(f"✅ Average Transaction Amount: {df_avg_transaction.shape[0]} rows")

Step 7: View and Export Data

View sample data and export to CSV:

# Display sample data for each framework
print("📊 Credit Card Spend (626):")
print(dataframes['spend'].head())
print(f"\n📊 Credit Card Transactions (627):")
print(dataframes['transactions'].head())
print(f"\n📊 Credit Card Users (628):")
print(dataframes['users'].head())
print(f"\n📊 Average Transaction Amount (629):")
print(dataframes['avg_transaction'].head())

# Export all dataframes to CSV
timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')

for name, df in dataframes.items():
    filename = f"facteus_{name}_{timestamp}.csv"
    df.to_csv(filename, index=False)
    print(f"💾 Exported {name} to {filename}")

Summary

This guide covered creating frameworks for all four Facteus Core Panel insights:

✅ Credit Card Spend (626) - Use aggregate="sum"
✅ Credit Card Transactions (627) - Use aggregate="sum"
✅ Credit Card Users (628) - Use aggregate="sum"
✅ Credit Card Average Transaction Amount (629) - Use aggregate="mean"

Key Points:

Aggregation: Use "sum" for spend, transactions, and users; use "mean" for average transaction amount
Date Resolution: Common options are "day", "week", "month", "quarter", "year"
Location Resolution: Typically "us" for US data
Processing Time: Frameworks may take time to process, especially for large entity sets

Facteus Core Panel Insight IDs​

Quick Start​

Step 1: Setup and Authentication​

Step 2: Define Entities and Date Range​

Step 3: Create Frameworks for Facteus Core Panel Insights​

Step 4a: Check Framework Prices (Recommended)​

Step 4b: Purchase Frameworks​

Step 5: Check Framework Status​

Step 6: Retrieve Data​

Step 7: View and Export Data​

Summary​

Key Points:​