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": Text Allowed values: "DATA_DUMP_FLAT" "QUICK_RTB_FLAT" "DEAL_UI_MONITOR" "ANALYSIS_FLAT" "QR_VIDEO" "AD_REQUEST"
"report_format": Text Allowed values: "CSV" "EXCEL" value: "CSV"
"currency_id": Number Allowed values: 1 through 10. value: publisher's currency
"date_range": ReportGenerationRequestDateRange
"dimensions": At most 10 values allowed Text (array) Allowed values: depends on report_type
"metrics": Text (array) Allowed values: depends on report_type
"column_order": Text (array) Allowed values: from amongst the values present in "dimensions" and "metrics" Default value: empty
"filters": 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": 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": object
"fixed": 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 dayYESTERDAY
: the day previous to currentLAST_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 dayLAST_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 dayLAST_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": Number greater or equal to 0
"from_unit": Text Allowed values: "DAY" "WEEK" "MONTH"
"to_count": Number greater or equal to 0
"to_unit": 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": Text Format: yyyy-MM-dd
"end_date": 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 IDadvertiser_category_name
: Category Nameadvertiser_id
: Advertiser IDadvertiser_name
: Advertiser Nameagency_advertiser_contact
: Agency Contactagency_id
: Agency IDagency_name
: Agency Nameauction_rule_id
: Auctionbuying_type_name
: Buying Typecampaign_agency_discount
: Agency Discount (%)campaign_budget
: Campaign Budgetcampaign_end
: Campaign End Datecampaign_id
: Campaign IDcampaign_name
: Campaign Namecampaign_reference_number
: Campaign Reference Numbercampaign_start
: Campaign Start Datechannel_id
: Reporting Channel IDchannel_name
: Reporting Channel Namecountry_id
: Countrycreative_creation_date
: Creative Creation Datecreative_id
: Creative IDcreative_name
: Creative Namecreative_size
: Creative Sizecreative_size_id
: Creative Size IDcreative_type_id
: Creative Typeday
: Daydefaults
: Defaultsdelivery_schedule_id
: Delivery Scheduledemand_optimization_billing
: Billing Optiondemand_partner_id
: Demand Partner IDdemand_partner_name
: Demand Partner Namedemand_partner_office_id
: Demand Partner Office IDdemand_partner_office_name
: Demand Partner Office Namedemand_partner_type_id
: Demand Partner Typedevice_name
: Device Namefrequency_cap
: Frequency Capimpression_cap
: Impression Capline_item_budget
: Line Item Budgetline_item_budget_type
: Line Item Budget Typeline_item_end
: Line Item End Dateline_item_id
: Line Item IDline_item_name
: Line Item Nameline_item_reference_number
: Line Item Reference Numberline_item_start
: Line Item Start Datemonth
: Monthoperations_contact_id
: Account Manager IDoperations_contact_name
: Account Manager Nameplacement_id
: Placement IDplacement_identifier
: Placement Identifierplacement_name
: Placement Nameplacement_reference_number
: Placement Reference Numberplacement_size_id
: Placement Size IDplacement_size_name
: Placement Sizeplacement_type_id
: Placement Typeplatform_id
: Platform Typepricing_model
: Pricing Modelsales_contact
: Sales Contactsecondary_campaign_type_id
: Campaign Typesecondary_line_item_type_id
: Line Item Typesite_id
: Site IDsite_name
: Site Namesite_platform_id
: Site Typevideo_format_type_id
: Video Format Typeweek
: Weekyear
: Yearzone_id
: Zone IDzone_name
: Zone Name
"dimensions" allowed for QUICK_RTB_FLAT Report
buying_type_name
: Buying Typecampaign_id
: Campaign IDcampaign_name
: Campaign Namecountry_id
: Countryday
: Daydelivery_schedule_id
: Delivery Scheduledemand_partner_id
: Demand Partner IDdemand_partner_name
: Demand Partner Namedemand_partner_office_id
: Demand Partner Office IDdemand_partner_office_name
: Demand Partner Office Nameexternal_buyer_id
: External Buyer IDexternal_buyer_name
: External Buyer Nameline_item_end_time
: Line Item End Dateline_item_id
: Line Item IDline_item_name
: Line Item Nameline_item_start_time
: Line Item Start Datemonth
: Monthplacement_id
: Placement IDplacement_name
: Placement Nameplacement_type_id
: Placement Typeplatform_id
: Platform Typertb_advertiser_category_name
: RTB Categoryrtb_advertiser_name
: RTB Advertiser Namertb_size_id
: Creative Size IDrtb_size_name
: Creative Sizesecondary_campaign_type_id
: Campaign Typesecondary_line_item_type_id
: Line Item Typesite_id
: Site IDsite_name
: Site Namesite_platform_id
: Site Typetechnical_provider_id
: Technical Provider IDtechnical_provider_name
: Technical Provider Nameweek
: Weekyear
: Yearzone_id
: Zone IDzone_name
: Zone Name
"dimensions" allowed for DEAL_UI_MONITOR Report
country_name
: Countrydate
: Datedeal_budget
: Deal Budgetdeal_end_time
: Deal End Timedeal_id
: Deal IDdeal_name
: Deal Namedeal_start_time
: Deal Start Timedeal_status
: Deal Statusdeal_type
: Deal Typedemand_partner_office_id
: Demand Partner Office IDdemand_partner_office_name
: Demand Partner Office Namesales_contact
: Sales Contactsub_publisher_id
: Subpublisher IDsub_publisher_name
: Subpublishertechnical_provider_id
: Technical Provider IDtechnical_provider_name
: Technical Provider Name
"dimensions" allowed for ANALYSIS_FLAT Report
advertiser_id
: Advertiser IDadvertiser_name
: Advertiser Namebuyer_id
: Buyer IDbuyer_name
: Buyer Namebuyer_type
: Buyer Typebuying_entity
: Buying Entitybuying_type_name
: Buying Typecampaign_id
: Campaign IDcampaign_name
: Campaign Namecampaign_owner
: Campaign Ownercampaign_type
: Campaign Typecountry_id
: Countrycreative_id
: Creative IDcreative_name
: Creative Nameday
: Dayguaranteed
: Guaranteedline_item_budget
: Line Item Budgetline_item_budget_type
: Line Item Budget Typeline_item_end
: Line Item End Dateline_item_id
: Line Item IDline_item_name
: Line Item Nameline_item_start
: Line Item Start Dateline_item_type
: Line Item Typemonth
: Monthplacement_id
: Placement IDplacement_name
: Placement Nameplacement_type
: Placement Typertb_advertiser_id
: RTB Advertiser IDrtb_advertiser_name
: RTB Advertiser Namesales_contact
: Sales Contactsite_id
: Site IDsite_name
: Site Namesite_type
: Site Typesite_url
: Site URLsize
: Sizesub_publisher_id
: Subpublisher IDsub_publisher_name
: Subpublishertechnical_provider_id
: Technical Provider IDtechnical_provider_name
: Technical Provider Namevideo_format
: Video Format Typeweek
: Weekyear
: Yearzone_id
: Zone IDzone_name
: Zone Name
"dimensions" allowed for QR_VIDEO Report
buying_type_name
: Buying Typecampaign_id
: Campaign IDcampaign_name
: Campaign Namecountry_id
: Countrycreative_id
: Creative IDcreative_name
: Creative Nameday
: Daydevice_type_id
: Device Typedsp_dimension__buyer_name
: Seat Nameerror_code
: Error Codeerror_code_translation
: Error Code Translationforeign_buyer_id
: Seat IDlanding_page
: Landing Pageline_item_id
: Line Item IDline_item_name
: Line Item Namemonth
: Monthplacement_id
: Placement IDplacement_name
: Placement Nameplacement_name
: Placement Nameplacement_type_id
: Placement Typeplayer_size
: Player Sizertb_advertiser_id
: RTB Advertiser IDrtb_advertiser_name
: RTB Advertiser Namesecondary_campaign_type_id
: Campaign Typesecondary_line_item_type_id
: Line Item Typesite_id
: Site IDsite_name
: Site Namesize_name
: Sizetechnical_provider_id
: Technical Provider IDtechnical_provider_name
: Technical Provider Namevideo_format_type_id
: Video Format Typeweek
: Weekyear
: Yearzone_id
: Zone IDzone_name
: Zone Name
"dimensions" allowed for AD_REQUEST Report
bid_url
: Bid URLbundle_value
: Bundle Valuecountry_id
: Countryday
: Daymonth
: Monthplacement_id
: Placement IDplacement_name
: Placement Namereferrer_domain
: Referrer Domainsite_id
: Site IDsite_name
: Site Namesite_type
: Site Typesize
: Sizetag_type
: Tag Typeua_device
: Device Typeweek
: Weekyear
: Year
"metrics" fields
"metrics" allowed for DATA_DUMP_FLAT Report
click_based_conversions
: Click Based Conversionsclick_rate
: Click Rate (%)clicks
: Clicksconversion_rate
: Conversion Rate (%)default_impressions
: Default Impressionsecpc
: eCPCecpm
: eCPMpaid_impressions
: Paid Impressionsrevenue
: Revenuetotal_conversions
: Total Conversionstotal_impressions
: Total Impressionsview_based_conversions
: View Based Conversions
"metrics" allowed for QUICK_RTB_FLAT Report
avg_bid_cpm
: Average Bid CPMavg_won_cpm
: Average Won CPMecpm
: eCPMhighest_bid
: Highest Bidlost_bids
: Lost Bidslowest_bid
: Lowest Bidrevenue
: Revenuetotal_bids
: Total Bidswin_rate
: Win Ratewon_bids
: Won Bids
"metrics" allowed for DEAL_UI_MONITOR Report
below_the_floor
: Below The Floorbid_requests
: Bid Requestsbid_responses
: Bid Responsesblacklisted
: Blacklistedecpm
: eCPMincomplete_response
: Incomplete Responseinner_competition
: Inner Competitionno_bid
: No bidpaid_impressions
: Paid Impressionsrevenue
: Revenuetechnical_error
: Technical Errorunknown_type
: Unknown Typevalid
: Valid
"metrics" allowed for ANALYSIS_FLAT Report
clicks
: Clicksdefault_impressions
: Default Impressionsecpc
: eCPCecpm
: eCPMfailbacks
: Failbacksimpressions
: Impressionsnoads
: No Adspaid_impressions
: Paid Impressionspost_click_conversions
: Post Click Conversionspost_view_conversions
: Post View Conversionsrevenue
: Revenuevalid_bids
: Valid Bids
"metrics" allowed for QR_VIDEO Report
click_based_conversions
: Click Based Conversionsclicks
: Clicksclose
: Closecollapse
: Collapsecomplete
: Completecreativeview
: Creative Viewctr
: CTR (%)ecpm
: eCPMerrors
: Errorsexpand
: Expandfillrate
: Fillrate (%)firstquartile
: First Quartilefullscreen
: Full Screenimpressions
: Impressionsmidpoint
: Midpointmute
: Mutenoads
: No Adspaid_impressions
: Paid Impressionspause
: Pauseresume
: Resumerevenue
: Revenuerewind
: Rewindrpm
: RPMskip
: Skipstart
: Startthirdquartile
: Third Quartiletotal_inventory
: Total Inventoryunmute
: Unmutevcr
: 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": Text The value here must me one from the dimensions available for that type of report
"operation" : Text Allowed values: "EQUAL" "GREATER_THAN" "GREATER_OR_EQUAL" "LESS_THAN" "LESS_OR_EQUAL" "NOT_EQUAL" "LIKE" "NOT_LIKE" "IN" "NOT_IN"
"value": Text or 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": 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": of the values ENQUEUED GENERATING UPLOADING FINISHED_OK FAILED
"error":null or 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": and time indication of generation request submission
"started_date": start date and time indiciation
"finished_date": 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": Allowed values: 1 through 500.
"report_generation_request": 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"...} ...]
}