Explorer API

The Explorer API is how you query and purchase data from Carbon Arc. It provides a complete workflow for building data requests, checking prices, making purchases, and retrieving your data.

Overview

The Explorer API follows a four-step workflow:

Step	Method	Description
1. Build	`build_framework()`	Define what data you want
2. Price	`check_framework_price()`	See how much it costs
3. Buy	`buy_frameworks()`	Purchase the data
4. Get	`get_framework_data()`	Retrieve your purchased data

Setup

from carbonarc import CarbonArcClient
import pandas as pd

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

Core Concepts

What is a Framework?

A Framework is a data query that defines:

Entities — Who/what you want data for (companies, products, apps, tickers)
Insight — What metric you want (revenue, users, transactions, etc.)
Filters — How to slice the data (date range, location, resolution)
Aggregate — How to aggregate the values (sum, mean, count, etc.)

Key IDs You'll Need

ID Type	Description	Example
`carc_id`	Entity identifier	`64719` (Tesla)
`insight`	Metric/KPI identifier	`347`
`representation`	Entity type	`"company"`, `"ticker"`, `"app"`

Finding IDs

Use the Ontology API to discover entity IDs and insights, or the ID Reference for a complete catalog. To verify compatibility, use get_entities_for_insight(insight_id) to find valid entities for an insight, or get_insights_for_entity(entity_id, entity_representation) to find valid insights for an entity.

API Methods

1. Build Framework

Verify Entity-Insight Compatibility

Before building a framework, confirm that your entity and insight are compatible. Not every entity has data for every insight. Use get_insights_for_entity(entity_id, entity_representation) or get_entities_for_insight(insight_id) from the Ontology API to check.

Create a framework that defines your data query.

framework = client.explorer.build_framework(
    entities=[
        {"carc_id": 64719, "representation": "company"}
    ],
    insight=347,
    filters={
        "location_resolution": "us",
        "date_resolution": "month",
        "date_range": {
            "start_date": "2024-01-01",
            "end_date": "2024-12-31"
        }
    },
    aggregate="sum"
)

Parameters

Parameter	Type	Required	Description
`entities`	list	Yes	List of entity objects with `carc_id` and `representation`
`insight`	int	Yes	The insight ID (metric) you want
`filters`	dict	Yes	Filter configuration (see below)
`aggregate`	str	No	Aggregation method (`"sum"`, `"mean"`, or `"count_distinct"`, default: `None`)

Filter	Options	Description
`date_resolution`	`day`, `week`, `month`, `quarter`	Time granularity
`location_resolution`	`us`, `state`, `dma`, `cbsa`, `country`, `zip`, `ww`	Geographic granularity
`date_range`	`{start_date, end_date}`	Date range in `YYYY-MM-DD` format

Aggregation Options

Aggregate	Description
`sum`	Sum of values
`mean`	Average of values
`count_distinct`	Count of unique values

2. Explore Available Filters

Some data assets have custom filters (e.g., diagnosis categories, product types). Use these methods to discover them.

Get Filter Keys

filters = client.explorer.collect_framework_filters(framework)
print(filters)
# ['location_resolution', 'date_resolution', 'diagnosis_category', ...]

options = client.explorer.collect_framework_filter_options(
    framework, 
    "diagnosis_category"
)
print(options)
# ['respiratory', 'cardiovascular', 'neurological', ...]

3. Check Framework Price

Before purchasing, check how much the data will cost.

price = client.explorer.check_framework_price(framework)
print(f"Price: ${price:.2f}")

Understanding Pricing

Price	Meaning
`$X.XX`	Cost to purchase this data
`$0.00`	Data is free, already purchased, or included in your subscription

4. Buy Framework

Purchase the framework to access the data.

warning

This will charge your account! Always check the price first.

order = client.explorer.buy_frameworks([framework])
framework_id = order['frameworks'][0]

print(f"Framework ID: {framework_id}")
# Framework ID: abc123-def456-...

Save your Framework ID — you'll need it to retrieve data!

Buying Multiple Frameworks

You can purchase multiple frameworks in a single call:

frameworks = [framework1, framework2, framework3]
order = client.explorer.buy_frameworks(frameworks)

# Get all framework IDs
framework_ids = order['frameworks']

5. Get Framework Metadata

After purchasing, get metadata about your framework.

metadata = client.explorer.get_framework_metadata(framework_id="YOUR_FRAMEWORK_ID")
print(metadata)

6. Get Framework Data

Retrieve the data you purchased. By default, fetch_all=True returns all data in a single call.

# Returns all data at once (default)
data = client.explorer.get_framework_data(framework_id="YOUR_FRAMEWORK_ID")

# Convert to DataFrame
df = pd.DataFrame(data['data'])
print(df.head())

Parameters

Parameter	Type	Required	Default	Description
`framework_id`	str	Yes	—	The framework ID from your purchase
`data_type`	str	No	None	Return format: `"dataframe"` (returns a DataFrame directly) or `"timeseries"`
`page`	int	No	None	Page number (only used when `fetch_all=False`)
`size`	int	No	None	Page size (only used when `fetch_all=False`)
`fetch_all`	bool	No	`True`	Fetch all data in one call. Set to `False` for paginated retrieval

Return as DataFrame Directly

df = client.explorer.get_framework_data(
    framework_id="YOUR_FRAMEWORK_ID",
    data_type="dataframe"
)
print(df.head())

Paginated Retrieval

For large datasets, set fetch_all=False and paginate through results:

all_records = []
page = 1
page_size = 1000

while True:
    response = client.explorer.get_framework_data(
        framework_id="YOUR_FRAMEWORK_ID",
        fetch_all=False,
        page=page,
        size=page_size
    )
    
    records = response.get('data', [])
    total = response.get('total', 0)
    
    if not records:
        break
        
    all_records.extend(records)
    
    if len(all_records) >= total:
        break
        
    page += 1

df = pd.DataFrame(all_records)
print(f"Total records: {len(df)}")

Complete Examples

Example 1: Basic Workflow

Query monthly revenue data for Tesla:

from carbonarc import CarbonArcClient
import pandas as pd

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

# Step 1: Build framework
framework = client.explorer.build_framework(
    entities=[{"carc_id": 64719, "representation": "company"}],
    insight=347,
    filters={
        "location_resolution": "us",
        "date_resolution": "month",
        "date_range": {"start_date": "2024-01-01", "end_date": "2024-06-30"}
    },
    aggregate="sum"
)

# Step 2: Check price
price = client.explorer.check_framework_price(framework)
print(f"Price: ${price:.2f}")

# Step 3: Purchase
order = client.explorer.buy_frameworks([framework])
framework_id = order['frameworks'][0]

# Step 4: Get data
data = client.explorer.get_framework_data(framework_id=framework_id)
df = pd.DataFrame(data['data'])
print(df)

Example 2: Multiple Entities

Compare metrics across multiple companies:

framework = client.explorer.build_framework(
    entities=[
        {"carc_id": 64719, "representation": "company"},  # Tesla
        {"carc_id": 64781, "representation": "company"},  # Apple
        {"carc_id": 64823, "representation": "company"},  # Amazon
    ],
    insight=347,
    filters={
        "location_resolution": "us",
        "date_resolution": "month",
        "date_range": {"start_date": "2024-01-01", "end_date": "2024-12-31"}
    },
    aggregate="sum"
)

# Check price
price = client.explorer.check_framework_price(framework)
print(f"Price for 3 companies: ${price:.2f}")

# Purchase and retrieve
order = client.explorer.buy_frameworks([framework])
framework_id = order['frameworks'][0]

data = client.explorer.get_framework_data(framework_id=framework_id)
df = pd.DataFrame(data['data'])
print(df)

Example 3: State-Level Data

Get data broken down by state:

framework = client.explorer.build_framework(
    entities=[{"carc_id": 64719, "representation": "company"}],
    insight=347,
    filters={
        "location_resolution": "state",  # State-level granularity
        "date_resolution": "month",
        "date_range": {"start_date": "2024-01-01", "end_date": "2024-03-31"}
    },
    aggregate="sum"
)

# Check price (state-level data may cost more)
price = client.explorer.check_framework_price(framework)
print(f"State-level price: ${price:.2f}")

Example 4: Daily Resolution

Get daily-level data:

framework = client.explorer.build_framework(
    entities=[{"carc_id": 64719, "representation": "company"}],
    insight=347,
    filters={
        "location_resolution": "us",
        "date_resolution": "day",  # Daily granularity
        "date_range": {"start_date": "2024-01-01", "end_date": "2024-01-31"}
    },
    aggregate="sum"
)

# Daily data for a month
price = client.explorer.check_framework_price(framework)
print(f"Daily data price: ${price:.2f}")

Example 5: Custom Filters

Work with dataset-specific filters:

# First, discover available filters
framework = client.explorer.build_framework(
    entities=[{"carc_id": 12345, "representation": "company"}],
    insight=789,
    filters={
        "location_resolution": "us",
        "date_resolution": "month",
        "date_range": {"start_date": "2024-01-01", "end_date": "2024-12-31"}
    },
    aggregate="sum"
)

# Get available filter keys
filter_keys = client.explorer.collect_framework_filters(framework)
print(f"Available filters: {filter_keys}")

# Get options for a specific filter
if "diagnosis_category" in filter_keys:
    options = client.explorer.collect_framework_filter_options(
        framework, 
        "diagnosis_category"
    )
    print(f"Diagnosis categories: {options}")
    
    # Rebuild framework with custom filter
    framework = client.explorer.build_framework(
        entities=[{"carc_id": 12345, "representation": "company"}],
        insight=789,
        filters={
            "location_resolution": "us",
            "date_resolution": "month",
            "date_range": {"start_date": "2024-01-01", "end_date": "2024-12-31"},
            "diagnosis_category": "respiratory"  # Apply custom filter
        },
        aggregate="sum"
    )

Method Reference

Method	Signature	Returns
`build_framework()`	`(entities, insight, filters, aggregate)`	Framework object
`collect_framework_filters()`	`(framework)`	List of filter keys
`collect_framework_filter_options()`	`(framework, filter_key)`	List of options
`check_framework_price()`	`(framework)`	Price (float)
`buy_frameworks()`	`([frameworks])`	Order object with framework IDs
`get_framework_metadata()`	`(framework_id)`	Metadata dict
`get_framework_data()`	`(framework_id, data_type?, page?, size?, fetch_all?)`	DataFrame, timeseries, or dict

Quick Reference

┌─────────────────────────────────────────────────────────────┐
│              EXPLORER API WORKFLOW                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. build_framework()       → Define your query             │
│                                                             │
│  2. collect_framework_filters()   → (Optional) Discover     │
│     collect_framework_filter_options()   available filters  │
│                                                             │
│  3. check_framework_price() → Verify cost before buying     │
│                                                             │
│  4. buy_frameworks()        → Purchase (charges account!)   │
│                                                             │
│  5. get_framework_data()    → Retrieve your data            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Troubleshooting

Common Issues

Issue	Cause	Solution
Empty data returned	Framework not purchased	Call `buy_frameworks()` first
Invalid entity	Wrong `carc_id`	Use Ontology API to find correct ID
Invalid insight	Wrong insight ID	Check ID Reference for valid insights
Invalid entity/insight combination	Entity doesn't have data for the insight	Use `get_insights_for_entity()` or `get_entities_for_insight()` to verify compatibility
Price is $0	Already purchased or free tier	Data should be available
Timeout on large queries	Too much data requested	Reduce date range or use pagination

Debugging Tips

Inspect raw API responses:

import json

# Check framework structure
print(json.dumps(framework, indent=2))

# Check data response structure
data = client.explorer.get_framework_data(framework_id=framework_id)
print(f"Keys: {data.keys()}")
print(f"Records: {len(data.get('data', []))}")
print(f"Total available: {data.get('total', 'N/A')}")

Error Handling

try:
    framework = client.explorer.build_framework(
        entities=[{"carc_id": 64719, "representation": "company"}],
        insight=347,
        filters={...},
        aggregate="sum"
    )
    
    price = client.explorer.check_framework_price(framework)
    print(f"Price: ${price:.2f}")
    
    if price > 0:
        confirm = input("Proceed with purchase? (y/n): ")
        if confirm.lower() != 'y':
            print("Purchase cancelled.")
            exit()
    
    order = client.explorer.buy_frameworks([framework])
    framework_id = order['frameworks'][0]
    
    data = client.explorer.get_framework_data(framework_id=framework_id)
    df = pd.DataFrame(data['data'])
    
except Exception as e:
    print(f"Error: {e}")

Next Steps

Library API — Explore available data assets
Ontology API — Find entities and insights
ID Reference — Complete catalog of IDs

Overview

Setup

Core Concepts

What is a Framework?

Key IDs You'll Need

API Methods

1. Build Framework

Parameters

Filter Options

Aggregation Options

2. Explore Available Filters

Get Filter Keys

Get Filter Options

3. Check Framework Price

Understanding Pricing

4. Buy Framework

Buying Multiple Frameworks

5. Get Framework Metadata

6. Get Framework Data

Parameters

Return as DataFrame Directly

Paginated Retrieval

Complete Examples

Example 1: Basic Workflow

Example 2: Multiple Entities

Example 3: State-Level Data

Example 4: Daily Resolution

Example 5: Custom Filters

Method Reference

Quick Reference

Troubleshooting

Common Issues

Debugging Tips

Error Handling

Next Steps