Facteus Constant Shopper - Framework Setup Guide

This guide shows you how to create frameworks for Constant Shopper credit card insights.

Facteus Constant Shopper Insight IDs

765: Credit Card Spend
766: Credit Card Transactions
767: Credit Card Users
768: 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 Constant Shopper, 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

# 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

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

# Or use relative dates:
# end_date = datetime.now().strftime("%Y-%m-%d")
# start_date = (datetime.now() - timedelta(days=365)).strftime("%Y-%m-%d")

# 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 Constant Shopper Insights

Create frameworks for each of the four Constant Shopper insights:

# Framework 1: Credit Card Spend (Insight ID 765)
framework_spend = client.explorer.build_framework(
    entities=entity_sets,
    insight=765,  # 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 (765)")
print(f"   Insight ID: {framework_spend['insight']['insight_id']}")
print(f"   Aggregate: {framework_spend['aggregate']}")

# Framework 2: Credit Card Transactions (Insight ID 766)
framework_transactions = client.explorer.build_framework(
    entities=entity_sets,
    insight=766,  # 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 (766)")
print(f"   Insight ID: {framework_transactions['insight']['insight_id']}")
print(f"   Aggregate: {framework_transactions['aggregate']}")

# Framework 3: Credit Card Users (Insight ID 767)
framework_users = client.explorer.build_framework(
    entities=entity_sets,
    insight=767,  # 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 (767)")
print(f"   Insight ID: {framework_users['insight']['insight_id']}")
print(f"   Aggregate: {framework_users['aggregate']}")

# Framework 4: Credit Card Average Transaction Amount (Insight ID 768)
framework_avg_transaction = client.explorer.build_framework(
    entities=entity_sets,
    insight=768,  # 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 (768)")
print(f"   Insight ID: {framework_avg_transaction['insight']['insight_id']}")
print(f"   Aggregate: {framework_avg_transaction['aggregate']}")

Step 4: Check Framework Prices (Optional)

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 (765)': framework_spend,
    'Credit Card Transactions (766)': framework_transactions,
    'Credit Card Users (767)': framework_users,
    'Credit Card Avg Transaction Amount (768)': 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 5: 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 Constant Shopper 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],           # 765
    'transactions': order['frameworks'][1],    # 766
    'users': order['frameworks'][2],           # 767
    'avg_transaction': order['frameworks'][3]  # 768
}

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

Option 2: Purchase frameworks individually

Uncomment the frameworks you want to purchase

framework_ids = {}

# Purchase Credit Card Spend (626)
# order_spend = client.explorer.buy_frameworks(framework_spend)
# framework_ids['spend'] = order_spend['frameworks'][0]
# print(f"✅ Purchased Credit Card Spend: {framework_ids['spend']}")

# Purchase Credit Card Transactions (627)
# order_transactions = client.explorer.buy_frameworks(framework_transactions)
# framework_ids['transactions'] = order_transactions['frameworks'][0]
# print(f"✅ Purchased Credit Card Transactions: {framework_ids['transactions']}")

# Purchase Credit Card Users (628)
# order_users = client.explorer.buy_frameworks(framework_users)
# framework_ids['users'] = order_users['frameworks'][0]
# print(f"✅ Purchased Credit Card Users: {framework_ids['users']}")

# Purchase Credit Card Average Transaction Amount (629)
# order_avg = client.explorer.buy_frameworks(framework_avg_transaction)
# framework_ids['avg_transaction'] = order_avg['frameworks'][0]
# print(f"✅ Purchased Average Transaction Amount: {framework_ids['avg_transaction']}")

print("💡 Uncomment the frameworks above to purchase them individually")

Step 6: Check Framework Status

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

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 7: Retrieve Data

Once frameworks are ready, retrieve data for all insights:

# Retrieve data for all frameworks
dataframes = {}

# Credit Card Spend (765)
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 (766)
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 (767)
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 (768)
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 8: 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

Next Steps:

Combine the dataframes for comprehensive analysis
Create visualizations comparing spend, transactions, users, and average transaction amounts
Export to S3 or other storage systems for long-term storage

Facteus Constant Shopper Insight IDs​

Quick Start​

Step 1: Setup and Authentication​

Step 2: Define Entities and Date Range​

Step 3: Create Frameworks for Constant Shopper Insights​

Step 4: Check Framework Prices (Optional)​

Step 5: Purchase Frameworks​

Option 2: Purchase frameworks individually​

Uncomment the frameworks you want to purchase​

Step 6: Check Framework Status​

Step 7: Retrieve Data​

Step 8: View and Export Data​

Summary​

Key Points:​

Next Steps:​