Getting Started

Get up and running with the Carbon Arc Python SDK in minutes.

---

Installation

pip install carbonarc

---

Setup

from carbonarc import CarbonArcClient
import pandas as pd

client = CarbonArcClient(token="YOUR_API_TOKEN")  # Get your token from the Carbon Arc dashboard

Get Your API Token

See API Authentication for instructions on generating your API token from the Carbon Arc dashboard.

---

SDK Structure

The SDK is organized into namespaces:

Namespace	Purpose
client.data	Browse data assets, metadata, data dictionaries
client.ontology	Find entities (companies, apps) and insights (metrics)
client.explorer	Build queries, check prices, purchase, retrieve data
client.block	Discover Block datasets, request access, and manage S3 / Polaris delivery

Block is an enterprise add-on

client.block is only available to enterprise clients with Block access, and only to API tokens belonging to a user with a Block User or Block Admin role. To enable Block, contact support@carbonarc.co. See Block for Devs.

---

Workflow

1. Explore   →  What data is available? (data/ontology)
2. Build     →  Define your query (explorer)
3. Purchase  →  Buy the data (explorer)
4. Retrieve  →  Get your data (explorer)

---

Quick Examples

List Datasets

response = client.data.get_datasets()
datasets = response.get('datasources', [])

for ds in datasets[:5]:
    ds_id = ds.get('dataset_id', ['N/A'])
    if isinstance(ds_id, list):
        ds_id = ds_id[0]
    print(f"{ds_id}: {ds.get('dataset_name')}")

List Entities

response = client.ontology.get_entities(page=1, size=20)

for entity in response.get('items', []):
    print(f"{entity['carc_id']}: {entity['carc_name']} ({entity['representation']})")

Get Entity Information

entity = client.ontology.get_entity_information(
    entity_id=64719,
    representation="company"
)
print(f"Entity: {entity.get('carc_name')}")

Build & Execute a Query

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

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

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

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

---

Key IDs

ID	Type	Example	Where to Find
carc_id	int	64719	client.ontology.get_entities()
insight	int	347	client.ontology.get_insight_information()
dataset_id	str	"CA0056"	client.data.get_datasets()
framework_id	str	(uuid)	client.explorer.buy_frameworks()

---

Filter Options

Filter	Values
date_resolution	day, week, month, quarter
location_resolution	us, state, dma, cbsa, zip, country, ww
aggregate	sum, mean, median, count, count_distinct

---

Common Patterns

Error Handling

try:
    result = client.data.get_datasets()
except Exception as e:
    print(f"Error: {e}")

Pagination

all_entities = []
page = 1

while True:
    response = client.ontology.get_entities(page=page, size=100)
    items = response.get('items', [])
    
    if not items:
        break
    
    all_entities.extend(items)
    
    if page >= response.get('pages', 1):
        break
    
    page += 1

print(f"Total entities: {len(all_entities)}")

Safe Data Access

# Returns empty list if key is missing
records = response.get('data', [])
datasources = response.get('datasources', [])
items = response.get('items', [])

---

Quick Reference

LIBRARY
─────────────────────────────────────────────────────────────
client.data.get_datasets()              List all datasets
client.data.get_dataset_information()   Get dataset details
client.data.get_data_dictionary()       Get field definitions
client.data.get_data_sample()           Preview sample data

ONTOLOGY
─────────────────────────────────────────────────────────────
client.ontology.get_entity_map()        Get entity types
client.ontology.get_entities()          List entities
client.ontology.get_entity_information() Get entity details
client.ontology.get_insight_information() Get insight details

EXPLORER
─────────────────────────────────────────────────────────────
client.explorer.build_framework()       Create a query
client.explorer.check_framework_price() Get price quote
client.explorer.buy_frameworks()        Purchase data
client.explorer.get_framework_data()    Retrieve data

---

Next Steps

Guide	What You'll Learn
API Authentication	Get your API token
Library	Explore available data assets
Ontology	Find entities and insights
Block	Discover and request Block datasets (enterprise)
Querying Data	Build and purchase data
Filters & Date Ranges	Query options
Error Handling	Troubleshooting
ID Reference	Complete ID catalog