Skip to main content

Omni Report Definition

Project description

Omni Reports

Omni Reports is a client to request, normalize and consolidate reports from several platforms using a simple, declarative and concise request structure. Behind the scenes, the Omni Report Client will convert the report definition into platform-specific report requests.

The Omni Report Definition is a json-like data structure based on Google Ads Report Definition, accepting several elements to query and segment a report.


To install Omni Reports, use pip:

pip install git+


Create a ReportTypeResolver to resolve report types of each platform (like Google Ads). Then, create a ReportClient and execute your report definition.

from omni_reports.client import ReportClient, ReportTypeResolverBuilder
from omni_reports.google_reports import GoogleAdsReportTypeResolver

resolver = ReportTypeResolverBuilder() \
    .extend(GoogleAdsReportTypeResolver) \

client = ReportClient(resolver)
result = client.execute_report({
    'report_name': 'my_report',
    'selector': {
        'fields': ['account_id', 'cost', 'conversions', 'cost_per_conversion'],
        'predicates': [
                'field': 'cost',
                'operator': 'greater_than',
                'values': ['0']


Additionally, you can pass a context to ReportClient so that a ReportTypeResolver can be configured.

from omni_reports.client import ReportClient
from omni_reports.google_reports import GoogleAdsReportTypeResolver

client = ReportClient(GoogleAdsReportTypeResolver, {

# or via `execute_report`
report_definition = {...}
client.execute_report(report_definition, {

Creating a ReportType

Create a ReportType in Omni Reports is simple. Just create a new class extending ReportType, declare the fields of your report type and implement the resolve method. The ReportClient will validate all definitions of your report type and call the resolver.

To create your report type, you must declare all fields of report with its behaviors and metadata. There is three types of behaviors: attribute, metric and segment.

  • Attribute: The attribute fields must always reflect the current state of your data, ignoring the timespan of the report;
  • Metric: The metric fields reflect the data over the timespan of the report;
  • Segment: The segment field contains dimension data that is used to group metrics. Including a metric field into your report definition may split a single row into multiple rows. The value of metric fields reflect the data over the timespan of the report.

After the identification of the behavior for each report type field, you can start declaring the report type class:

from omni_reports.client import ReportClient, ReportTypeResolverBuilder
from omni_reports.client.types import ReportType
from omni_reports.client.fields import AttributeReportField, MetricReportField, SegmentReportField

class MyAdReportType(ReportType):
    Example of ReportType to query perfomance of all accounts in platform

    account_id = SegmentReportField()
    campaign_id = SegmentReportField()
    ad_group_id = SegmentReportField()
    ad_id = SegmentReportField()

    cost = MetricReportField()
    conversions = MetricReportField()
    cost_per_conversion = MetricReportField()

    campaign_status = AttributeReportField()
    ad_group_status = AttributeReportField()
    ad_status = AttributeReportField()

    def resolve(self, fields, predicates, report_definition, context, client):
        # logic to apply predicates and filter fields
        return []

resolver = ReportTypeResolverBuilder() \
    .add_type("MY_AD_REPORT", MyAdReportType()) \

client = ReportClient(resolver)
    'report_type': 'MY_AD_REPORT',
    'report_name': 'report_name_here',
    'selector': {
        'fields': ['ad_group_id', 'cost', 'conversions', 'cost_per_conversion'],
        'predicates': [
                'field': 'campaign_id',
                'operator': 'equals',
                'values': ['1234']


To contribute, see the CONTRIBUTING guides.



Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

omni_reports-0.0.8.tar.gz (12.0 kB view hashes)

Uploaded source

Built Distribution

omni_reports-0.0.8-py2-none-any.whl (17.4 kB view hashes)

Uploaded py2

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page