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(
    host="https://api.carbonarc.co",
    token="YOUR_API_TOKEN"            # Get from 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 three main 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

---

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
Querying Data	Build and purchase data
Filters & Date Ranges	Query options
Error Handling	Troubleshooting
ID Reference	Complete ID catalog