Ontology API

The Ontology API provides programmatic access to Carbon Arc's knowledge graph — explore entities (companies, products, tickers, locations) and insights (metrics and KPIs).

---

Available Methods

Method	Description
client.ontology.get_entity_map()	Get all available entity types/representations
client.ontology.get_entities()	List and filter entities (paginated)
client.ontology.get_insights()	List and filter insights (paginated)
client.ontology.get_entity_information()	Get details for a specific entity
client.ontology.get_insight_information()	Get details for a specific insight
client.ontology.get_entities_for_insight()	Find entities with data for an insight
client.ontology.get_insights_for_entity()	Find insights with data for an entity

---

Quick Start

from carbonarc import CarbonArcClient

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

---

Get Entity Map

Discover all available entity types (representations) in the ontology. This helps you understand what kinds of entities you can query.

entity_map = client.ontology.get_entity_map()

Response Structure

The response is a list of representation objects:

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

print(f"Available entity types: {sorted(representations)}")

Common Representations

Representation	Description
company	Companies (e.g., Tesla, Apple)
ticker	Stock tickers (e.g., TSLA, AAPL)
product	Products and brands
app	Mobile applications
category	Product or industry categories
state	US states
country	Countries
cbsa	Core-Based Statistical Areas (metro regions)
dma	Designated Market Areas

---

List Entities

Get a paginated, filterable list of entities in the ontology.

# Basic usage
response = client.ontology.get_entities()

# Filter by representation
response = client.ontology.get_entities(representation=["company"], page=1, size=100)

Parameters

Parameter	Type	Required	Default	Description
representation	list[str]	No	None	Filter by entity type (e.g., ["company"], ["ticker", "app"])
domain	str or list[str]	No	None	Filter by entity domain
entity	list[str]	No	None	Filter by entity category ("brand", "company", "people", "location")
subject_ids	list[int]	No	None	Filter by subject IDs
topic_ids	list[int]	No	None	Filter by topic IDs
insight_types	list[str]	No	None	Filter by insight type ("metric", "event", "kpi", "marketshare", "cohort")
insight_id	int	No	None	Filter to entities that have this insight
search	str	No	None	Filter entities by keyword/name (e.g., "Tesla")
version	str	No	"latest"	Ontology version
page	int	No	1	Page number (1-indexed)
size	int	No	100	Number of items per page
sort_by	str	No	"label"	Field to sort by
order	str	No	"asc"	Sort direction ("asc" or "desc")

Response Structure

{
  "total": 13551,
  "page": 1,
  "size": 100,
  "pages": 136,
  "entities": [
    {
      "carc_id": 64719,
      "label": "Tesla",
      "representation": "company",
      "entity_domain": "discretionary",
      "entity_domain_label": "Consumer Discretionary"
    }
  ]
}

Example: Find an Entity by Name

Use the search parameter to filter entities by keyword:

response = client.ontology.get_entities(search="Tesla", representation=["company"])
entities = response.get("entities", [])

note

Results are returned as the first page (default size: 100). If your search term is broad and may match many entities, use the page and size parameters to paginate through additional results.

---

List Insights

Get a paginated, filterable list of insights in the ontology. This is useful for discovering available metrics and KPIs — for example, finding all insights of a certain type or all insights that apply to a specific entity.

# Basic usage
response = client.ontology.get_insights()

# Filter by insight type
response = client.ontology.get_insights(insight_types=["metric"], page=1, size=100)

Parameters

Parameter	Type	Required	Default	Description
subject_ids	list[int]	No	None	Filter by subject IDs
topic_ids	list[int]	No	None	Filter by topic IDs
insight_types	list[str]	No	None	Filter by insight type ("metric", "event", "kpi", "marketshare", "cohort")
entity_id	int	No	None	Filter to insights available for this entity
entity_representation	str	No	None	Filter by entity representation
entity_domain	str or list[str]	No	None	Filter by entity domain
entity	str	No	None	Filter by entity category ("brand", "company", "people", "location")
search	str	No	None	Filter insights by keyword/name (e.g., "Revenue")
page	int	No	1	Page number (1-indexed)
size	int	No	100	Number of items per page
sort_by	str	No	"insight_label"	Field to sort by
order	str	No	"asc"	Sort direction ("asc" or "desc")

Response Structure

{
  "total": 850,
  "page": 1,
  "size": 100,
  "pages": 9,
  "items": [
    {
      "insight_id": 302,
      "label": "Accounts Indicator",
      "topic_label": "Accounts",
      "topic_id": 40,
      "subject_label": "Federal Reserve Indicators",
      "subject_id": 15,
      "insight_type": "metric",
      "insight_name": "account_indicator"
    }
  ]
}

Example: Find an Insight by Name

Use the search parameter to filter insights by keyword:

response = client.ontology.get_insights(search="Revenue", insight_types=["metric"])
items = response.get("items", [])

note

Results are returned as the first page (default size: 100). If your search term is broad and may match many insights, use the page and size parameters to paginate through additional results.

---

Get Entity Information

Get detailed information about a specific entity. Requires both the entity_id and representation.

entity_info = client.ontology.get_entity_information(
    entity_id=64719,           # Entity ID (required)
    representation="company"   # Entity type (required)
)

Parameters

Parameter	Type	Required	Description
entity_id	int	Yes	The entity's unique ID (carc_id)
representation	str	Yes	The entity type (company, ticker, product, etc.)

Response Structure

{
  "carc_id": 64719,
  "carc_name": "Tesla Inc.",
  "representation": "company",
  "ticker": "TSLA",
  "sector": "Consumer Cyclical",
  "industry": "Auto Manufacturers"
}

Example: Get Company Details

# Look up Tesla
entity = client.ontology.get_entity_information(
    entity_id=64719,
    representation="company"
)

print(f"Name: {entity.get('carc_name')}")
print(f"ID: {entity.get('carc_id')}")
print(f"Representation: {entity.get('representation')}")

# Additional fields vary by representation type
if 'ticker' in entity:
    print(f"Ticker: {entity.get('ticker')}")
if 'sector' in entity:
    print(f"Sector: {entity.get('sector')}")
if 'industry' in entity:
    print(f"Industry: {entity.get('industry')}")

Finding Entity IDs

You can find entity IDs by:

1. Using get_entities() to browse
2. Using get_entities_for_insight() to find entities with specific metrics
3. Looking up entities in the Carbon Arc platform UI

---

Get Insight Information

Get detailed information about a specific insight (metric/KPI). Insights are the data points you can query for entities.

insight_info = client.ontology.get_insight_information(insight_id=465)

Parameters

Parameter	Type	Required	Description
insight_id	int	Yes	The insight's unique ID

Response Structure

{
  "carc_id": 465,
  "carc_name": "News Event",
  "dataset_id": "CA0035",
  "topic_label": "Legal",
  "insight_type": "metric"
}

Example: Get Insight Details

insight = client.ontology.get_insight_information(insight_id=465)

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

Common Insight Types

Insight Type	Description
metric	Quantitative data (revenue, transactions, users)
dimension	Categorical data (names, labels, categories)
event	Point-in-time occurrences (news events, filings)

---

Get Entities for Insight

Find all entities that have data available for a specific insight. This is useful for discovering which entities you can query for a particular metric.

response = client.ontology.get_entities_for_insight(insight_id=465)

Parameters

Parameter	Type	Required	Description
insight_id	int	Yes	The insight ID to find entities for

Response Structure

{
  "entities": [
    {
      "carc_id": 1784,
      "carc_name": "AGIO",
      "entity": "company",
      "entity_label": "AGIO",
      "entity_domain": "biopharma",
      "entity_representation_name": "ticker",
      "entity_representation_label": "Ticker"
    }
  ]
}

Example: Find Entities with a Metric

# Find all entities with "News Event" data (insight_id=465)
response = client.ontology.get_entities_for_insight(insight_id=465)

entities = response.get('entities', [])

print(f"Found {len(entities)} entities with this insight")
print("-" * 60)

for entity in entities[:20]:
    entity_id = entity.get('carc_id')
    name = entity.get('carc_name')
    domain = entity.get('entity_domain')
    print(f"  {entity_id:<8} | {domain:<12} | {name}")

---

Get Insights for Entity

Find all insights that have data available for a specific entity. This is the inverse of get_entities_for_insight() — use it to discover which metrics you can query for a given company, product, or app before building a framework.

response = client.ontology.get_insights_for_entity(
    entity_id=64719,
    entity_representation="company"
)

Parameters

Parameter	Type	Required	Description
entity_id	int	Yes	The entity ID to find insights for
entity_representation	str	Yes	The entity type (e.g., "company", "ticker", "app")

Response Structure

{
  "insights": [
    {
      "insight_id": 8,
      "insight_name": "ad_spend_per_ad",
      "topic_id": 14,
      "topic_name": "ad"
    }
  ],
  "source_count": 12,
  "subject_count": 5
}

Example: Find Available Metrics for a Company

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

insights = response.get('insights', [])

print(f"Found {len(insights)} insights for this entity")
print("-" * 60)

for insight in insights[:20]:
    insight_id = insight.get('insight_id')
    name = insight.get('insight_name')
    topic = insight.get('topic_name')
    print(f"  {insight_id:<8} | {topic:<15} | {name}")

Verify Before You Buy

Use get_insights_for_entity() and get_entities_for_insight() together to confirm that an entity-insight pair exists before building a framework. Attempting to buy a framework with an invalid combination will result in an error.

---

Pagination

Most ontology endpoints return paginated results. Use the pagination info to iterate through all results:

def get_all_entities(client, page_size=100):
    """Iterate through all entities with pagination."""
    all_entities = []
    page = 1
    
    while True:
        response = client.ontology.get_entities(page=page, size=page_size)
        entities = response.get('entities', [])
        
        if not entities:
            break
            
        all_entities.extend(entities)
        
        if page >= response.get('pages', 1):
            break
            
        page += 1
    
    return all_entities

# Usage
all_entities = get_all_entities(client)
print(f"Total entities retrieved: {len(all_entities)}")

---

Error Handling

Always wrap API calls in try/except blocks:

try:
    entity_info = client.ontology.get_entity_information(
        entity_id=64719,
        representation="company"
    )
    print(f"Found: {entity_info.get('carc_name')}")
except Exception as e:
    print(f"Error: {e}")

---

Complete Workflow Example

Here's a complete workflow demonstrating how to explore the ontology:

import pandas as pd
from carbonarc import CarbonArcClient

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

# ─────────────────────────────────────────────────────────────────
# Step 1: Discover available entity types
# ─────────────────────────────────────────────────────────────────
print("STEP 1: Available Entity Types")
entity_map = client.ontology.get_entity_map()

representations = set()
for item in entity_map:
    rep = item.get('representation')
    if rep:
        representations.add(rep)

print(f"Found {len(representations)} entity types:")
for rep in sorted(representations)[:10]:
    print(f"  • {rep}")

# ─────────────────────────────────────────────────────────────────
# Step 2: Look up a specific entity
# ─────────────────────────────────────────────────────────────────
print("\nSTEP 2: Entity Details")
entity = client.ontology.get_entity_information(
    entity_id=64719,  # Tesla
    representation="company"
)

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

# ─────────────────────────────────────────────────────────────────
# Step 3: Explore an insight
# ─────────────────────────────────────────────────────────────────
print("\nSTEP 3: Insight Details")
insight = client.ontology.get_insight_information(insight_id=465)

print(f"Insight: {insight.get('carc_name')}")
print(f"Dataset: {insight.get('dataset_id')}")
print(f"Topic: {insight.get('topic_label')}")

# ─────────────────────────────────────────────────────────────────
# Step 4: Find entities with this insight
# ─────────────────────────────────────────────────────────────────
print("\nSTEP 4: Entities with this Insight")
entities_response = client.ontology.get_entities_for_insight(insight_id=465)

entities = entities_response.get('entities', [])
print(f"Found {len(entities)} entities")
for entity in entities[:5]:
    print(f"  • {entity.get('carc_name')} ({entity.get('entity_domain')})")

# ─────────────────────────────────────────────────────────────────
# Step 5: Find insights available for an entity (reverse lookup)
# ─────────────────────────────────────────────────────────────────
print("\nSTEP 5: Insights for Tesla")
insights_response = client.ontology.get_insights_for_entity(
    entity_id=64719,
    entity_representation="company"
)

insights = insights_response.get('insights', [])
print(f"Found {len(insights)} insights")
for insight in insights[:5]:
    print(f"  • {insight.get('insight_name')} (ID: {insight.get('insight_id')}, Topic: {insight.get('topic_name')})")

print("\nExploration complete!")

---

Quick Reference

# ─────────────────────────────────────────────────────────────────
# ENTITY MAP - Get available entity types
# ─────────────────────────────────────────────────────────────────
entity_map = client.ontology.get_entity_map()
# Returns: List of representation objects

# ─────────────────────────────────────────────────────────────────
# LIST ENTITIES - Browse and filter entities (paginated)
# ─────────────────────────────────────────────────────────────────
response = client.ontology.get_entities(representation=["company"], page=1, size=100)
# Returns: {total, page, size, pages, entities: [{carc_id, label, representation, entity_domain, ...}]}

# ─────────────────────────────────────────────────────────────────
# LIST INSIGHTS - Browse and filter insights (paginated)
# ─────────────────────────────────────────────────────────────────
response = client.ontology.get_insights(insight_types=["metric"], size=100)
# Returns: {total, page, size, pages, items: [{insight_id, label, insight_type, topic_label, ...}]}

# ─────────────────────────────────────────────────────────────────
# ENTITY DETAILS - Get info for a specific entity
# ─────────────────────────────────────────────────────────────────
entity = client.ontology.get_entity_information(
    entity_id=64719,           # Required
    representation="company"   # Required
)
# Returns: {carc_id, carc_name, representation, ticker, sector, ...}

# ─────────────────────────────────────────────────────────────────
# INSIGHT DETAILS - Get info for a specific insight
# ─────────────────────────────────────────────────────────────────
insight = client.ontology.get_insight_information(insight_id=465)
# Returns: {carc_id, carc_name, dataset_id, topic_label, insight_type}

# ─────────────────────────────────────────────────────────────────
# ENTITIES FOR INSIGHT - Find entities with a specific metric
# ─────────────────────────────────────────────────────────────────
response = client.ontology.get_entities_for_insight(insight_id=465)
# Returns: {entities: [{carc_id, carc_name, entity, entity_domain, ...}]}

# ─────────────────────────────────────────────────────────────────
# INSIGHTS FOR ENTITY - Find metrics available for a specific entity
# ─────────────────────────────────────────────────────────────────
response = client.ontology.get_insights_for_entity(entity_id=64719, entity_representation="company")
# Returns: {insights: [{insight_id, insight_name, topic_id, topic_name}], source_count, subject_count}

---

Next Steps

Once you've explored the Ontology and identified your entities and insights:

1. Use the Library API to understand available data assets
2. Build Frameworks to query and purchase data
3. Set up Scheduled Deliveries for recurring data needs