You are here: Developers > OpenX Platform API > Use Cases > Working with reports

Working with reports

Last updated on July 12, 2017

Accessing Reports via OpenX Reporting API

Even though you can access reports using the OpenX user interface, you may also run these same reports using the OpenX API. You can perform many of the same steps in accessing reports using the API as you would when using the OpenX user interface, with the main difference being that you will only need to make a single API request to configure the date range and attributes you want to see in the report.

If you decide to access reports via the OpenX API, it is assumed you are already intimately familiar with reporting and understand how these reports are configured and generated. If you are unfamiliar with OpenX reporting, please refer to the OpenX Reporting documentation for more detailed information about how reports are managed in the user interface.

To run reports, make the following report object calls:

  1. GET /report/get_reportlist List all reports that are available to you based on your account and user permissions.

    The reports listed by this request typically correspond to the reports available to you in the OpenX UI.

    Sample request:

    curl http://openx_server_name/ox/4.0/report/get_reportlist --cookie "openx3_access_token=token_string"

    Where: token_string is a string of characters returned by the GET request at login. To obtain an openx3_access_token, see the authentication topic.

  2. GET /report/get_report_inputs. Determine the needed parameters for the specified report.

    Sample request for report inputs:

    curl http://openx_server_name/ox/4.0/report/get_report_inputs?report=inv_perf_pub --cookie "openx3_access_token=token_string"

    Where:"required": "1" indicates a parameter that is required when running a report. You can include other values as needed.

  3. GET /report/run. Run the specified report with required and desired URI parameters.

    Available parameters for the report are listed in the response to GET /report/get_report_inputs.

    Recommended run parameters:

    • report. The report code, such as report=adunit_size_sum. You can retrieve the available report codes using the GET /report/get_reportlist call.

    • start_date

      • A specific date in yyyy-mm-dd HH:MM:SS format

        OR

      • An integer for the days backward from today. For example, 7 means "seven days ago" and 0 means "starting today" (inclusive).

    • end_date

      • A specific date in yyyy-mm-dd HH:MM:SS format

        OR

      • A negative integer for the days from now. For example, -7 means "until seven days from now" and 0 means "before today" (exclusive).

    • report_format. The format of the report data to download, such as report_format=csv. Size limitations include:

      • csv. No limitations

      • json. Maximum of 1000 rows

      • pdf. No limitations

      • xls. Maximum of 65,000 rows

    • variable_parameter. (Optional) Depending on the report code, the response from GET /report/get_report_inputs provides additional parameters.

    Sample run request for the InventoryAd space available on a website or app. The basic unit of inventory for OpenX is an ad unit. Detailed Performance report:

    curl http://openx_server_name/ox/4.0/report/run?report=inv_perf_pub&start_date=0&end_date=0&do_break=SiteName,AdUnit,AdUnitSize&report_format=json --cookie "openx3_access_token=token_string"

    Where:

  4. Parse the JSON response for use with your reporting integration.

See also


Authentication Via Client Libraries

Before you can access reports via the OpenX API, you must first be authenticated. You can use an existing OpenX client library or your own library. If you use one of these client libraries, the back-end authentication logic is automatically implemented for you via the client library and you need not perform any OAuth implementation steps. If, however, you choose to write your own client library, you will then need to implement the OAuth authentication logic yourself.

For more detailed information on how to implement authentication logic, refer to the Authentication section.

Running a Report Using the OpenX API

When generating reports, you likely will want to use a program to make these calls on an predetermined automated basis (hourly, daily, weekly, etc.). If, however, you wish to make these API calls manually, or through a browser, then the examples below provide the necessary information for you to make these individual calls through a terminal window or browser.

When making a request using the API, there are a number of parameters you may pass in your request which will present specific information you want displayed in the report. Although there are only a few required input parameters you need to pass in the request, there are a number of other parameters you can include in your request.

Note: : There are two different report formats you can use in your request: CSV & JSON. you can specify the report format by entering format (csv or JSON) in the report_format parameter.

Bid Performance Report Example

One type of report you may wish to run is the Bid Performance Report, which provides insight into bid activity based on inventory, demand, and Private MarketplaceThe packaging, offering, and selling of high quality inventory to a limited set of buyers. Abbreviated as PMP. deal information. This can help you evaluate both Ad Exchange and Private Marketplace performance.

When you make the Bid Performance Report request, the report is generated with different columns based on the input parameters and the breakout columns you have specified.

Report Columns

Column Description
Date The date the report was generated.
PublisherName The name of the publisherAn account type that represents a business with ad space to sell..
PublisherID The ID associated with the publisher.
SiteName The name of the site.
AdUnit The name of the ad unit.
AdUnitID The ID associated with the ad unit.
AdUnitSize The size of the ad unit.
DeliveryMedium The attribute reports off the "Default Delivery MediumThe manner in which an end-user is exposed to ad inventory, such as web or mobile." set at the site level.
DemandPartner The demand side platform the buyerA company that pays a demand partner to purchase ad inventory on OpenX Ad Exchange. is using for the deal.
DemandPartnerID The ID associated with the demand side platform the buyer is using for the deal.
Buyer The Buyer that is represented by the Exchange entity or DSPDemand-side platform, a platform or provider that allows advertisers to manage multiple ad exchange and data exchange accounts through one interface, often in real time. (Demand Partner).
AdvertiserName The AdvertiserIn OpenX, an account type that represents a business that runs advertising campaigns to display ads on websites. represented by the Buyer and owner of the brandA name that represents the product or service being advertised, such as Tide. being advertised.
Domain The domain where the inventory is running (e.g. CNN.com).
DealName The name of the deal.
ExternalDealID The ID associated for the external deal.
DealType The type of deal. Options are: Preferred, Private Auction, WIthin Open Auction.
DealPriority A slider that specifies the relative priorityIndicates which deal or line item should take precedence in the case that multiple deals or line items are eligible to serve for a given ad request. for the deal (1-10; 1=highest, 10=lowest)
DealFloor The price set for the deal.
DealAccountExecutive The sales person for the deal.
DealAccountManager The individual responsible for managing the deal.
PackageName The name of the packageA bundle of targeting criteria for similar inventory segments which you can offer at a predetermined price (typically to facilitate regular sales efforts) and automatically create line items from in OpenX..
PackageID The ID associated with the package.
Country The country associated with the report.
PublisherCurrency The type of currency for the publisher (e.g. USD, Euro)

Note: : It is assumed you have already been authenticated to use the OpenX Platform API. If you are not already authenticated, use your login credentials to log into your OpenX server instance. Also, because these are daily reports, data will be displayed for a day.

The table below lists the different metrics that can be returned in a report.

Report Metrics

Metric Description
Impressions The total number of impressions delivered, excluding PSA, house, and companion ads for the selected date range..
Revenue The total revenue received for this date range.
CPMCost per mille, a pricing method which calculates cost based on the number of impressions (per 1000). Revenue per thousand impressions.
Bid Requests The number of bid requests sent to the demand partnerA company which purchases ad inventory on OpenX Ad Exchange.
Opportunities The number of eligible bid opportunities sent to the demand partner. An opportunity is counted each time the buyer has a chance to win an impressionA single display of an ad on a web page, mobile app, or other delivery medium. For deals, impression is a metric to relay the total number of ads that have served. See also billable impression, forecasted impressions.. For example, if the bid was eligible for two deals of different priority, and had the opportunity to bid in both deals because the first deal did not fell the impression, these would be counted as two opportunities. On the other hand, if the buyer wins the impression from the first deal by meeting the deal criteria, then the second deal does not count as an opportunity
Eligibility Rate = Opportunities/Bid Requests
Bids The number of positive bids.
Bid Rate = (Bids/Bid Requests)
Win Rate = (Impressions/Bid Requests)
Bid Fill Rate = (Impressions/Bid Requests)
Bid CPM (Sum of bid amounts for all bids/bids) x 1000. Average bid for this date range. Includes both winning and losing bids.
Win CPM = (Sum of bid amounts for all winning bids/impressions) x 1000. The average winning bid for this date range.

The examples below illustrate several different types of Bid Performance Reports, each request passing different parameters. This enables you to see how passing these parameters causes the report to display different sets of information.

Note: : Please remember these are daily reports so data will be displayed for a day.

If you would like to generate a Bid Performance Report with no additional optional (breakout) columns displayed, run the following command from your terminal window:

curl '<api_url>'/ox/4.0/report/run?start_date=2016-01-19 10:00:00&end_date=2016-01-19 15:00:00&report_format=csv&report=bid_perf

The table below lists the parameters being passed in this request.

Bid Performance Report w/o Optional Columns Request Values

Parameter Description

Example Value

api_url The URL for the OpenX Reporting API.

http://qa-v2-i24-sspSupply-side platform, a platform or provider that allows publishers to manage and optimize revenue for their inventory from multiple sources, often in real time.-only.api-v4-qa-ca.openx.net

api_client The API client you are using

ox

api_version The version of the API.

4.0

service The type of service.

report

start_date The start date displayed in the report.

2016-01-19 10:00:00

end_date The end date displayed in the report.

2016-01-19 15:00:00

report_format The output format for the report. Options are: CSV, JSON

csv

report The type of report being generated. Options are: Exchange (exch_perf), SSP Revenue (ssp_rev), Bid Performance (bid_perf).

The type of report being generated. Options are: Exchange (exch), SSP Revenue (ssp_rev), Bid Performance (bid_perf).

If, however, you want to generate a Bid Performance Report, but with all optional parameters, run the following command from your terminal window.

curl '<api_url>'/ox/4.0/report/run?start_date=2016-01-19 10:00:00&end_date=2016-01-19 15:00:00&do_break=SiteName,AdUnit,AdUnitSize,DeliveryMedium,DemandPartner,Buyer,AdvertiserName,domain,DealName,DealFloor,PackageName,Country&report_format=csv&report=bid_perf

In this example, note that you are passing the values listed in the table below.

Bid Performance Report w/ Optional Columns Request Values

Parameter Description

Example Value

api_url The URL for the OpenX Reporting API.

http://qa-v2-i24-ssp-only.api-v4-qa-ca.openx.net

api_client The API client you are using

ox

api_version The version of the API.

4.0

service The type of service.

report

start_date The start date displayed in the report.

2016-01-19 10:00:00

end_date The end date displayed in the report.

2016-01-19 15:00:00

do_break The breakout parameters being used in the request.

SiteName, AdUnit, AdUnitSize, DeliveryMedium, DemandPartner, Buyer, AdvertiserName, domain, DealName, DealFloor, PackageName, Country

report_format The output format for the report. Options are CSV and JSON.

csv

report

The type of report.

bid_perf

include_viewability

The viewabilityOpenX uses the Media Ratings Council (MRC) definition unless otherwise noted. According to the MRC, display ads are considered viewable if 50% of their pixels are in view for a minimum of one second, two seconds for video. This applies to both desktop and mobile environments. However, in some situations, you may be able to set your own definition. rate of the selected inventory.

Y

Important: The value is case sensitive and must be a capital Y.

To generate a Bid Performance Report report, and filter on some publishers for which you have
 access, run the following command from your terminal window:

curl '<api_url>'/ox/4.0/report/run?start_date=2016-01-19 10:00:00&end_date=2016-01-19 15:00:00
&do_break=SiteName,AdUnit,AdUnitSize,DeliveryMedium,DemandPartner,Buyer,AdvertiserName,domain,DealName,
DealFloor,PackageName,Country&report_format=csv&pub_id=1610635512,1610636382&report=bid_perf
&include_viewability=Y

Note that you are passing the values listed in the table below as part of the request.

Bid Performance Report Publisher Filters Request Values

Parameter Description

Example Value

api_url The URL for the OpenX Reporting API.

http://qa-v2-i24-ssp-only.api-v4-qa-ca.openx.net

api_client The API client.

ox

api_version The API version.

4.0

service The service used in the request.

report

start_date The start date displayed in the report.

2016-01-19 10:00:00

end_date The end date displayed in the report.

2016-01-19 15:00:00

do_break The breakout parameters being used in the request.

SiteName, AdUnit, AdUnitSize, DeliveryMedium, DemandPartner, Buyer, AdvertiserName, domain, DealName, DealFloor, PackageName, Country

report_format The output format for the report. Options are CSV and JSON.

csv

pub_id

ID of the publishers used in the report.

1610635512, 1610636382

report

The type of report.

bid_perf

Note: When entering dates in the request, the date format must be "YYYY-MM-DD
 HH:MM:SS." Please note that the time displayed is the local time for the server instance.

Making a cURL Request

You may also generate a Bid Performance Report by making a single cURL call. Like the URL example above, this example assumes you are already logged in and authenticated; however, unlike the example above, make sure you take note of the cookie information, as you will need to include this information in your cURL call.

To generate a Bid Performance Report using a single cURL call, enter the following command:

curl '<api_url>'/ox/4.0/report/run?start_date=2016-01-19 10:00:00&end_date=2016-01-19 15:00:00&do_break=SiteName,AdUnit,AdUnitSize,DeliveryMedium,DemandPartner,Buyer,AdvertiserName,domain,DealName,DealFloor,PackageName,Country&report_format=csv&report=bid_perf' -H 'Cookie: openx3_access_token=cf708d438a38193a81c953fc5c7346ca438b056a5e2b9; reports=%7B%22name%22%3A%22600000e0-acc0-fff1-8123-9c5e2e%22%2C%22success%22%3Atrue%2C%22server%22%3A%22qa-mstr-er-ca-01.ca.dc.openx.org%22%2C%22project%22%3A%22New%20External%20Reporting%22%2C%22session_timeout%22%3A21600000%2C%22sessionState%22%3A%220.0000000111489889517bca0cd3b892ee89d916aa612a4c2256dd27f476f117c7a5f5526a22aa41b7.1033.0.1.UTC.wps*_1.0.1.1.New%20External%20Reporting.03CE130C11E4499E44870080EFB525B7.0-1033.1.1_-0.1.0_-1033.1.1_10.1.0.*0%22%2C%22last_reports_session_check%22%3A1453712065071%2C%22dates_selected%22%3A%7B%22prior_start%22%3A%2220160111%22%2C%22prior_end%22%3A%2220160117%22%2C%22start%22%3A%2220160118%22%2C%22end%22%3A%2220160124%22%2C%22start_offset%22%3A7%2C%22end_offset%22%3A1%2C%22prior_start_offset%22%3A14%2C%22prior_end_offset%22%3A8%2C%22id_selected%22%3A%22last_seven_days%22%7D%7D' --compressed

Note: : The following parameters are used in this request.

Bid Performance Report cURL Request Values

Parameter Description

Example Value

api_url The URL for the OpenX Reporting API.

http://qa-v2-i24-ssp-only.api-v4-qa-ca.openx.net

api_client The API client.

ox

api_version The API version.

4.0

service The service used in the request.

report

start_date The start date displayed in the report.

2016-01-19 10:00:00

end_date The end date displayed in the report.

2016-01-19 15:00:00

do_break The breakout parameters being used in the request.

SiteName, AdUnit, AdUnitSize, DeliveryMedium, DemandPartner, Buyer, AdvertiserName, domain, DealName, DealFloor, PackageName, Country

report_format The output format for the report. Options are CSV and JSON.

csv

report

The type of report.

bid_perf

cookie

The session access token and cookie.

openx3_access_token=cf708d438a38193a81c953fc5c7346ca438b056a5e2b9reports=%7B%22name%22%3A%22600000e0-acc0-fff1-8123 9c5e2e%22%2C%22success%22%3Atrue%2C%22server%22%3A%22

Report Status

When making reporting calls like "GET /run/report" via an API client, a report request can return one of the following statuses:

Status Description
QUEUED The report request was received, is in the reporting queue, and will be processed shortly.
RUNNING The report request was received and the report is still running.
OK The report was completed and the results are ready for pickup.

TIME OUT

Indicates a timeout state. Only possible when requesting a JSON report.

Using Report Status

Some users set a timeout for their API requests, and report results are not available before the timeout setting. For this reason, the API was designed to provide the current status before the report has completed.

If the status is QUEUED or RUNNING, you can request the same report again (without changing any parameters). This causes the report to provide the data as soon as the first request completes.

Note: If you change any parameters and request the same report again, it creates a new request, causing it to queue, run, and complete again.

Working with a Completed Report

Once you have structured your request and selected your output format (CSV or JSON), the API will process the request and return raw data based on the selected input parameters. You can then use this data in your preferred visualization tool (e.g. Excel, Word, etc.) to sort and analyze the data.

Feedback form