Skip to main content

Explorer: Frameworks

This notebook demonstrates how to build and explore data frameworks using the SDK.

1. Load Environment Variables and Instantiate Client​

from dotenv import load_dotenv
import os

# Load environment variables from .env file
dotenv_path = '.env'
load_dotenv(dotenv_path)

# Retrieve API token
api_token = os.getenv('API_AUTH_TOKEN')

# Initialize the SDK client
from carbonarc import CarbonArcClient
client = CarbonArcClient(api_token)

print('Client initialized successfully')

2. Build a Framework​

Construct a query framework using the Carbon Arc API. Replace parameters as needed.

# Import required dependencies
import os
from dotenv import load_dotenv
from carbonarc import CarbonArcClient

load_dotenv()

## Read in environment variables
API_AUTH_TOKEN=os.getenv("API_AUTH_TOKEN")

# Create API Client
client = CarbonArcClient(API_AUTH_TOKEN)

print('Client initialized successfully')

# Define the framework request payload
framework = client.explorer.build_framework(
    entities=[{"carc_id": 64781, "representation": "company"}],
    insight=347,
    filters={
        "location_resolution": "us",
        "date_resolution": "day",
        "date_range": {"start_date": "2022-6-20", "end_date": "2025-6-19"},
    },
    aggregate="mean"
)

# Build the framework and retrieve available filters
information = client.explorer.collect_framework_filters(framework_request)
print('Framework filters:', information)

3. View Available Filters​

Retrieve the filter keys you can use to refine your framework.

filter_keys = client.explorer.collect_framework_filters(framework_request)
print('Available filters:', filter_keys)

4. Inspect Filter Options​

Choose a filter key to see its available options.

filter_key = "platform"
options = client.explorer.collect_framework_filter_options(framework_request, filter_key)
print(f"Options for '{filter_key}':", options)

Next Steps​

  • Retrieve data with client.explorer.get_framework_data(framework_id=<YOUR_ID>)
  • Stream large datasets using client.explorer.stream_framework_data(framework_id=<YOUR_ID>)