Skip to main content

Querying Data for Devs

Learn how to build queries, create frameworks, and retrieve data programmatically using the Carbon Arc SDK.

API Reference

Explorer API

Build, price, purchase, and retrieve data using frameworks.

Filters & Date Ranges

Date resolutions, location granularity, and aggregation options.

Error Handling

Handle errors gracefully with retries and debugging strategies.

Exporting Data

Export to CSV, Excel, JSON, Parquet, databases, and cloud storage.

Available Methods

MethodDescription
client.explorer.build_framework()Create a framework defining your data query
client.explorer.collect_framework_filters()Discover available filter keys
client.explorer.collect_framework_filter_options()Get options for a specific filter
client.explorer.check_framework_price()Check cost before purchasing
client.explorer.buy_frameworks()Purchase frameworks (charges account)
client.explorer.get_framework_metadata()Get metadata for a purchased framework
client.explorer.get_framework_data()Retrieve purchased data

Key Concepts

ConceptDescription
FrameworkA structured query combining an entity, insight, time range, and filters
EntityThe subject of your query (company, product, location, etc.)
InsightThe metric or KPI you want to retrieve (spend, transactions, users, etc.)
FiltersOptional parameters to narrow your query (geography, time, demographics)

Typical Workflow

  1. Discover — Use the Ontology API to find entities and insights
  2. Build — Create a framework with your query parameters
  3. Validate — Check filters and estimate price
  4. Execute — Purchase and retrieve your data
  5. Analyze — Work with the returned DataFrame

Quick Start

from carbonarc import CarbonArcClient
import pandas as pd

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

Build a Framework

# Define your query
framework = client.explorer.build_framework(
    entities=[{"carc_id": 64719, "representation": "company"}],  # Tesla
    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 before purchasing
price = client.explorer.check_framework_price(framework)
print(f"Price: ${price:.2f}")

Execute and Retrieve Data

# Purchase the framework (charges your account!)
order = client.explorer.buy_frameworks([framework])
framework_id = order['frameworks'][0]

# Retrieve the data
data = client.explorer.get_framework_data(framework_id=framework_id)
df = pd.DataFrame(data['data'])

print(df.head())
ResourceDescription
Library for DevsExplore available data assets
Ontology for DevsFind entities and insights
ID ReferenceUnderstand all ID types
Frameworks OverviewPlatform documentation on frameworks
PaginationHandle large data assets efficiently
Use Cases & RecipesReal-world examples you can copy and adapt
Exporting DataExport to CSV, Excel, Parquet, databases, and cloud
Filters & Date RangesMaster filtering and date options
Error HandlingImplement robust error handling

Need Help?