py2adobe-reporting 1.0.0

Data Engineering tool for accessing Adobe CJA Reporting API

py2adobe_reporting

A Python wrapper for Adobe Customer Journey Analytics (CJA) Reporting API and Adobe Experience Platform (AEP) Data Distiller access that enables analysts to extract and analyze data programmatically.

New in v1.0.0

JSON Extractor Tool

A visual web-based tool that extracts table and visualization metadata from Adobe CJA Analysis Workspace projects and automatically generates API request bodies.

• Import Workspace Projects – Fetch any project by ID and extract all metadata
• 10+ Visualization Types – Generates request bodies for Freeform Tables, Area Charts, Bar Charts, Key Metric Summary, and more
• Smart Source Resolution – Visualizations automatically inherit data from linked source tables
• Component Mining – Recursively extracts all segments, metrics, dimensions, and date ranges
• Modern UI – Dark theme with color-coded badges and collapsible sections

from py2adobe_reporting.cja_functions.reporting_management import Reporting

reporting = Reporting()
url = reporting.json_extractor_launch(headers)
# Browser opens to the JSON Extractor UI

# When done:
reporting.json_extractor_stop()

See JSON Extractor Documentation for full details.

Features

• Time Series Reports - Flexible time-based reports with configurable granularity (minute, hour, day, week, month, quarter, year)
• Multi-Metric Analysis - Pull multiple metrics in a single report
• Dimension Breakdowns - Break down metrics by two dimensions simultaneously
• Segmentation Support - Segment your data for your reports to tailor your analysis
• Top Items Analysis - Get top 10 dimension items with optional search
• Pagination Support - Handle large datasets with automatic pagination (up to 50,000 rows per page)
• Component Discovery - List available segments, metrics, dimensions, and calculated metrics for a data view
• JSON Extractor Tool - Visual UI for extracting request bodies from Analysis Workspace projects
• Data Distiller Access - Connect to AEP Data Distiller databases and run SQL queries into pandas DataFrames
• Server-to-Server Authentication - Secure OAuth 2.0 authentication

Installation

pip install py2adobe_reporting

Or install from source:

git clone https://github.com/jaytmii/py2adobe_reporting_package.git
cd py2adobe_reporting_package
pip install -e .

Requirements

• Python >= 3.8
• Adobe CJA API credentials (OAuth 2.0 Server-to-Server)
• SQLAlchemy and a PostgreSQL-compatible driver for Data Distiller access

Quick Start

1. Set Up Authentication

Create a JSON configuration file with your Adobe credentials:

{
  "client_secret": "your-client-secret",
  "company_id": "your-company-id",
  "ims_host": "ims",
  "token_url": "token_url",
  "default_headers": {
    "x-api-key": "your-api-key",
    "x-gw-ims-org-id": "your-org-id"
  },
  "scopes": "api_scopes",
"db_user": "your-db-username",
"db_password": "your-db-password",
"db_host": "your-db-host",
"db_port": "5432",
"db_name": "your-db-name"
}

2. Authenticate

from py2adobe_reporting.auth import s2s_auth

# Authenticate and get environment object
env = s2s_auth("path/to/config.json")

3. Generate Headers

from py2adobe_reporting.auth import cja_oauth_headers

# Create headers for API calls
headers = cja_oauth_headers("path/to/config.json", env.token)

4. Pull a Report

from py2adobe_reporting.cja_functions.reporting_management import Reporting

# Initialize reporting class
reporting = Reporting()

# Get daily time series report
df = reporting.get_granularity_report(
    headers=headers,
    data_view_id="your-data-view-id",
    start_date="2024-01-01",
    end_date="2024-01-31",
    dimension_id="variables/daterangeday",
    metric_id="metrics/visits",
    granularity="day"
)

print(df.head())

Available Functions

Core Reporting Methods

• get_granularity_report() - Time-series reports with configurable granularity
• get_all_rows_report() - All rows for a dimension with single or multiple metrics
• get_breakdown_report() - Break down metrics by two dimensions simultaneously
• get_top_ten_dimension_items() - Get top 10 items for a dimension with optional search

Component Discovery

• component_reports() - Get available segments, dimensions, metrics for a data view
• component_lookup() - Map component IDs to names with automatic deduplication

Low-Level Utilities

• get_single_call_report() - Single API call with custom request body
• get_total_table_rows() - Get total row count for a report configuration
• get_total_table_pages() - Calculate total pages needed

JSON Extractor

• json_extractor_launch() - Launch the visual JSON extractor UI
• json_extractor_stop() - Stop the extractor server

Data Distiller

• DataDistillerAuth.connect_to_db() - Build a SQLAlchemy engine for AEP Data Distiller
• query_aep_sandbox_database_table() - Execute SQL and return a pandas DataFrame

Documentation

For detailed function parameters and examples, see:

• Reporting Management Documentation
• JSON Extractor Documentation

Data Distiller Quick Start

from py2adobe_reporting.auth import DataDistillerAuth
from py2adobe_reporting.cja_functions.reporting_management import Reporting

# Build DB engine from config file db_* keys
dd_auth = DataDistillerAuth("path/to/config.json")
engine = dd_auth.connect_to_db()

reporting = Reporting()
df = reporting.query_aep_sandbox_database_table(
    engine,
    "SELECT * FROM your_schema.your_table LIMIT 100"
)

print(df.head())

Example Use Cases

Get Daily Visits

df = reporting.get_granularity_report(
    headers=headers,
    data_view_id="dv_123",
    start_date="2024-01-01",
    end_date="2024-01-31",
    dimension_id="variables/daterangeday",
    metric_id="metrics/visits",
    granularity="day"
)

Get Monthly Visits

df = reporting.get_granularity_report(
    headers=headers,
    data_view_id="dv_123",
    start_date="2024-01-01",
    end_date="2024-12-31",
    dimension_id="variables/daterangemonth",
    metric_id="metrics/visits",
    granularity="month"
)

Get All Rows for a Dimension

df = reporting.get_all_rows_report(
    headers=headers,
    data_view_id="dv_123",
    start_date="2024-01-01",
    end_date="2024-01-31",
    dimension_id="variables/page",
    metric_id="metrics/visits"
)

Pull Multiple Metrics

df = reporting.get_all_rows_report(
    headers=headers,
    data_view_id="dv_123",
    start_date="2024-01-01",
    end_date="2024-01-31",
    dimension_id="variables/page",
    metric_ids=["metrics/visits", "metrics/orders", "metrics/revenue"],
    multiple_metrics=True
)

Breakdown by Multiple Dimensions

df = reporting.get_breakdown_report(
    headers=headers,
    data_view_id="dv_123",
    start_date="2024-01-01",
    end_date="2024-01-31",
    dimension_id="variables/page",
    metric_id="metrics/visits",
    breakdown_dimension="variables/browser",
    segment_included=True,
    segment=["segment_id_123"]
)

Search for Dimension Items

df = reporting.get_top_ten_dimension_items(
    headers=headers,
    data_view_id="dv_123",
    start_date="2024-01-01",
    end_date="2024-01-31",
    dimension="variables/page",
    search_type="contain",
    contains_term="( CONTAINS 'product' )"
)

Discover Available Components

segments, dimensions, metrics, calc_metrics = reporting.component_reports(
    headers=headers,
    data_view_id="dv_123"
)
print(dimensions)  # View available dimensions
print(metrics)     # View available metrics

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

James Mitchell - [e-mail]