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",...}, ...]
}