ID Reference

This guide explains all the different ID types used in the Carbon Arc platform and how to retrieve them. Use this as a quick reference when building integrations or exploring the data catalog.

ID Types Overview

ID Type	Format	Example	Source
Dataset ID	String	`"CA0056"`	`get_datasets()`
Topic ID	Integer	`1`, `2`, `3`	`get_dataset_information()`
Insight ID	Integer	`465`, `78857`	`get_insight_information()`
Entity ID	Integer	`64719`	`get_entities()`
Representation	String	`"company"`, `"ticker"`	`get_entity_map()`
Subject	String	`"Consumer Spend"`	`get_datasets() → data.Subjects`

How They Connect

Dataset (CA0056)
   └── Topics (entity_topic_id: 1, 2, 3...)
         └── Insights (insight_id: 465, 78857...)
               └── Entities (carc_id: 64719 + representation: "company")

Dataset ID

Format: String (e.g., "CA0001", "CA0056")

Dataset IDs identify unique data sources in the Carbon Arc library. They follow the pattern CA followed by a 4-digit number.

How to Get All Dataset IDs

from carbonarc import CarbonArcClient
import pandas as pd

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

# Get all datasets
response = client.data.get_datasets()

# Extract datasources
datasets = response.get('datasources', [])

# Build a reference table
for ds in datasets:
    ds_id = ds.get('dataset_id', 'N/A')
    # Handle list format
    if isinstance(ds_id, list):
        ds_id = ds_id[0] if ds_id else 'N/A'
    
    ds_name = ds.get('dataset_name', 'N/A')
    print(f"{ds_id}: {ds_name}")

Response Fields

Field	Type	Description
`dataset_id`	string/list	Unique identifier (e.g., "CA0056")
`dataset_name`	string	Human-readable name
`description`	string	Dataset description
`provider_name`	string	Data provider
`data.Subjects`	list	Subject categories
`data.Topics`	list	Topic names (preview)
`data.Key Metrics`	list	Available metrics

Topic ID (entity_topic_id)

Format: Integer (e.g., 1, 2, 3)

Topics are sub-categories within a data asset. Each data asset has one or more topics, and each topic has a unique entity_topic_id within that data asset.

How to Get Topic IDs for a Dataset

# Get dataset information including topics
dataset_info = client.data.get_dataset_information(dataset_id="CA0056")

# Extract topics
topics = dataset_info.get('entity_topics', [])

for topic in topics:
    topic_id = topic.get('entity_topic_id')
    topic_label = topic.get('entity_topic_label')
    print(f"  entity_topic_id: {topic_id} → {topic_label}")

Example Output

entity_topic_id: 1 → Core Panel
entity_topic_id: 2 → by Payment Method
entity_topic_id: 3 → by Demographics

Usage

Topic IDs are used to filter Library calls:

# Get data dictionary for a specific topic
data_dict = client.data.get_data_dictionary(
    dataset_id="CA0056",
    entity_topic_id=1  # Filter to "Core Panel"
)

# Get sample data for a specific topic
sample = client.data.get_data_sample(
    dataset_id="CA0056",
    entity_topic_id=1
)

Insight ID

Format: Integer (e.g., 465, 78857)

Insights are metrics or KPIs that can be queried for entities. Each insight has a unique ID and is associated with a data asset and topic.

How to Look Up an Insight

# Get insight details by ID
insight = client.ontology.get_insight_information(insight_id=465)

print(f"Insight ID:   {insight.get('carc_id')}")
print(f"Name:         {insight.get('carc_name')}")
print(f"Dataset:      {insight.get('dataset_id')}")
print(f"Topic:        {insight.get('topic_label')}")
print(f"Type:         {insight.get('insight_type')}")

Response Fields

Field	Type	Description
`carc_id`	integer	The insight ID
`carc_name`	string	Insight name (e.g., "News Event")
`dataset_id`	string	Associated data asset
`topic_label`	string	Associated topic
`insight_type`	string	Type (metric, dimension, event)

Download Insight IDs

Use the button below to download a static CSV of Insight IDs and their mapped metrics for easier reference.

Download Insight IDs CSV

Entity ID (carc_id)

Format: Integer (e.g., 64719)

Entities are real-world objects like companies, products, apps, or locations. Each entity has a unique carc_id and a representation (type).

How to Get Entity Information

# Get entity details - requires both ID and representation
entity = client.ontology.get_entity_information(
    entity_id=64719,           # Tesla's carc_id
    representation="company"   # Entity type
)

print(f"Entity ID:      {entity.get('carc_id')}")
print(f"Name:           {entity.get('carc_name')}")
print(f"Representation: {entity.get('representation')}")
print(f"Ticker:         {entity.get('ticker', 'N/A')}")

Browsing Entities

# List entities (paginated)
response = client.ontology.get_entities(page=1, size=100)

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

Finding Entities with a Specific Insight

# Get all entities that have data for insight 465
response = client.ontology.get_entities_for_insight(insight_id=465)

entities = response.get('entities', [])
print(f"Total entities: {len(entities)}")
for entity in entities[:10]:
    print(f"  {entity.get('carc_id')}: {entity.get('carc_name')}")

Finding Insights for a Specific Entity

# Get all insights available for entity 64719 (Tesla)
response = client.ontology.get_insights_for_entity(entity_id=64719, entity_representation="company")

insights = response.get('insights', [])
print(f"Total insights: {len(insights)}")
for insight in insights[:10]:
    print(f"  {insight.get('insight_id')}: {insight.get('insight_name')} (Topic: {insight.get('topic_name')})")

Representation (Entity Type)

Format: String (e.g., "company", "ticker", "product")

Representations define the type/category of an entity. They are required when looking up entity information.

How to Get All Representations

# Get entity map with all representations
entity_map = client.ontology.get_entity_map()

# Extract unique representations
representations = set()
for item in entity_map:
    if isinstance(item, dict):
        rep = item.get('representation')
        if rep:
            representations.add(rep)

print("Available representations:")
for rep in sorted(representations):
    print(f"  - {rep}")

Common Representations

Representation	Description	Example Entities
`company`	Companies	Tesla, Apple, Amazon
`ticker`	Stock tickers	TSLA, AAPL, AMZN
`product`	Products/brands	iPhone, Model 3
`app`	Mobile apps	Instagram, TikTok
`category`	Categories	Electronics, Apparel
`state`	US States	California, Texas
`country`	Countries	USA, China
`cbsa`	Metro regions	New York-Newark-Jersey City
`dma`	Designated Market Areas	Los Angeles

Subject

Format: String (e.g., "Consumer Spend", "App Usage")

Subjects are high-level categories that describe what type of data a data asset contains. They help you find relevant data assets.

How to Get All Subjects

# Get all datasets and extract subjects
response = client.data.get_datasets()
datasets = response.get('datasources', [])

# Collect all unique subjects
all_subjects = set()
subject_to_datasets = {}

for ds in datasets:
    ds_id = ds.get('dataset_id', 'N/A')
    if isinstance(ds_id, list):
        ds_id = ds_id[0]
    
    subjects = ds.get('data', {}).get('Subjects', [])
    
    for subject in subjects:
        all_subjects.add(subject)
        if subject not in subject_to_datasets:
            subject_to_datasets[subject] = []
        subject_to_datasets[subject].append(ds_id)

# Display subjects with their datasets
for subject in sorted(all_subjects):
    datasets = subject_to_datasets[subject]
    print(f"{subject}: {', '.join(datasets[:3])}...")

Common Subjects

Subject	Description
Consumer Spend	Credit card and transaction data
App Usage	Mobile app engagement data
Web Traffic	Website analytics
Location Visits	Foot traffic and geolocation
Employment	Job postings and workforce data
Social Media	Social platform metrics

Quick Reference Card

┌─────────────────────────────────────────────────────────────────┐
│                    CARBON ARC ID QUICK REFERENCE                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  DATASET ID                                                     │
│    Format:  "CA0001", "CA0056"                                  │
│    Get:     client.data.get_datasets()                          │
│                                                                 │
│  TOPIC ID (entity_topic_id)                                     │
│    Format:  1, 2, 3 (integer)                                   │
│    Get:     client.data.get_dataset_information(dataset_id)     │
│                                                                 │
│  INSIGHT ID                                                     │
│    Format:  465, 78857 (integer)                                │
│    Get:     client.ontology.get_insight_information(insight_id) │
│                                                                 │
│  ENTITY ID (carc_id)                                            │
│    Format:  64719 (integer)                                     │
│    Get:     client.ontology.get_entities()                      │
│    Lookup:  client.ontology.get_entity_information(             │
│               entity_id=64719, representation="company")        │
│                                                                 │
│  REPRESENTATION                                                 │
│    Format:  "company", "ticker", "product"                      │
│    Get:     client.ontology.get_entity_map()                    │
│                                                                 │
│  SUBJECT                                                        │
│    Format:  "Consumer Spend", "App Usage"                       │
│    Get:     client.data.get_datasets() → data.Subjects          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Migrating APIs

Users transitioning from the 1.0 Platform to Carbon Arc's 2.0 Platform can use this guide to adapt and update their existing code.

Download API Mapping CSV

Walkthrough Video

Migrate previous 1.0 APIs to the 2.0 Platform:

Filter on API Name or Insight Name to find your matching object
Use Feed Name to help you locate the Metric(s) you want
Replace legacy table access with the new Insight ID via the Python SDK

Next Steps

Library for Devs — Explore data assets and their structure
Ontology for Devs — Search for entities and insights