Skip to main content

Filters & Date Ranges

Master the filtering options that control when, where, and how your Carbon Arc data is aggregated.

Overview

Every Carbon Arc data query uses filters to define:

Filter TypeControlsOptions
Date ResolutionTime granularityday, week, month, quarter
Location ResolutionGeographic granularityus, state, dma, cbsa, zip, country, ww
Date RangeTime periodstart_date, end_date
AggregationHow values combinesum, mean, median, count, count_distinct

Date Resolution

Controls the time granularity of your data.

OptionDescriptionUse Case
"day"Daily data pointsDetailed trends, short periods
"week"Weekly aggregationSmoothed trends, medium periods
"month"Monthly aggregationStandard reporting, YoY analysis
"quarter"Quarterly aggregationEarnings comparisons, long-term

Examples

# Daily - 31 data points for January
daily_filters = {
    "date_resolution": "day",
    "location_resolution": "us",
    "date_range": {"start_date": "2024-01-01", "end_date": "2024-01-31"}
}

# Monthly - 12 data points for full year
monthly_filters = {
    "date_resolution": "month",
    "location_resolution": "us",
    "date_range": {"start_date": "2024-01-01", "end_date": "2024-12-31"}
}

# Quarterly - 8 data points for 2 years
quarterly_filters = {
    "date_resolution": "quarter",
    "location_resolution": "us",
    "date_range": {"start_date": "2023-01-01", "end_date": "2024-12-31"}
}
tip

Higher granularity (day) = more data points = potentially higher cost. Choose the resolution that matches your analysis needs.

Location Resolution

Controls the geographic granularity of your data.

OptionDescriptionApproximate Rows
"us"United States aggregate1 (national total)
"state"US state-level breakdown50+
"dma"Designated Market Areas210 (TV markets)
"cbsa"Core-Based Statistical Areas900+ (metro areas)
"zip"ZIP code level40,000+
"country"Country-level (international)Varies
"ww"Worldwide aggregate1 (global total)

Data Point Calculation

Data Points ≈ (Time Periods) × (Locations) × (Entities)
ConfigurationCalculationData Points
US + Monthly + 1 Year1 × 12 × 112
State + Monthly + 1 Year50 × 12 × 1600
DMA + Monthly + 1 Year210 × 12 × 12,520
CBSA + Monthly + 1 Year900 × 12 × 110,800
ZIP + Daily + 1 Month40,000 × 30 × 11,200,000
warning

ZIP-level daily data for extended periods can be extremely large and expensive. Always check pricing first!

Date Ranges

Format

Date ranges use YYYY-MM-DD format:

"date_range": {
    "start_date": "2024-01-01",
    "end_date": "2024-12-31"
}

Fixed Date Ranges

# Full year
full_year_2024 = {
    "start_date": "2024-01-01",
    "end_date": "2024-12-31"
}

# Q1 2024
q1_2024 = {
    "start_date": "2024-01-01",
    "end_date": "2024-03-31"
}

# Q2 2024
q2_2024 = {
    "start_date": "2024-04-01",
    "end_date": "2024-06-30"
}

# Q3 2024
q3_2024 = {
    "start_date": "2024-07-01",
    "end_date": "2024-09-30"
}

# Q4 2024
q4_2024 = {
    "start_date": "2024-10-01",
    "end_date": "2024-12-31"
}

Dynamic Date Ranges

For recurring reports, calculate dates relative to today:

from datetime import datetime, timedelta
from dateutil.relativedelta import relativedelta

today = datetime.now()

# Last 30 days
last_30_days = {
    "start_date": (today - timedelta(days=30)).strftime("%Y-%m-%d"),
    "end_date": today.strftime("%Y-%m-%d")
}

# Last 12 months
last_12_months = {
    "start_date": (today - relativedelta(months=12)).strftime("%Y-%m-%d"),
    "end_date": today.strftime("%Y-%m-%d")
}

# Year-to-Date (YTD)
ytd = {
    "start_date": f"{today.year}-01-01",
    "end_date": today.strftime("%Y-%m-%d")
}

Helper Functions

Copy these reusable functions for your projects:

from datetime import datetime, timedelta
from dateutil.relativedelta import relativedelta

def get_last_n_days(n: int) -> dict:
    """Get date range for last N days"""
    today = datetime.now()
    return {
        "start_date": (today - timedelta(days=n)).strftime("%Y-%m-%d"),
        "end_date": today.strftime("%Y-%m-%d")
    }

def get_last_n_months(n: int) -> dict:
    """Get date range for last N months"""
    today = datetime.now()
    return {
        "start_date": (today - relativedelta(months=n)).strftime("%Y-%m-%d"),
        "end_date": today.strftime("%Y-%m-%d")
    }

def get_quarter(year: int, quarter: int) -> dict:
    """Get date range for a specific quarter (1-4)"""
    quarters = {
        1: ("01-01", "03-31"),
        2: ("04-01", "06-30"),
        3: ("07-01", "09-30"),
        4: ("10-01", "12-31")
    }
    start_md, end_md = quarters[quarter]
    return {
        "start_date": f"{year}-{start_md}",
        "end_date": f"{year}-{end_md}"
    }

def get_full_year(year: int) -> dict:
    """Get date range for a full year"""
    return {
        "start_date": f"{year}-01-01",
        "end_date": f"{year}-12-31"
    }

def get_ytd() -> dict:
    """Get year-to-date range"""
    today = datetime.now()
    return {
        "start_date": f"{today.year}-01-01",
        "end_date": today.strftime("%Y-%m-%d")
    }

def get_trailing_twelve_months() -> dict:
    """Get TTM (Trailing Twelve Months) date range"""
    today = datetime.now()
    return {
        "start_date": (today - relativedelta(months=12)).strftime("%Y-%m-%d"),
        "end_date": today.strftime("%Y-%m-%d")
    }

Usage:

# Examples
get_last_n_days(30)           # {'start_date': '2024-01-24', 'end_date': '2024-02-23'}
get_last_n_months(6)          # {'start_date': '2023-08-23', 'end_date': '2024-02-23'}
get_quarter(2024, 1)          # {'start_date': '2024-01-01', 'end_date': '2024-03-31'}
get_full_year(2024)           # {'start_date': '2024-01-01', 'end_date': '2024-12-31'}
get_ytd()                     # {'start_date': '2024-01-01', 'end_date': '2024-02-23'}
get_trailing_twelve_months()  # TTM range

Aggregation Methods

Controls how values are combined when aggregating data.

MethodDescriptionUse Case
"sum"Sum of all valuesTotal revenue, transactions
"mean"Average of valuesAverage order value, rating
"median"Middle valueRobust average (ignores outliers)
"count"Number of recordsTransaction count
"count_distinct"Unique value countUnique customers, locations
Default

If not specified, "sum" is used by default.

Examples

# Total revenue
sum_framework = client.explorer.build_framework(
    entities=[{"carc_id": 64719, "representation": "company"}],
    insight=347,
    filters={...},
    aggregate="sum"
)

# Average order value
mean_framework = client.explorer.build_framework(
    entities=[{"carc_id": 64719, "representation": "company"}],
    insight=347,
    filters={...},
    aggregate="mean"
)

# Unique customer count
distinct_framework = client.explorer.build_framework(
    entities=[{"carc_id": 64719, "representation": "company"}],
    insight=347,
    filters={...},
    aggregate="count_distinct"
)

Custom Filters

Some data assets have dataset-specific filters beyond the standard options:

Filter TypeDataset TypeExample Values
diagnosis_categoryHealthcarerespiratory, cardiovascular
product_categoryRetailelectronics, apparel
merchant_categorySpendrestaurants, travel
platformApp dataios, android

Discovering Custom Filters

# Build a framework first
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-03-31"}
    },
    aggregate="sum"
)

# Get available filters
available_filters = client.explorer.collect_framework_filters(framework)
print(available_filters)
# ['location_resolution', 'date_resolution', 'diagnosis_category', ...]

Exploring Filter Options

# Get options for a specific filter
filter_options = client.explorer.collect_framework_filter_options(
    framework, 
    "diagnosis_category"
)
print(filter_options)
# ['respiratory', 'cardiovascular', 'neurological', ...]

Using Custom Filters

filters = {
    "date_resolution": "month",
    "location_resolution": "state",
    "date_range": {"start_date": "2024-01-01", "end_date": "2024-12-31"},
    "diagnosis_category": "respiratory"  # Custom filter
}

Practical Examples

Trend Analysis (TTM, Monthly, National)

framework = client.explorer.build_framework(
    entities=[{"carc_id": 64719, "representation": "company"}],
    insight=347,
    filters={
        "date_resolution": "month",
        "location_resolution": "us",
        "date_range": get_trailing_twelve_months()
    },
    aggregate="sum"
)

Use for: Executive dashboards, trend identification

Regional Analysis (Quarterly, State-Level)

framework = client.explorer.build_framework(
    entities=[{"carc_id": 64719, "representation": "company"}],
    insight=347,
    filters={
        "date_resolution": "month",
        "location_resolution": "state",
        "date_range": get_quarter(2024, 1)
    },
    aggregate="sum"
)

Use for: Regional performance, territory planning

Daily Momentum (Last 30 Days)

framework = client.explorer.build_framework(
    entities=[{"carc_id": 64719, "representation": "company"}],
    insight=347,
    filters={
        "date_resolution": "day",
        "location_resolution": "us",
        "date_range": get_last_n_days(30)
    },
    aggregate="sum"
)

Use for: Recent momentum, event impact analysis

Year-over-Year Comparison

# Current year
current_year = client.explorer.build_framework(
    entities=[{"carc_id": 64719, "representation": "company"}],
    insight=347,
    filters={
        "date_resolution": "month",
        "location_resolution": "us",
        "date_range": get_full_year(2024)
    },
    aggregate="sum"
)

# Prior year
prior_year = client.explorer.build_framework(
    entities=[{"carc_id": 64719, "representation": "company"}],
    insight=347,
    filters={
        "date_resolution": "month",
        "location_resolution": "us",
        "date_range": get_full_year(2023)
    },
    aggregate="sum"
)

Use for: YoY growth analysis, seasonal patterns

Quick Reference

Complete Filter Object

filters = {
    "date_resolution": "month",           # day, week, month, quarter
    "location_resolution": "state",       # us, state, dma, cbsa, zip, country, ww
    "date_range": {
        "start_date": "2024-01-01",
        "end_date": "2024-12-31"
    },
    # Custom filters (if available for the dataset):
    # "diagnosis_category": "respiratory",
    # "merchant_category": "restaurants"
}

Cheat Sheet

What You NeedDate ResLocation ResTypical Use
High-level trendsmonthusDashboards
Regional breakdownmonthstateTerritory planning
Market analysismonthdmaMedia planning
Metro focusmonthcbsaUrban analysis
Detailed patternsdayusEvent analysis
Maximum detaildayzipHyperlocal

Best Practices

Do

  • Match resolution to analysis period — Short periods use daily/weekly; Long periods use monthly/quarterly
  • Start coarse, then drill down — Begin with "us" + "month", add granularity as needed
  • Check price before finer granularity — ZIP × daily × full year is expensive!
  • Use dynamic date ranges — get_trailing_twelve_months() keeps reports current

Don't

  • Request daily + ZIP for multi-year periods (massive data volume)
  • Assume all data assets support all resolutions
  • Forget to check data availability for your date range

Next Steps