Digital Platform API - Report service

The Report Service is used to provide access to many different types of reports. It also ensures that each user types can only access the reports that are appropriate for that type. For example, network users have access to all report types, while advertiser and publisher users only have access to a few.

The available metrics vary depending on the report type, but can include how much money was spent on inventory, the number of impressions seen and/or sold, revenue earned, and more. This document describes how to request and download data from the Report Service. It also describes how to get more information about each of the supported report types, as well as providing links to further documentation about each report type.

Report types

REST API for viewing metadata

JSON fields for viewing metadata

The meta array includes the following fields:

Meta data response example (using the network_analytics report)

$ curl -b cookies -c cookies 'https://api.appnexus.com/report?meta=network_analytics'

{
    "response": {
        "status": "OK",
        "meta": {
            "time_granularity": "hourly",
            "columns": [
                {
                    "column": "month",
                    "type": "date"
                },
                {
                    "column": "day",
                    "type": "date"
                },
                {
                    "column": "hour",
                    "type": "date"
                },
                {
                    "column": "buyer_member_id",
                    "type": "int"
                },
                {
                    "column": "seller_member_id",
                    "type": "int"
                },
                {
                    "column": "seller_member_name",
                    "type": "string"
                },
                {
                    "column": "seller_member",
                    "type": "string"
                },
                {
                    "column": "advertiser_id",
                    "type": "int"
                },
                ...
            ],
            "filters": [
                {
                    "column": "hour",
                    "type": "date"
                },
                {
                    "column": "day",
                    "type": "date"
                },
                {
                    "column": "month",
                    "type": "date"
                },
                {
                    "column": "buyer_member_id",
                    "type": "int"
                },
                {
                    "column": "seller_member_id",
                    "type": "int"
                },
                ...
            ],
            "havings": [
                {
                    "column": "imps"
                },
                {
                    "column": "clicks"
                },
                {
                    "column": "cost"
                },
                {
                    "column": "revenue"
                },
                {
                    "column": "booked_revenue"
                },
                {
                    "column": "reseller_revenue"
                },
                {
                    "column": "profit"
                },
                ...
            ],
            "time_intervals": [
                "current_hour",
                "last_hour",
                "last_48_hours",
                "today",
                "yesterday",
                "last_7_days",
                "month_to_date",
                "quarter_to_date",
                "last_month",
                "lifetime",
                "mtd"
            ]
        }
    }
}

REST API for data retrieval

JSON fields for data retrieval

group_filters example

{
"group_filters": [
{
"imps": {
"value": 10000,
"operator": ">="
}
}
]
}

How to run a report?

• Step 1. Create a JSON-formatted report request
• Step 2. POST the request to the Report Service
• Step 3. GET the report status from the Report Service
• Step 4. GET the report data from the Report Download Service

Step 1: Create a JSON-formatted report request

The JSON file should include the specific report_type that you want to run, as well as the columns (dimensions and metrics) and report_interval ("today", "yesterday", "month_to_date", etc.) that you want to retrieve. You can also include filters for dimensions, define granularity (year, month, day), and specify the format in which the data should be returned. The format options are:

• "csv" - Comma-separated file
• "excel" - Tab-separated file
• "xlsx" - Modern XML-compatible Excel format (zipped)

For more details about the fields that can be included in the request, see JSON fields above. For a full list of available dimensions and metrics, see the documentation for the specific report type that you want to run, or pull that report's metadata as described in REST API for Viewing Metadata.

$ cat report_request

{
    "report": {
        "report_type": "network_analytics",
        "report_interval": "last_48_hours",
        "columns": ["day","imps","clicks"],
        "filters": [{"geo_country":"US"}],
        "orders": [{"order_by":"day", "direction":"ASC"},{"order_by":"imps", "direction":"DESC"}],
        "format": "csv"
    }
}

Step 2: POST the request to the Report service

You POST the JSON request and get back a report ID.

$ curl -b cookies -c cookies -X POST -d @report_request 'https://api.appnexus.com/report'

{
    "response": {
        "status": "OK",
        "report_id": "ca9955709eade9a0e89f5cda5345c12r"
    }
}

Alternatively, you can get a Report ID via a POST request using a saved report ID. For more information, see the Saved Report Service:

curl -c cookies -b cookies -X POST 'https://api.appnexus.com/report?saved_report_id=30'

Step 3: GET the report status from the Report service

Make a GET call with the report ID to retrieve the status of the report. Continue making this call until the execution_status is "ready". Then use the report-download service to save the reporting data to a file. (This is described in the next step.)

$ curl -b cookies -c cookies 'https://api.appnexus.com/report?id=ca9955709eade9a0e89f5cda5345c12r'

{
    "response": {
        "status": "OK",
        "report": {
            "name": null,
            "created_on": "2017-03-13 18:15:48",
            "cache_hit": false,
            "fact_cache_hit": false,
            "json_request": "{\"report\":{\"report_type\":\"network_analytics\",\"report_interval\":
                \"last_48_hours\",\"columns\":[\"day\",\"imps\",\"clicks\"],\"filters\":[{\"geo_country\":
                \"US\"},{\"entity_member_id\":\"514\"},{\"entity_member_id\":null}],\"orders\":
                [{\"order_by\":\"day\",\"direction\":\"ASC\"},{\"order_by\":\"imps\",\"direction\":
                \"DESC\"}]}}",
            "header_info": "Report type:,network_analytics\r\n,\r\nRun at:,2017-03-13 18:15:48\r\nStart date:,
                \r\nEnd date:,\r\nTimezone:,\r\nUser:,John Smith (9385)\r\n",
            "report_size": "10",
            "row_count": "35",
            "url": "report-download?id=ca9955709eade9a0e89f5cda5345c12r"
        },
        "execution_status": "ready"
    }
}

Step 4: GET the report data from the Report Download service

To download the report data to a file, make another GET call with the report ID, but this time to the report-download service. You can find the service and report ID in the url field of the previous GET response. When identifying the file that you want to save to, be sure to use the file extension of the "format" that you specified in your initial POST.

curl -i -b cookies -c cookies 'https://api.appnexus.com/report-download?id=ca9955709eade9a0e89f5cda5345c12r' > /tmp/network_analytics.csv

You can then open the csv file using Microsoft Excel or similar software.

Report data size limitations

Report results larger than 15 MB will not be emailed to recipients specified in the JSON request.

Reports that take longer than 15 minutes to process will timeout and return with an error status. This amount of processing time roughly corresponds to 1MM rows of data. If your reports routinely timeout, consider one of the following options:

• Verify that you really need all that data. If you don't, update your report requests with a shorter time interval or fewer dimensions. For tips on preventing reports from being unnecessarily large or taking too long to process, see Reporting Best Practices below.
• If you really do need all of that data, follow the instructions in Report Pagination.

Report throttling

In order to ensure that our systems operate as smoothly as possible for all users, the Report Service throttles report requests at both the member level and the user level. This page describes how the limits are determined, and how we handle requests that exceed the limits defined for each member and each user.

User limits

When a report is submitted by User A, a check is performed to see if User A has submitted 5 report requests in the past 15 minutes that are in pending status or currently being processed. If so, an error is signaled.

Member limits

A given member is limited to n report requests being processed at the same time, where n is determined by the member's contract (This is specified internally by the max_concurrent_reports_processing field on the api.member table.) Any report requests submitted after the limit has been reached are placed in a queue. No warnings or alerts are given.

Example

User- and member-level throttling interact with each other as shown in the following example. Assume that User A and User B are associated with the same member; this member has a limit of 5 concurrent report requests. We assume for this example that the following report requests are all submitted within a 15 minute time span:

Report request # 6 is placed in the queue, since there are already 5 report requests being processed for this member. For the same reason, requests # 6-8 are also placed in the queue. Finally, we can see that request # 9 causes an error to be signaled, since User A has submitted their 6th report request within a 15 minute time span.

Conversion data

Conversions (and related data) in reports are processed asynchronously. As a result, reports are available more quickly, while some conversion-related data is still being processed in the background. For more information, see "Asynchronous Conversion Attribution" on the Availability of Reporting Data page.

Reporting best practices

Here are some tips for preventing your reports from being unnecessarily large or taking a long time to process:

• Shorten the report_interval (e.g., from "lifetime" to "last_48_hours").
• Add more higher-level filters (e.g., for a specific publisher, advertiser, campaign, etc.).
• Avoid combining granular buy-side and sell-side dimensions (e.g., creative and placement), as this increases the number of rows exponentially. If you need to report on such combinations, consider using Bulk Reporting Feeds or the Log-Level Data (LLD) Feeds.

If you must pull large reports that take a long time to process, follow the instructions in Report Pagination.

To determine when a report was last updated, use the Report Status Service.