Reporting API Service

This article covers the new Reporting API services available from August 2020 onwards.

General

Root URL

The root URL for the Report REST/JSON API is: https://api.360yield.com/report

Most URLs mentioned in this document are relative to it. So for example, if the document specifies that a HTTP request needs to be made to the URL /generation-request/search, this means that the full URL of the request should be: https://api.360yield.com/report/generation-request/search. For URLs that don't have this root, the full URL value will be specified

HTTP Request Headers

For most of the HTTP Requests that will be made towards the Report REST/JSON API, the following headers need to be present:

Accept=application/json
Content-Type=application/json
Authorization=Bearer [authorization-token-value]

For instances where the HTTP Request requires different headers, they will be specified there.

Report Generation Request API

The maximum number of rows a report can have is 500k. If the corresponding data were to produce more than 500k rows, only the first 500k are generated and output in the report!

HTTP Method: POST
URL: /report/generation

Request body object:

The root fields of the JSON object used for request body here, ReportGenerationRequest Object, has the following root fields:

{
    "report_type": Required. Text. Allowed values: "DATA_DUMP_FLAT", "QUICK_RTB_FLAT", "DEAL_UI_MONITOR", "ANALYSIS_FLAT", "QR_VIDEO", "AD_REQUEST",
    "report_format":  Optional. Text. Allowed values: "CSV", "EXCEL". Default value: "CSV",
    "currency_id": Optional. Number. Allowed values: 1 through 10. Default value: publisher's currency,
    "date_range": Required. ReportGenerationRequestDateRange Object.
    "dimensions": Required. At most, 10 values allowed. Text (array).  Allowed values: depends on report_type,
    "metrics": Required. Text (array). Allowed values: depends on report_type,
    "column_order": Optional. Text (array). Allowed values: from amongst the values present in "dimensions" and "metrics". Default value: empty,
    "filters": Optional. ColumnOperationValueTriplet Object (array). Default value: empty
}

Here's a simple example of an actual body of a request to generate a report:

{
  "report_type": "ANALYSIS_FLAT",
  "date_range": {
    "quick": "LAST_3_MONTHS"
  },
  "dimensions": [
    "campaign_name"
  ],
  "metrics": [
    "revenue"
  ]
}

The above request will produce a report of type ANALYSIS_FLAT containing your publisher's revenue by campaign, for the last 3 months.

The API Response body for this will look something like this:

{
    "report_generation_id": "a4daa538-2f3e-46db-81d9-12dd212317a3",
    "status_name": "ENQUEUED",
    //...
}

Please see Report Generation Status API section below, for details on how to check the report generation progression, and download the report file (CSV) when finished.

Continuing right below, are details on all the fields that go in the Report Generation Request.

"report_type" field

The UI names of the report types are:

"DATA_DUMP_FLAT" -> Monetisation
"QUICK_RTB_FLAT" -> Programmatic
"DEAL_UI_MONITOR" -> Deals (30 days)
"ANALYSIS_FLAT" -> Analysis
"QR_VIDEO" -> Video
"AD_REQUEST" -> Ad Requests (90 days)

"currency_id" field

Numeric values correspond to the following currencies:

1 EUR
2 USD
3 GBP
4 DKK
5 SEK
6 AUD
7 CZK
9 CHF
10 NOK

"date_range" field

ReportGenerationRequestDateRange Object:

{
    "quick": Text. Allowed values: "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_31_DAYS", "THIS_WEEK", "LAST_WEEK", "LAST_4_WEEKS", "THIS_MONTH", "LAST_MONTH", "LAST_3_MONTHS", "LAST_6_MONTHS",
    "relative": RelativeDateRange object,
    "fixed": FixedDateRange object
}

Only one of "quick", "relative" or "fixed" fields can be populated for a given request.

quick options:

The options available for quick date range are interpreted as follows:

TODAY: current day
YESTERDAY: the day previous to current
LAST_7_DAYS: last 7 full days (before current day, which is not part of the date range in this case)
LAST_31_DAYS: last 31 full days (before current day, which is not part of the date range in this case)
THIS_WEEK: from most recent Monday until current day
LAST_WEEK: last full week, from Monday to Sunday (before current week, which is not part of the date range in this case)
LAST_4_WEEKS: last full 4 weeks, from Monday of the first week to Sunday of the 4th week (before current week, which is not part of the date range in this case)
THIS_MONTH: from the 1rst day of current month, until current day
LAST_3_MONTHS: last full 3 months, from the 1rst day of the first month to the last day of the 3rd month (before current month, which is not part of the date range in this case)
LAST_6_MONTHS: last full 6 months, from the 1rst day of the first month to the last day of the 6th month (before current month, which is not part of the date range in this case)

RelativeDateRange Object:

{
    "from_count": Required. Number greater or equal to 0,
    "from_unit": Required. Text. Allowed values: "DAY", "WEEK", "MONTH",
    "to_count": Required. Number greater or equal to 0,
    "to_unit": Required. Text. Allowed values: "DAY", "WEEK", "MONTH",
}

Here, a value of 0 means current time unit (day/week/month), and 1 means previous time unit, and so on.

For example:

{
    "from_count": 5,
    "from_unit": "DAY",
    "to_count": 0,
    "to_unit": "DAY",
}

Will mean: from five days ago to current day

FixedDateRange Object:

{
    "start_date": Required. Text. Format: yyyy-MM-dd
    "end_date": Required. Text. Format: yyyy-MM-dd. Must be after "start_date"
}

"dimensions" and "metrics" fields

The columns in a report are separated into two categories: dimension and metrics. Dimensions represent columns that will group data (such as "country_id" or "campaign_name"). A Report Generation Request needs to have at least 1 dimension and at most 10 dimensions. Metrics are columns containing aggregated numerical data (such as "revenue" or "clicks") A Report Generation Request needs to have at least 1 metric.

Each type of report has a list of allowed dimensions and metrics.

"dimensions" fields

"dimensions" allowed for DATA_DUMP_FLAT Report

advertiser_category_id : Category ID
advertiser_category_name : Category Name
advertiser_id : Advertiser ID
advertiser_name : Advertiser Name
agency_advertiser_contact : Agency Contact
agency_id : Agency ID
agency_name : Agency Name
auction_rule_id : Auction
buying_type_name : Buying Type
campaign_agency_discount : Agency Discount (%)
campaign_budget : Campaign Budget
campaign_end : Campaign End Date
campaign_id : Campaign ID
campaign_name : Campaign Name
campaign_reference_number : Campaign Reference Number
campaign_start : Campaign Start Date
channel_id : Reporting Channel ID
channel_name : Reporting Channel Name
country_id : Country
creative_creation_date : Creative Creation Date
creative_id : Creative ID
creative_name : Creative Name
creative_size : Creative Size
creative_size_id : Creative Size ID
creative_type_id : Creative Type
day : Day
defaults : Defaults
delivery_schedule_id : Delivery Schedule
demand_optimization_billing : Billing Option
demand_partner_id : Demand Partner ID
demand_partner_name : Demand Partner Name
demand_partner_office_id : Demand Partner Office ID
demand_partner_office_name : Demand Partner Office Name
demand_partner_type_id : Demand Partner Type
device_name : Device Name
frequency_cap : Frequency Cap
impression_cap : Impression Cap
line_item_budget : Line Item Budget
line_item_budget_type : Line Item Budget Type
line_item_end : Line Item End Date
line_item_id : Line Item ID
line_item_name : Line Item Name
line_item_reference_number : Line Item Reference Number
line_item_start : Line Item Start Date
month : Month
operations_contact_id : Account Manager ID
operations_contact_name : Account Manager Name
placement_id : Placement ID
placement_identifier : Placement Identifier
placement_name : Placement Name
placement_reference_number : Placement Reference Number
placement_size_id : Placement Size ID
placement_size_name : Placement Size
placement_type_id : Placement Type
platform_id : Platform Type
pricing_model : Pricing Model
sales_contact : Sales Contact
secondary_campaign_type_id : Campaign Type
secondary_line_item_type_id : Line Item Type
site_id : Site ID
site_name : Site Name
site_platform_id : Site Type
video_format_type_id : Video Format Type
week : Week
year : Year
zone_id : Zone ID
zone_name : Zone Name

"dimensions" allowed for QUICK_RTB_FLAT Report

buying_type_name : Buying Type
campaign_id : Campaign ID
campaign_name : Campaign Name
country_id : Country
day : Day
delivery_schedule_id : Delivery Schedule
demand_partner_id : Demand Partner ID
demand_partner_name : Demand Partner Name
demand_partner_office_id : Demand Partner Office ID
demand_partner_office_name : Demand Partner Office Name
external_buyer_id : External Buyer ID
external_buyer_name : External Buyer Name
line_item_end_time : Line Item End Date
line_item_id : Line Item ID
line_item_name : Line Item Name
line_item_start_time : Line Item Start Date
month : Month
placement_id : Placement ID
placement_name : Placement Name
placement_type_id : Placement Type
platform_id : Platform Type
rtb_advertiser_category_name : RTB Category
rtb_advertiser_name : RTB Advertiser Name
rtb_size_id : Creative Size ID
rtb_size_name : Creative Size
secondary_campaign_type_id : Campaign Type
secondary_line_item_type_id : Line Item Type
site_id : Site ID
site_name : Site Name
site_platform_id : Site Type
technical_provider_id : Technical Provider ID
technical_provider_name : Technical Provider Name
week : Week
year : Year
zone_id : Zone ID
zone_name : Zone Name

"dimensions" allowed for DEAL_UI_MONITOR Report

country_name : Country
date : Date
deal_budget : Deal Budget
deal_end_time : Deal End Time
deal_id : Deal ID
deal_name : Deal Name
deal_start_time : Deal Start Time
deal_status : Deal Status
deal_type : Deal Type
demand_partner_office_id : Demand Partner Office ID
demand_partner_office_name : Demand Partner Office Name
sales_contact : Sales Contact
sub_publisher_id : Subpublisher ID
sub_publisher_name : Subpublisher
technical_provider_id : Technical Provider ID
technical_provider_name : Technical Provider Name

"dimensions" allowed for ANALYSIS_FLAT Report

advertiser_id : Advertiser ID
advertiser_name : Advertiser Name
buyer_id : Buyer ID
buyer_name : Buyer Name
buyer_type : Buyer Type
buying_entity : Buying Entity
buying_type_name : Buying Type
campaign_id : Campaign ID
campaign_name : Campaign Name
campaign_owner : Campaign Owner
campaign_type : Campaign Type
country_id : Country
creative_id : Creative ID
creative_name : Creative Name
day : Day
guaranteed : Guaranteed
line_item_budget : Line Item Budget
line_item_budget_type : Line Item Budget Type
line_item_end : Line Item End Date
line_item_id : Line Item ID
line_item_name : Line Item Name
line_item_start : Line Item Start Date
line_item_type : Line Item Type
month : Month
placement_id : Placement ID
placement_name : Placement Name
placement_type : Placement Type
rtb_advertiser_id : RTB Advertiser ID
rtb_advertiser_name : RTB Advertiser Name
sales_contact : Sales Contact
site_id : Site ID
site_name : Site Name
site_type : Site Type
site_url : Site URL
size : Size
sub_publisher_id : Subpublisher ID
sub_publisher_name : Subpublisher
technical_provider_id : Technical Provider ID
technical_provider_name : Technical Provider Name
video_format : Video Format Type
week : Week
year : Year
zone_id : Zone ID
zone_name : Zone Name

"dimensions" allowed for QR_VIDEO Report

buying_type_name : Buying Type
campaign_id : Campaign ID
campaign_name : Campaign Name
country_id : Country
creative_id : Creative ID
creative_name : Creative Name
day : Day
device_type_id : Device Type
dsp_dimension__buyer_name : Seat Name
error_code : Error Code
error_code_translation : Error Code Translation
foreign_buyer_id : Seat ID
landing_page : Landing Page
line_item_id : Line Item ID
line_item_name : Line Item Name
month : Month
placement_id : Placement ID
placement_name : Placement Name
placement_name : Placement Name
placement_type_id : Placement Type
player_size : Player Size
rtb_advertiser_id : RTB Advertiser ID
rtb_advertiser_name : RTB Advertiser Name
secondary_campaign_type_id : Campaign Type
secondary_line_item_type_id : Line Item Type
site_id : Site ID
site_name : Site Name
size_name : Size
technical_provider_id : Technical Provider ID
technical_provider_name : Technical Provider Name
video_format_type_id : Video Format Type
week : Week
year : Year
zone_id : Zone ID
zone_name : Zone Name

"dimensions" allowed for AD_REQUEST Report

bid_url : Bid URL
bundle_value : Bundle Value
country_id : Country
day : Day
month : Month
placement_id : Placement ID
placement_name : Placement Name
referrer_domain : Referrer Domain
site_id : Site ID
site_name : Site Name
site_type : Site Type
size : Size
tag_type : Tag Type
ua_device : Device Type
week : Week
year : Year

"metrics" fields

"metrics" allowed for DATA_DUMP_FLAT Report

click_based_conversions : Click Based Conversions
click_rate : Click Rate (%)
clicks : Clicks
conversion_rate : Conversion Rate (%)
default_impressions : Default Impressions
ecpc : eCPC
ecpm : eCPM
paid_impressions : Paid Impressions
revenue : Revenue
total_conversions : Total Conversions
total_impressions : Total Impressions
view_based_conversions : View Based Conversions

"metrics" allowed for QUICK_RTB_FLAT Report

avg_bid_cpm : Average Bid CPM
avg_won_cpm : Average Won CPM
ecpm : eCPM
highest_bid : Highest Bid
lost_bids : Lost Bids
lowest_bid : Lowest Bid
revenue : Revenue
total_bids : Total Bids
win_rate : Win Rate
won_bids : Won Bids

"metrics" allowed for DEAL_UI_MONITOR Report

below_the_floor : Below The Floor
bid_requests : Bid Requests
bid_responses : Bid Responses
blacklisted : Blacklisted
ecpm : eCPM
incomplete_response : Incomplete Response
inner_competition : Inner Competition
no_bid : No bid
paid_impressions : Paid Impressions
revenue : Revenue
technical_error : Technical Error
unknown_type : Unknown Type
valid : Valid

"metrics" allowed for ANALYSIS_FLAT Report

clicks : Clicks
default_impressions : Default Impressions
ecpc : eCPC
ecpm : eCPM
failbacks : Failbacks
impressions : Impressions
noads : No Ads
paid_impressions : Paid Impressions
post_click_conversions : Post Click Conversions
post_view_conversions : Post View Conversions
revenue : Revenue
valid_bids : Valid Bids

"metrics" allowed for QR_VIDEO Report

click_based_conversions : Click Based Conversions
clicks : Clicks
close : Close
collapse : Collapse
complete : Complete
creativeview : Creative View
ctr : CTR (%)
ecpm : eCPM
errors : Errors
expand : Expand
fillrate : Fillrate (%)
firstquartile : First Quartile
fullscreen : Full Screen
impressions : Impressions
midpoint : Midpoint
mute : Mute
noads : No Ads
paid_impressions : Paid Impressions
pause : Pause
resume : Resume
revenue : Revenue
rewind : Rewind
rpm : RPM
skip : Skip
start : Start
thirdquartile : Third Quartile
total_inventory : Total Inventory
unmute : Unmute
vcr : VCR (%)
view_based_conversions : View Based Conversions

"metrics" allowed for AD_REQUEST Report

ad_requests : Ad Requests

"filters" field

The "filters" field in the ReportGenerationRequest object must contain an array of ColumnOperationValueTriplet objects. Each of these represent a filter criterion.

The structure of the ColumnOperationValueTriplet object is:

{
    "column": Required. Text. The value here must me one from the dimensions available for that type of report.
    "operation" : Required. Text. Allowed values: "EQUAL", "GREATER_THAN", "GREATER_OR_EQUAL", "LESS_THAN", "LESS_OR_EQUAL", "NOT_EQUAL", "LIKE", "NOT_LIKE", "IN", "NOT_IN"
    "value": Required. Text or Array. Allowed values: depends on values present in "column" and "operation" fields
}

Only some of the dimensions of a given report type are available for filtering.

For some dimensions, there is only a fixed set of values from which you can chose to filter on. For example, the secondary_campaign_type_id dimension (from the QUICK_RTB_FLAT report type), only has a fixed set of 5 numerical values to select from: 1 (meaning "Publisher"), 2 (meaning "House"), etc. For these dimensions, the only available values for the "operation" field are "IN" and "NOT_IN", and the "value" field must be an array containing at least one of the available values.

For example, a filter criterion on secondary_campaign_type_id might look like this:

{
    "column": "secondary_campaign_type_id",
    "operation": "IN",
    "value": [1, 2]
}

For other dimensions, that do not have a fixed set of values, the "operation" field can take any of the possible values except "IN" and "NOT_IN" and the "value" field must have a text or numerical value.

For example, a filtering criterion on campaign_name might look like this:

{
    "column": "campaign_name",
    "operation": "LIKE",
    "value": "video"
}

To get a complete list of what dimensions are available, please use the following end point of the Report API:

HTTP Method: POST
URL: /report/allowed-filters

Request body object:

{
    "report_type": Required. Text. Allowed values: "DATA_DUMP_FLAT", "QUICK_RTB_FLAT", "DEAL_UI_MONITOR", "ANALYSIS_FLAT", "QR_VIDEO", "AD_REQUEST"
}

The response returned by this will contain:

all the dimensions that can be used for filtering for the report type specified in the request. The "column" field contains the technical value that can be used in a ColumnOperationValueTriplet object
what type of data the dimension has (for the purpose of filtering). This dictates what operators are available. For example, a "text" type will support operators such as "EQUAL", "LIKE", "NOT_LIKE", etc, while a type of "NUMBER" will support operations such as "EQUAL", "GREATER_THAN", "LES\S_OR_EQUAL", etc
the "available_values" field, when containing a non-null value, will indicate that this dimension, for the purpose of filtering, only accepts a fixed set of values. As such, when creating a filter criterion for this dimension, the available operations are only "IN" and "NOT_IN", and the criterion value needs to be an array containing at least one of the available values.

Here's a partial example on what a response from this end point looks like. This is for report type "QUICK_RTB_FLAT":

{
    "filters": [
        {
            "title": "Buying Type",
            "type": "ENUM",
            "column": "buying_type_name",
            "available_values": [
                {
                    "display_value": "Always-on deal",
                    "filter_value": "Always-on deal"
                },
                {
                    "display_value": "Classic",
                    "filter_value": "Classic"
                },
                {
                    "display_value": "Deal id",
                    "filter_value": "Deal id"
                },
                {
                    "display_value": "No Buying Type",
                    "filter_value": "NoBuyingType"
                },
                {
                    "display_value": "RTB",
                    "filter_value": "RTB"
                },
                {
                    "display_value": "Universal classic",
                    "filter_value": "Universal classic"
                },
                {
                    "display_value": "Universal deal",
                    "filter_value": "Universal deal"
                }
            ]
        },
        {
            "title": "Campaign ID",
            "type": "NUMBER",
            "column": "campaign_id",
            "available_values": null
        },
        {
            "title": "Campaign Name",
            "type": "TEXT",
            "column": "campaign_name",
            "available_values": null
        },
        {
            "title": "Campaign Type",
            "type": "ENUM",
            "column": "secondary_campaign_type_id",
            "available_values": [
                {
                    "display_value": "House",
                    "filter_value": 2
                },
                {
                    "display_value": "Improve",
                    "filter_value": 4
                },
                {
                    "display_value": "Marketing",
                    "filter_value": 6
                },
                {
                    "display_value": "Publisher",
                    "filter_value": 1
                },
                {
                    "display_value": "System Default",
                    "filter_value": 3
                }
            ]
        }
        ...

Here's an example of a complete Report Generation Request that contains some filter criteria:

{
  "report_type": "QUICK_RTB_FLAT",
  "report_format": "EXCEL",
  "date_range": {
    "relative": {
      "from_count": 5,
      "from_unit": "MONTH",
      "to_count": 0,
      "to_unit": "MONTH"
    }
  },
  "dimensions": [
    "campaign_name",
    "secondary_campaign_type_id"
  ],
    "metrics": [
    "revenue"
  ],
  "filters": [
    {
      "column": "campaign_name",
      "operation": "LIKE",
      "value": "ongoing"
    },
    {
      "column": "secondary_campaign_type_id",
      "operation": "IN",
      "value": [
        "2",
        "4"
      ]
    }
  ],
  "column_order": [
    "campaign_name",
    "secondary_campaign_type_id",
    "revenue"
  ]
}

The filtering declared in this request will behave as follows:

only select campaigns that contain "ongoing" in their name, case INsensitive
AND
only select campaigns of type "2" OR "4"

Report Generation Status API

HTTP Method: GET
URL: /report/generation-status/{{report_generation_id}}

The report_generation_id parameter is obtained when making the initial report generation request. It can be found in the API response, in the "report_generation_id" field, and it's a text value. Please see above section Report Generation Request API for details on how to make a report generation request.

The API response to this request will contain following relevant fields:

{
    "status_name": One of the values ENQUEUED, GENERATING, UPLOADING, FINISHED_OK, FAILED ,
    "error":null or String with error decsription,
    "report_download_url":null or download url to be used when report is ready,
    "rows_processed_count": number of rows in the results when known,
    "requested_date": Date and time indication of generation request submission,
    "started_date": Generation start date and time indiciation,
    "finished_date": Generation finished date and time indication,
    "generation_duration_seconds": generation duration in seconds
}

Report Preview API

HTTP Method: POST
URL: /report/preview

This method can be used to directly obtain up to 500 result rows of a given report request. The rows are returned within the call response as JSON.

Request body object:

The root fields of the JSON object used for request body here, ReportPreviewRequest Object, has the following root fields:

{
    "rows": Number. Allowed values: 1 through 500.
    "report_generation_request": ReportGenerationRequest Object (check the report generation request)
}

The API response to this request has the following structure:

{
    "column_order":[{"id":"dimension_or_metric_id","display":"Dimension / Metric Display Name"},...],
    "rows":[{"dimension_or_metric_id":"value",...}, ...]
}