Skip to main content

Guide: Using the Wildcard in the Carbon Arc Python Package

What is it?​

The wildcard feature (*) allows you to request all entities of a given type (e.g., all companies, all tickers, all locations) without specifying individual carc_ids.

How to Use It​

You can pass a str to the entities argument in build_framework(), and the SDK will automatically format it as a wildcard.

Before getting started, make sure to walk through our Setup Guide to confirm all required dependencies are installed and properly configured.

The guide covers everything from environment setup and authentication to package installation and common troubleshooting tips. Following it ensures your Python SDK runs smoothly and avoids errors related to missing libraries or misconfigured environments.

Below is an example of a properly formatted framework to pull all Product Brands POS Spend the our POS Convenience Store dataset.

framework = {
    "entities": {"carc_name": "*", "representation":"product"}, #Our wildcard is added here next to carc_name
    "insight": {"insight_id": 385 }, #Insight ID for POS Convenience Store Spend
    "filters": {
    "date_resolution": "day", #Sets the date resolution to Daily
    "location_resolution": "us", #Selects US level data
    "date_range": {
      "start_date": "2022-7-12",
      "end_date": "2025-7-11"
        }
    },
    "aggregate": "sum"
}

Check Your Framework Price​

When using a wildcard, it's especially important to validate the estimated price before purchasing. Pulling all entities can result in large queries and higher consumption costs. Always check the framework price to avoid unexpected usage.

price = client.explorer.check_framework_price(framework)
print(price)

Double-Check Your Filters​

Before purchasing your framework, take a moment to review all selected filters. Some datasets include optional or dependent filters — such as panel cuts by geography, cohort, or payment method — that may impact the scope and shape of your results.

Make sure you’ve selected the filters that match your intended use case, especially when working with complex datasets. A quick review can help avoid pulling more data than necessary or missing key segments.

framework_filters = client.explorer.collect_framework_filters(framework)
print("Available filters:")
print(framework_filters)

Purchase and Access Your Framework​

Once you've reviewed your filters and confirmed the price, go ahead and purchase your framework.

After purchasing, you can print your order details to retrieve the framework ID — this is your key reference for all downstream actions.

With your framework ID, you can:

  • Retrieve full metadata for your framework
  • Begin streaming or downloading the associated data
  • Track usage and consumption history tied to that order

This ID will be your anchor point as you move from configuration to insight.

order_information = client.explorer.buy_frameworks([framework])
print(order_information)
framework_id = "INSERT YOUR FRAMEWORK HERE"
framework_metadata = client.explorer.get_framework_metadata(framework_id=framework_id)

Download Your Data​

Once your framework is purchased and your framework ID is collected, you're ready to start downloading your data.

Below is an example command using the Python SDK to pull your framework data into a pandas DataFrame:


import pandas as pd
import os

df = client.explorer.get_framework_data(
    framework_id=framework_id,
    fetch_all=False,
    page=1,
    size=7000,
    data_type="dataframe"
)

# Step 2: Export to CSV
output_file = "framework_sample_wildcard.csv"
df.to_csv(output_file, index=False)

# Step 3: Print full path
print("✅ Exported 7,000 rows to:", os.path.abspath(output_file))

Check Out the Carbon Arc Python Package PyPI Page​

Visit our official PyPI page to reference the latest version of the Carbon Arc Python SDK. This is the home base for our package that allows you to connect directly to the Carbon Arc Platform with just a few lines of code.

More Code​