{ "swagger": "2.0", "info": { "version": "", "contact": { "name": "API Support", "url": "https://www.mediamath.com/contact-us/", "email": "support@mediamath.com" }, "title": "Reports API", "description": "The Reports API on the TerminalOne Platform allows advertisers to access, query and aggregate reporting data. It is also the API that powers all reporting seen on our TerminalOne flagship UI.\n\nThe Reports API offers a number of reports. Each report offers its own pre-aggregated, time-based metrics on entites that users can query. A query can filter, aggregate, sort, paginate, and format this data.\n\nIt is a read-only system meaning no request against it can alter the data in any way.\n\nIt is also a metadata-driven system. The supported reports are described in a human- and machine-readable format. This ensures easy one-off and repeatable programmatic data querying. It also provides a way for clients to adapt to changes in reports programmatically. This gives client-developers the ability to create UIs that provide useful operational feedback in a navigable and understandable way. \n\nThe $API_BASE for the latest version of Reports API is\n\n`https://api.mediamath.com/reporting/v1/std`\n\n### Authentication\n\nSee [OAuth Authentication](https://apidocs.mediamath.com/auth)\n\nMediaMath is in the process of migrating all APIs to OAuth2, but some APIs are not fully migrated. To mitigate that, make a request to `https://api.mediamath.com/api/v2.0/session` with the `Authorization:\"Bearer ACCESS_TOKEN\"` header. \nCopy the `adama_session` cookie header from the response. \n\nUse both the `Authorization:\"Bearer ACCESS_TOKEN\"` header and `adama_session=` cookie in all future requests to the reporting API. \n\n\n### Reports update schedule\n\nThe table below shows when TerminalOne Performance reports are updated. A campaign's reporting data is updated once per day, with a full view of the previous day's reporting data. This is based on the time zone of the campaign. The table below displays, based on the campaign's time zone, the time at which updated performance data will be available. There is an exception, AUS EST, which may not capture the full previous day but will complete with the next day's update.\n\n|Campaign Time Zone|Report Update Time|\n|--- |--- |\n|GMT|8 AM GMT|\n|EST|8 AM EST|\n|PST|11 AM PST|\n|EST (AUS)|5 AM EST (AUS)|\n\n# Fields\n\nReport data is stored and output in a tabular format. This means that the output consists of rows and columns. Every row has a value for every column.\n\nThe `structure` object can be used to determine the columns a report can output. Its fields are divided among three mappings - `time_field`, `dimensions`, and `metrics`. Each mapping, maps field name to #model:Fqbi8siNTuFGqA2W5.\n\n```json\n{\n \n \"time_rollups\" : [ \"by_day\", \"by_week\", \"by_month\", \"all\" ],\n \"time_windows\" : [ \"yesterday\", \"last_X_days\", \"month_to_date\", \"campaign_to_date\" ],\n \"timezone\" : \"campaign timezone\",\n \"time_aggregation\" : \"by_day\",\n \"structure\" : { \n \"time_field\" : { \n \"date\" : { \n \"name\" : \"Date\",\n \"type\" : \"datetime\"\n }\n }, \n \"dimensions\" : {\n \"campaign_id\" : { ... },\n \"campaign_name\" : { ... },\n \"strategy_id\" : { ... },\n \"strategy_name\" : { ... }\n }, \n \"metrics\" : { \n \"clicks\" : { ... },\n \"impressions\" : { ... }\n }\n }\n ...\n}\n```\n\n### Time Field\n\nThe time field represents the time-component of the report's metrics. There is (currently) only one time field for each report. It can be of one of these data types: `datetime` or `interval`. Its data type determines the type of report (**datetime** or **interval** based report).\n\n**Note:** The type of report is not to be confused with the `Type` attribute. The `Type` attribute is purely informational.\n\nThe time field was distinguished from the dimension fields to allow its use in grouping and filtering rows easier to understand. It gets its own set of parameters and language.\n\n#### datetime-typed Time Fields\n\nDatetime-typed time fields contains a combination of year, month, day, and possibly down to hour, minute and second. The `time_aggregation` property indicates the field's finest grain (by_hour, by_day, etc). The `time_rollups` property indicates the available grouping options that can go beyond the `time_aggregation` of the report.\n\n```\ntime_rollup=by_week ### group rows by the week - week starts on Monday \ntime_rollup=by_month ### group rows by the month\ntime_rollup=all ### produces at most one row of output per combination of dimension fields\n ### listed in the dimensions parameter\n```\n\nThe time field for these reports are typically represented in the output by a start_date and end_date column. The format of the column will depend on the time window and `time_rollup`.\n\n* YYYY-MM-DD\n* YYYY-MM-DD hh:mi:ss\n\nThe only exception to this rule is detailed in the Special Time Windows section.\n\nThe timezone of the start_date and end_date columns will match the `timezone` property.\n\n#### interval-typed Time Fields\n\n`interval`-typed time fields, contain a predefined non-calendar date based aggregation (1 day, 7 days, 30 days, and so on). In this case, the only accepted way to specify a time interval is by using the parameter `time_window`. The only value supported for the parameter `time_rollup` for interval-based reports is `all`.\n\nThe time field for these reports are represented in the output by a interval column. The value of the column will depend on the `time_window` chosen. The following gives example column values based on the time_window.\n\n* yesterday - 1\n* last_7_days - 7\n* last_30_days - 30\n* campaign_to_date - CTD\n* flight_to_date - FTD\n\n#### Filtering with the Time Field\n\nThe API requires the specification of a time window in order to narrow the data set operated on. A time window must be specified in one of the two possible ways.\n\n* `start_date` and `end_date` (optional - defaults to \"yesterday\").\n* `time_window` may be set to one of the formats defined by the `time_windows` attribute.\n\n```\n### operate on data timestamped between Jan 01, 2013 and Feb 01, 2013, inclusive\nstart_date=2013-01-01&end_date=2013-02-01 \n### operate on data timestamped between May 05, 2013 and yesterday, inclusive\nstart_date=2013-05-01 \n### other usage examples \ntime_window=last_30_days \ntime_window=month_to_date \ntime_window=yesterday \n```\n\n##### start_date and end_date\n\n`start_date` and `end_date` may only be used when the report's time field is of the `datetime` type. They may not be used when the report's time field is of the `interval` data type. This is because the `time_windows` are pre-defined intervals that cannot be split.\n\nThe `start_date` and `end_date` parameters define inclusive boundaries for the data. In order to ease the burden of calculating an inclusive end, the inputs may be specified at various granularities.\n\n* month - YYYY-MM\n* day - YYYY-MM-DD\n* hour - YYYY-MM-DDThh\n* minute - YYYY-MM-DDThh:mi\n* second - YYYY-MM-DDThh:mi:ss\n\nEach granularity matches a substring of the ISO 8601 format.\n\nIf the report is at a coarser granularity (see `time_aggregation`) than the input, the input will be taken to mean the entirety of the time unit.\n\n```\nstart_date=2016-04-12T01%3A30%3A00&end_date=2016-04-12T02%3A30%3A00\n# ie. start_date=2016-04-12T01:30:00&end_date=2016-04-12T02:30:00\n# For a report with a time_aggregation of by_hour:\n# 2016-04-12T01:00:00 to 2016-04-12T02:59:59.\n \n# For a report with a time_aggregation of by_day:\n# 2016-04-12T00:00:00 to 2016-04-12T23:59:59\n```\n\n##### time_window\n\nAll values mentioned in the `time_windows` array will be accepted verbatim by the time_window parameter with the exception of any time window that starts with `last_X_`. They may be interpreted as such.\n\n* The `last_X_days` time window ends yesterday (inclusive) and starts X days before that.\n* The `last_X_hours` time window ends at the previous hour (inclusive) and starts X hours before that.\n\nFuture windows of this type may be defined following this nomenclature, but for different units. Rules for the time window may vary slightly.\n\n##### Special Time Windows\n\nThe following `time_windows` are considered to be special time windows.\n\n* `campaign_to_date`\n* `flight_to_date`\n\nFor reports with a `datetime`-typed `time_field`, the start_date and end_date columns that would normally be present, will be replaced by the interval column. Additionally, the following validation rules apply when a special `time_window` is chosen.\n\n* The results will have an `interval` column instead of `start_date` and `end_date` columns.\n* The `time_rollup` parameter must be set to `all`.\n* Any mention of the `time_field` for the report in the `order` parameter will be rejected.\n\n### Dimension Fields\n\nDimension fields describe an entity. The example reports provide dimension fields for campaign, and strategy entities. Dimension fields are used to group rows during aggregation in conjunction with the time field.\n\n### Metric Fields\n\nOnce the rows have been grouped. The metric fields are calculated based on the values of the group's underlying rows. These calculations are generally sums or averages. These fields are usually a numeric data type.\n\n# Data Types\n\nThe `id` type allows any character except whitespace.\n\nThe `datetime` type may be filtered by dates, or datetimes in either of the following ISO 8601 based formats.\n\n* date - YYYY-MM-DD\n* datetime - YYYY-MM-DDThh:mi:ss\n\nYear, month, and day are all 1-based. Hour, minute, and second are all 0-based. Valid hours are 0-23.\n\nThe dimension fields of the `datetime` type will always be output in the aforementioned datetime format. The output columns for the time field will be output in the same format, but without the separating 'T'.\n\n### Field Data Type Groupings\n\nThis documentation may refer to multiple data types via a group name. The following table details the group names.\n\n|Group|Data Types|\n|--- |--- |\n|float|float, money, percent, ratio|\n|integer|integer, count, rank|\n|numeric|float and integer groups|\n|date|datetime|\n|string|string, interval|\n|id|id|\n|bool|bool, boolean|" }, "host": "api.mediamath.com", "basePath": "/reporting/v1/std", "schemes": [ "https" ], "consumes": [ "application/x-www-form-urlencoded" ], "paths": { "/meta": { "get": { "operationId": "GET_meta", "summary": "Reports List", "tags": [ "Metadata" ], "description": "In order to obtain a list of reports which are currently supported by the Reports API, issue the following API call:\n\n`$API_BASE/meta`\n\nAll metadata in Reports API is represented in JSON format (content-type: application/json; charset=UTF-8). The schema for the response follows the example.\n\n## Reports Meta as of 2017-05-11\n\nThe example has been formatted for easy reading.\n\n``` json\n{\n \"reports\": {\n \"app_transparency\": {\n \"Description\": \"Standard performance metrics broken out by App ID. Non-app inventory shown as N/A app_id\",\n \"Name\": \"App Transparency Report\",\n \"URI_Data\": \"https://api.mediamath.com/reporting/v1/std/app_transparency\",\n \"URI_Meta\": \"https://api.mediamath.com/reporting/v1/std/app_transparency/meta\",\n \"Version\": 1\n },\n \"audience_index\": {\n \"Description\": \"Special index metrics for comparing your ads' viewers to 3rd party segments. Broken out by audience name, as well as standard dimensions down to campaign and strategy. Currently available in one interval: last 14 days.\",\n \"Name\": \"Audience Index Report\",\n \"URI_Data\": \"https://api.mediamath.com/reporting/v1/std/audience_index\",\n \"URI_Meta\": \"https://api.mediamath.com/reporting/v1/std/audience_index/meta\",\n \"Version\": 1\n },\n \"audience_index_pixel\": {\n \"Description\": \"Special index metrics for comparing your site visitors to 3rd party segments. Broken out by audience name and pixel. Currently available in one interval: last 14 days.\",\n \"Name\": \"Audience Index Pixel Report\",\n \"URI_Data\": \"https://api.mediamath.com/reporting/v1/std/audience_index_pixel\",\n \"URI_Meta\": \"https://api.mediamath.com/reporting/v1/std/audience_index_pixel/meta\",\n \"Version\": 1\n },\n \"contextual_insights\": {\n \"Description\": \"Standard performance metrics broken out by contextual categories that strategies are targeting\",\n \"Name\": \"Contextual Insights\",\n \"URI_Data\": \"https://api.mediamath.com/reporting/v1/std/contextual_insights\",\n \"URI_Meta\": \"https://api.mediamath.com/reporting/v1/std/contextual_insights/meta\",\n \"Version\": 1\n },\n \"data_pixel_loads\": {\n \"Description\": \"Loads and Uniques metrics for data pixels, broken out by referrer and referrer rank, available by day.\",\n \"Name\": \"Data Pixel Loads Report\",\n \"URI_Data\": \"https://api.mediamath.com/reporting/v1/std/data_pixel_loads\",\n \"URI_Meta\": \"https://api.mediamath.com/reporting/v1/std/data_pixel_loads/meta\",\n \"Version\": 1\n },\n \"day_part\": {\n \"Description\": \"Standard performance metrics broken out by time of day and day of week. Available in standard intervals.\",\n \"Name\": \"Day Part Report\",\n \"URI_Data\": \"https://api.mediamath.com/reporting/v1/std/day_part\",\n \"URI_Meta\": \"https://api.mediamath.com/reporting/v1/std/day_part/meta\",\n \"Version\": 2\n },\n \"device_technology\": {\n \"Description\": \"Standard performance metrics broken out by technology dimensions including browser, operating system, and connection type. Available in custom date ranges or intervals with the option to aggregate by day, week, or month.\",\n \"Name\": \"Device Technology Report\",\n \"URI_Data\": \"https://api.mediamath.com/reporting/v1/std/device_technology\",\n \"URI_Meta\": \"https://api.mediamath.com/reporting/v1/std/device_technology/meta\",\n \"Version\": 1\n },\n \"event_pixel_loads\": {\n \"Description\": \"Loads and Uniques metrics for event pixels, broken out by referrer and referrer rank, available by day.\",\n \"Name\": \"Event Pixel Loads Report\",\n \"URI_Data\": \"https://api.mediamath.com/reporting/v1/std/event_pixel_loads\",\n \"URI_Meta\": \"https://api.mediamath.com/reporting/v1/std/event_pixel_loads/meta\",\n \"Version\": 1\n },\n \"geo\": {\n \"Description\": \"Standard performance metrics broken out by geographic dimensions including country, region, and metro area. Available in standard intervals.\",\n \"Name\": \"Geo Report\",\n \"URI_Data\": \"https://api.mediamath.com/reporting/v1/std/geo\",\n \"URI_Meta\": \"https://api.mediamath.com/reporting/v1/std/geo/meta\",\n \"Version\": 2\n },\n \"hyperlocal\": {\n \"Description\": \"Standard performance metrics broken out by Hyperlocal Targeting objects created via third party.\",\n \"Name\": \"Hyperlocal Report\",\n \"URI_Data\": \"https://api.mediamath.com/reporting/v1/std/hyperlocal\",\n \"URI_Meta\": \"https://api.mediamath.com/reporting/v1/std/hyperlocal/meta\",\n \"Version\": 1\n },\n \"performance\": {\n \"Description\": \"Standard performance metrics in campaign currency and broken out by our widest array of dimensions. Available in custom date ranges or intervals with the option to aggregate by day, week, or month.\",\n \"Name\": \"Performance Report in Campaign Currency\",\n \"URI_Data\": \"https://api.mediamath.com/reporting/v1/std/performance\",\n \"URI_Meta\": \"https://api.mediamath.com/reporting/v1/std/performance/meta\",\n \"Version\": 1\n },\n \"postal_code\": {\n \"Description\": \"Standard performance metrics broken out by postal code. Only includes data for strategies that targeted or anti-targeted postal codes. Available in custom date ranges or intervals with the option to aggregate by day, week, or month.\",\n \"Name\": \"Postal Code Report\",\n \"URI_Data\": \"https://api.mediamath.com/reporting/v1/std/postal_code\",\n \"URI_Meta\": \"https://api.mediamath.com/reporting/v1/std/postal_code/meta\",\n \"Version\": 1\n },\n \"pulse\": {\n \"Description\": \"Standard performance metrics broken out by standard dimensions, available in precise time windows - down to the hour - with the option to aggregate by hour or day.\",\n \"Name\": \"Pulse Report\",\n \"URI_Data\": \"https://api.mediamath.com/reporting/v1/std/pulse\",\n \"URI_Meta\": \"https://api.mediamath.com/reporting/v1/std/pulse/meta\",\n \"Version\": 1\n },\n \"reach_frequency\": {\n \"Description\": \"Basic performance metrics as well as the \\\"uniques\\\" metric, broken out by frequency of ad exposure. Available in standard intervals.\",\n \"Name\": \"Reach and Frequency Report\",\n \"URI_Data\": \"https://api.mediamath.com/reporting/v1/std/reach_frequency\",\n \"URI_Meta\": \"https://api.mediamath.com/reporting/v1/std/reach_frequency/meta\",\n \"Version\": 1\n },\n \"site_transparency\": {\n \"Description\": \"Standard performance metrics broken out by the domain of the inventory. Available in standard intervals.\",\n \"Name\": \"Site Transparency Report\",\n \"URI_Data\": \"https://api.mediamath.com/reporting/v1/std/site_transparency\",\n \"URI_Meta\": \"https://api.mediamath.com/reporting/v1/std/site_transparency/meta\",\n \"Version\": 2\n },\n \"video\": {\n \"Description\": \"Video-specific metrics such as completion rate, skips, and fullscreens broken out by a wide array of dimensions. Available in custom date-ranges or intervals with the option to aggregate by day, week, or month.\",\n \"Name\": \"Video Report\",\n \"URI_Data\": \"https://api.mediamath.com/reporting/v1/std/video\",\n \"URI_Meta\": \"https://api.mediamath.com/reporting/v1/std/video/meta\",\n \"Version\": 1\n },\n \"watermark\": {\n \"Description\": \"Watermark metrics show how many impressions and how much spend went towards the brain's learning activities. Viewable by campaign and strategy dimensions and available by day.\",\n \"Name\": \"Watermark Report in US Dollars\",\n \"URI_Data\": \"https://api.mediamath.com/reporting/v1/std/watermark\",\n \"URI_Meta\": \"https://api.mediamath.com/reporting/v1/std/watermark/meta\",\n \"Version\": 1\n },\n \"win_loss\": {\n \"Description\": \"Metrics describe the auction before a win or even a bid has taken place. Broken out by strategy, exchange, and deal dimensions and available by hour.\",\n \"Name\": \"Win/Loss Report\",\n \"URI_Data\": \"https://api.mediamath.com/reporting/v1/std/win_loss\",\n \"URI_Meta\": \"https://api.mediamath.com/reporting/v1/std/win_loss/meta\",\n \"Version\": 2\n },\n \"win_loss_creative\": {\n \"Description\": \"Metrics describe the auction before a win has taken place. Broken out by creative dimensions and available by hour.\",\n \"Name\": \"Win/Loss Creative Report\",\n \"URI_Data\": \"https://api.mediamath.com/reporting/v1/std/win_loss_creative\",\n \"URI_Meta\": \"https://api.mediamath.com/reporting/v1/std/win_loss_creative/meta\",\n \"Version\": 1\n }\n }\n}\n\n```", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" } ], "responses": { "200": { "description": "", "schema": { "title": "Reports List", "type": "object", "properties": { "reports": { "type": "object", "additionalProperties": { "title": "Brief Report Description", "type": "object", "properties": { "Name": { "type": "string", "description": "This is the human-readable name of the report. It is not recognized by any API input." }, "Version": { "type": "integer", "description": "This is the version of the report. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details." }, "Description": { "type": "string" }, "URI_Data": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:kbWhxp8szYZXNMBre endpoint." }, "URI_Meta": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:XLZxmeHNEAsLXfPht." }, "Transition": { "type": "object", "description": "Reports may change over time. This object will be present if the report will undergo a breaking change. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "replaced_by": { "type": "string", "format": "uri", "description": "The URL where the metadata for the next version of the report may be found." }, "transition_date": { "type": "string", "format": "date-time", "description": "After this GMT time the current version of the report will no longer be available." }, "next_version": { "type": "integer", "description": "The version replacing the current version of the report." } }, "required": [ "replaced_by", "transition_date", "next_version" ] }, "Deprecation": { "type": "object", "description": "Reports may be deprecated all together, or superseded by another report. This object will be present if the report is scheduled for deprecation. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "superseded_by": { "type": "string", "format": "uri", "description": "Optionally provides the metadata URI for the superseding report." }, "deprecation_date": { "type": "string", "format": "date-time", "description": "The GMT time when the report will no longer be available. When a report is past its `deprecation_date` it will no longer appear in the #endpoint:zMKJNurbLQddPfSfN. All endpoints having to do specifically with that report will return a 410 GONE response." } }, "required": [ "deprecation_date" ] } }, "required": [ "Name", "Version", "URI_Data", "URI_Meta" ] }, "description": "This is a mapping of report names to #model:DXB2r3wXGZsaAdrcB." } } } } } } }, "/{report}/meta": { "parameters": [ { "name": "report", "in": "path", "description": "This must be a report discoverable from #endpoint:zMKJNurbLQddPfSfN.", "required": true, "type": "string" } ], "get": { "operationId": "GET_report-meta", "summary": "Report Meta", "tags": [ "Metadata" ], "description": "The examples used in this section are truncated versions of #docTextSection:5pQR3f2NJeRJCCTcy. The use of \"...\" in an example is meant to indicate truncation of other properties. The Definition section of this endpoint provides information about how the metadata may vary from report to report. The Definition section of the #endpoint:kbWhxp8szYZXNMBre provides a reference to the query string parameters that it accepts.", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" } ], "responses": { "200": { "description": "", "schema": { "title": "Full Report Description", "allOf": [ { "title": "Brief Report Description", "type": "object", "properties": { "Name": { "type": "string", "description": "This is the human-readable name of the report. It is not recognized by any API input." }, "Version": { "type": "integer", "description": "This is the version of the report. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details." }, "Description": { "type": "string" }, "URI_Data": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:kbWhxp8szYZXNMBre endpoint." }, "URI_Meta": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:XLZxmeHNEAsLXfPht." }, "Transition": { "type": "object", "description": "Reports may change over time. This object will be present if the report will undergo a breaking change. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "replaced_by": { "type": "string", "format": "uri", "description": "The URL where the metadata for the next version of the report may be found." }, "transition_date": { "type": "string", "format": "date-time", "description": "After this GMT time the current version of the report will no longer be available." }, "next_version": { "type": "integer", "description": "The version replacing the current version of the report." } }, "required": [ "replaced_by", "transition_date", "next_version" ] }, "Deprecation": { "type": "object", "description": "Reports may be deprecated all together, or superseded by another report. This object will be present if the report is scheduled for deprecation. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "superseded_by": { "type": "string", "format": "uri", "description": "Optionally provides the metadata URI for the superseding report." }, "deprecation_date": { "type": "string", "format": "date-time", "description": "The GMT time when the report will no longer be available. When a report is past its `deprecation_date` it will no longer appear in the #endpoint:zMKJNurbLQddPfSfN. All endpoints having to do specifically with that report will return a 410 GONE response." } }, "required": [ "deprecation_date" ] } }, "required": [ "Name", "Version", "URI_Data", "URI_Meta" ] }, { "type": "object", "properties": { "Type": { "type": "string" }, "currency": { "type": "string", "description": "Provides information about the currency of the `metrics` fields typed as \"money\".\n\nWhen set to \"campaign currency\", the currency varies from record to record. To determine the currency for a particular record, the campaign_currency_code `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the currency for all records of the report." }, "data_retention": { "type": "string", "description": "Indicates how far back data is available. This can be a date, datetime, or time window as specified by the \"time_window\" and \"Special Time Windows\" sections of #docTextSection:GYrNjxjRCDjDrqcu7. This property should be used very loosely. It may not be accurate. It is meant to give a general idea." }, "default_metrics": { "type": "array", "description": "This is the list of metrics that will be returned if the `metrics` parameter is not specified in a call to the #endpoint:kbWhxp8szYZXNMBre endpoint.", "items": { "type": "string" } }, "structure": { "type": "object", "required": [ "time_field", "dimensions", "metrics" ], "properties": { "time_field": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "dimensions": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "metrics": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." } } }, "time_aggregation": { "type": "string", "description": "This property indicates the finest granularity of the `time_field`. For reports with a `time_field` of the `datetime` type, this will be \"by_hour\", \"by_day\", etc. When the type is `interval`, this will be \"various\"." }, "time_rollups": { "type": "array", "description": "This property indicates the available levels of granularity for the `time_field`. It lists the valid values of the `time_rollup` parameter used for the #endpoint:kbWhxp8szYZXNMBre endpoint. For reports with a `time_field` of the `datetime` type, this tends to be a combination of \"by_hour\", \"by_day\", \"by_week\", \"by_month\", \"all\", etc. When the type is `interval`, this will only include \"all\".", "items": { "type": "string" } }, "time_windows": { "type": "array", "description": "Lists the acceptable formats for the `time_window` parameter used by the #endpoint:kbWhxp8szYZXNMBre endpoint. Some values may be used as is, others may need to be modified. For details see the time_window section of #docTextSection:GYrNjxjRCDjDrqcu7.", "items": { "type": "string" } }, "timezone": { "type": "string", "description": "Provides information about the timezone of the `time_field` for the report.\n\nWhen set to \"campaign timezone\", the timezone varies from record to record. To determine the currency for a particular record, the campaign_timezone `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the timezone for all records of the report." } }, "required": [ "default_metrics", "structure", "time_rollups", "time_windows" ] } ] } } } } }, "/{report}": { "parameters": [ { "name": "report", "in": "path", "description": "This must be a report discoverable from #endpoint:zMKJNurbLQddPfSfN.", "required": true, "type": "string" } ], "get": { "operationId": "GET_report", "summary": "Report Data", "tags": [ "Data Retrieval" ], "description": "# Parameters\n\nParameter names are case sensitive, (see the table below).\n\nMost parameters will fall under one of the following two formats.\n\n* enumeration of comma-separated items (used in aggregation, selection and sorting);\n * example:\n * `dimensions=campaign_id%2Ccampaign_name%2Ccampaign_start_date` (in other words, `campaign_id,campaign_name,campaign_start_date`)\n* list of logically AND-ed expressions, joined by ampersand (used in dimension and metric filtering);\n * examples:\n * `filter=campaign_id%3D12345%26strategy_id%3D98765` (in other words, `campaign_id=12345&strategy_id=98765`)\n * `having=impressions%3E%3D500%26clicks%3C100` (in other words, `impressions>=500&clicks<100`)\n\n# Query Options\n\nA query can filter, aggregate, sort, paginate, and format a report's data.\n\nFiltering is required. It must be done on the time field, and one or more dimension fields that have their `access` property set to true. It can be done both before and after aggregation.\n\nAggregation, like filtering, is also required. The grouping must be performed against the time field and a combination of one or more dimension fields.\n\nSorting, pagination, and formatting are not required. The features are controlled via the `order`, `page_limit`, `page_offset`, and `precision` parameters. They are described in full detail in the Definition section at the end of the documentation for this endpoint.\n\n### Filtering\n\nData filtering may be performed before rows are grouped, and afterwards as well.\n\nIt can be done before grouping via the `time_window`, `start_date`, `end_date`, and `filter` parameters. This provides finer control over what rows contribute to the metric fields of a group.\n\nFiltering can also be done after grouping, and metric calculations via the `having` parameter.\n\nFor more information about the `time_window`, `start_date`, and `end_date` parameters see the #docTextSection:GYrNjxjRCDjDrqcu7 section.\n\nFor more information about the `filter` and `having` parameters see the following section.\n\n#### Predicate Parameters\n\n`filter` and `having` are predicate parameters. One of the two parameters is required. The parameters consist of one or more predicates. A predicate has the following format.\n\n1. a dimension or metric field from the report definition\n2. an operator from the _Operators supported in filtering expressions_ table\n3. one or more values matching the type of field\n\nAt least one predicate parameters is required. This is because at least one of the predicates must use one of the access dimension fields in an equality test (operator `=`).\n\nThe `filter` parameter filters on dimension fields only, while the `having` parameter may filter by both dimension and metric fields. The `filter` parameter is applied before rows are grouped, while the `having` parameter is applied after rows have been grouped, and metrics have been calculated.\n\nThe parameter `filter` is not required if access dimension fields are used in parameter `having`. Using dimension fields in the `having` parameter causes those dimension fields to be used in grouping rows.\n\n##### Operators supported in filtering expressions\n\n|Operators|Operation|Field Data Type|\n|--- |--- |--- |\n|=, !=|equality, non-equality check|all|\n|>, <, >=, <=|inequality check|numeric|\n|~, =~|contains, case sensitive|string|\n|=:|contains, case insensitive|string|\n|!~|does not contain, case sensitive|string|\n|!:|does not contain, case insensitive|string|\n\n##### Multiple Predicates\n\nMore than one predicate may be specified in a predicate parameter. The predicates need to be joined together with an ampersand (&). The ampersand indicates the predicates are ANDed together. As such, for a record to appear in the results, each predicate must evaluate to true for that record. The following shows an example.\n\n```\n### filtering aggregated rows by metric or dimension fields\nhaving=impressions%3E%3D500%26clicks%3C100%26campaign_id%3D12345\n### (i.e. impressions>=500&clicks<100&campaign_id=12345)\n\n### filtering base rows by dimension fields\nfilter=campaign_id%3D12345%26strategy_id%3D98765%2Cstrategy_goal_type%3Dcpc\n### (i.e. campaign_id=12345&strategy_id=98765&strategy_goal_type=cpc)\n```\n\n##### Predicates with Multiple Values\n\nA predicate is considered true, if one or more values evaluate as true for the given field and comparison operation. This result is then ANDed with any other predicates that exist at that level of filtering. Values must be separated by commas. The following shows an example.\n\n```\n### filtering records for when campaign_id is 11111, 22222, or 33333 and the campaign_name contains \"sell\"\nfilter=campaign_id%3D11111%2C22222%2C33333%26campaign_name%7Esell\n### (i.e. campaign_id=11111,22222,33333&campaign_name~sell)\n```\n\n##### Encoding Predicates\n\nIn order to ensure predicates and values are properly separated, a special encoding is needed for predicate values that contain any of the following characters.\n\n& , \" < > = ~ ! :\n\nThe encoding is a simple two step process.\n\n1. Double quotes are doubled.\n2. The resultant value is surrounded in double quotes.\n\nThe following shows an example.\n\n* Unencoded: Jack & Jill \"Of All Trades\"\n* Encoded: \"Jack & Jill \"\"Of All Trades\"\"\"\n\nThis special encoding may be applied to any value in the predicates. It does not determine the type. The looseness is there to allow for URLs to be more readable. It does however, need to be applied before URL encoding is performed.\n\n### Aggregation\n\nThrough the `dimensions`, one can indicate the way the rows must be grouped. One or more dimension fields, may be specified. The order in which the dimension fields are listed is important for the result set.\n\n```\n### group by these fields in this order dimensions=campaign_id%2Ccampaign_name%2Ccampaign_start_date\n### (i.e. campaign_id,campaign_name,campaign_start_date) \n```\n\nSee the Time Field section of the #endpoint:XLZxmeHNEAsLXfPht for grouping options available for the time field.\n\nGrouping by metric fields is not allowed. Metric fields are calculated based on the underlying rows of each group. The metrics can be chosen via the `metrics` parameter.\n\n```\n### calculate these metrics per group dimensions=clicks%2Cimpressions\n### (i.e. clicks,impressions) \n```\n\n# On Success\n\nThe system returns an appropriate HTTP return code (2xx or 3xx - see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6.1.1)). The response body is CSV-formatted (`Content-Type: text/csv`), consisting of one header row, and zero or more data rows. The response uses the HTTP 1.1 [chunking](http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.6.1) feature.\n\nA data row will represent a group. It will have a start_date/end_date format, or an interval format. Always use the header line to determine the order of columns, as they may not match the order listed in the parameters.\n\n### start_date/end_date Format\n\n* two columns of type datetime:\n * start_date - the start of the time rollup interval (inclusive)\n * end_date - the end of the time rollup interval (inclusive)\n* all dimension fields specified in the parameters dimensions\n* all metric fields specified in the parameter metrics\n* all fields, dimension or metric, specified in the parameters having and order\n\nNote that the `start_date` and `end_date` will cover the whole interval specified by the parameter time_window (or `start_date` \\/ `end_date` equivalents), or the intervals generated according to the parameter `time_rollup`, even though data may not exist for the whole interval.\n\n```\nstart_date,end_date,campaign_id,campaign_name,creative_id,creative_name,clicks,impressions,total_spend\n\"2013-05-01\",\"2013-05-22\",123456,\"My Campaign Nr 10\",98765432,\"Creative No 12\",17701,171981779,45266.65\n\"2013-04-24\",\"2013-04-30\",123456,\"My Campaign Nr 10\",11223344,\"Creative Nr Five\",4101,45076933,7566.57\n\"2013-04-24\",\"2013-04-30\",123456,\"My Campaign Nr 10\",12121212,\"Creative Ten\",5220,42592353,6360.86\n\"2013-05-01\",\"2013-05-22\",123456,\"My Campaign Nr 10\",99887766,\"Creative One\",21912,41691908,61644.34 \n```\n\n### interval Format\n\n* one field of type interval:\n * interval - the pre-aggregated interval of the group.\n* all dimension fields specified in the parameters dimensions\n* all metric fields specified in the parameter metrics\n* all fields, dimension or metric, specified in the parameters having and order\n\n```\ninterval,campaign_id,campaign_name,creative_id,creative_name,clicks,impressions,total_spend\n7,123456,\"My Campaign Nr 10\",98765432,\"Creative No 12\",17701,171981779,45266.65\n7,123456,\"My Campaign Nr 10\",11223344,\"Creative Nr Five\",4101,45076933,7566.57\n7,123456,\"My Campaign Nr 10\",12121212,\"Creative Ten\",5220,42592353,6360.86\n7,123456,\"My Campaign Nr 10\",99887766,\"Creative One\",21912,41691908,61644.34 \n```\n\n### Predicting the Format\n\n`interval` based report queries will return the interval format.\n\n`datetime` based report queries:\n* using a special time window will return the interval format.\n* using a normal time window will return the start_date/end_date format.\n\n# On Error\n\nOn error, an appropriate HTTP status code is returned (4xx or 5xx - see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6.1.1)). The response body, which of type XML (`Content-Type: text/xml`) will contain, at the minimum (see examples below), the root element result, with at least one element named status, which in turn has an attribute named code, and a human readable text. Some error responses also contain an attribute reason, which adds more information regarding the error.\n\nThere are several types of errors:\n\n### Authentication and authorization errors\n\n```\nHTTP/1.0 401 Unauthorized\nContent-Type: text/xml; charset=UTF-8\n\n\n Authentication Required\n\n```\n\n```\nHTTP/1.0 403 Forbidden\nContent-Type: text/xml; charset=UTF-8\n\n\n \n Insufficient permissions\n\n```\n\n### Parameter validation errors (malformed values, unknown fields, missing required parameters, etc)\n\n```\nHTTP/1.0 400 Bad Request\nContent-Type: text/xml; charset=UTF-8\n\n\n a time window is required\n\n```\n\n### Non-existent entities\n\n```\nHTTP/1.0 404 Not Found\nContent-Type: text/xml; charset=UTF-8\n\n\n \n Entity Not Found\n\n```\n\n### Server errors (internal error, request timeout, scheduled maintenance, server overloaded)\n\n```\nHTTP/1.0 500 Internal Server Error\nContent-Type: text/xml; charset=UTF-8\n\n\n Internal Server Error\n\n```\n\n```\nHTTP/1.0 500 Internal Server Error\nContent-Type: text/xml; charset=UTF-8\n\n\n The request timed out\n\n```\n\n```\nHTTP/1.0 503 Service Unavailable\nContent-Type: text/xml; charset=UTF-8\n\n\n The server is temporarily unavailable due to maintenance downtime.\n\n```", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" }, { "name": "dimensions", "in": "query", "description": "Selects the dimension fields to use in grouping rows.\n\nThis should be a comma-separated list of dimension field names.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": true, "type": "string" }, { "name": "metrics", "in": "query", "description": "Controls the selection of metric fields.\n\nThis should be a comma-separated list of metric field names.\n\nIf not specified, this will default to the metric fields specified by the `default_metrics` property of the #endpoint:XLZxmeHNEAsLXfPht.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": false, "type": "string" }, { "name": "filter", "in": "query", "description": "Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": true, "type": "string" }, { "name": "having", "in": "query", "description": "Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": false, "type": "string" }, { "name": "time_rollup", "in": "query", "description": "The allowed values are specified by the time_rollups report meta property. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "time_window", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "start_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": false, "type": "string", "default": "yesterday" }, { "name": "order", "in": "query", "description": "Controls the sorting of the groups.\n\nThis should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed.\n\nThe first field has the most significance in sorting.", "required": false, "type": "string" }, { "name": "page_limit", "in": "query", "description": "Controls the maximum number of rows of data.\n\nThis parameter is required, if page_offset is one or greater.", "required": false, "type": "integer", "minimum": 1, "default": "unlimited" }, { "name": "page_offset", "in": "query", "description": "Controls how many pages to skip.", "required": false, "type": "integer", "minimum": 0 }, { "name": "precision", "in": "query", "description": "Controls how many digits to the right of the decimal places to display for float types.", "required": false, "type": "integer", "minimum": 0, "maximum": 8, "default": 8 }, { "name": "Accept-Encoding:", "in": "header", "description": "If the client supports the compression methods also supported by the server (currently `gzip` and `deflate`), the response data set (`text`\\/`csv`) will be returned in a compressed format. The metadata and error responses will not be compressed.\n\nIn order to receive the data in compressed format, the client must use the HTTP request header `Accept-Encoding`, and enumerate the preferred compression methods (see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). If the header `Accept-Encoding` is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format.\n\n ### request \n Accept-Encoding: gzip,deflate \n\n ### response \n Content-Encoding: gzip \n Content-Type: text/csv; charset=UTF-8 ", "type": "string", "enum": [ "gzip,deflate" ] }, { "name": "If-Modified-Since", "in": "header", "description": "If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body.\n\nIf the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header.", "type": "string", "format": "date-time" } ], "responses": { "200": { "description": "" }, "304": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } } } }, "/{report}/validate": { "parameters": [ { "name": "report", "in": "path", "required": true, "type": "string" } ], "get": { "operationId": "GET_report-validate", "summary": "Validate Report Data Request", "tags": [ "Data Retrieval" ], "description": "### Validating Data Retrieval Requests\n\nData retrieval requests can be validated and authenticated without actually requesting data, by simply appending a `/validate` path segment to the URI. **Important:** The validation process takes into account the current user's permissions. The error responses that are returned in case of validation failure are the same as the ones that would have been returned by the regular API call.\n\nThe following shows an example validation request for a request with an erroneous `organization_id` filtering parameter:\n\n```\nGET /reporting/v1/std/{report}/validate?filter=organization_id%3D12345&dimensions=campaign_id%2Corganization_id&time_window=last_7_days&time_rollup=by_day\n```\n\n```\nHTTP/1.0 404 Not Found\nContent-Type: text/xml; charset=UTF-8\n\n\n\n \n Entity Not Found\n\n```\n\nBy contrast, this call shows a validation response for a valid call:\n\n```\nGET /reporting/v1/std/{report}/validate?filter=organization_id%3D12346&dimensions=campaign_id%2Corganization_id&time_window=last_7_days&time_rollup=by_day\n```\n\n```\nHTTP/1.0 200 OK\nContent-Type: text/xml; charset=UTF-8\n\n\n\n \n\n```", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" }, { "name": "dimensions", "in": "query", "description": "Selects the dimension fields to use in grouping rows.\n\nThis should be a comma-separated list of dimension field names.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": true, "type": "string" }, { "name": "metrics", "in": "query", "description": "Controls the selection of metric fields.\n\nThis should be a comma-separated list of metric field names.\n\nIf not specified, this will default to the metric fields specified by the `default_metrics` property of the #endpoint:XLZxmeHNEAsLXfPht.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": false, "type": "string" }, { "name": "filter", "in": "query", "description": "Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": true, "type": "string" }, { "name": "having", "in": "query", "description": "Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": false, "type": "string" }, { "name": "time_rollup", "in": "query", "description": "The allowed values are specified by the time_rollups report meta property. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "time_window", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "start_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": false, "type": "string", "default": "yesterday" }, { "name": "order", "in": "query", "description": "Controls the sorting of the groups.\n\nThis should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed.\n\nThe first field has the most significance in sorting.", "required": false, "type": "string" }, { "name": "page_limit", "in": "query", "description": "Controls the maximum number of rows of data.\n\nThis parameter is required, if page_offset is one or greater.", "required": false, "type": "integer", "minimum": 1, "default": "unlimited" }, { "name": "page_offset", "in": "query", "description": "Controls how many pages to skip.", "required": false, "type": "integer", "minimum": 0 }, { "name": "precision", "in": "query", "description": "Controls how many digits to the right of the decimal places to display for float types.", "required": false, "type": "integer", "minimum": 0, "maximum": 8, "default": 8 }, { "name": "Accept-Encoding:", "in": "header", "description": "If the client supports the compression methods also supported by the server (currently `gzip` and `deflate`), the response data set (`text`\\/`csv`) will be returned in a compressed format. The metadata and error responses will not be compressed.\n\nIn order to receive the data in compressed format, the client must use the HTTP request header `Accept-Encoding`, and enumerate the preferred compression methods (see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). If the header `Accept-Encoding` is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format.\n\n ### request \n Accept-Encoding: gzip,deflate \n\n ### response \n Content-Encoding: gzip \n Content-Type: text/csv; charset=UTF-8 ", "type": "string", "enum": [ "gzip,deflate" ] }, { "name": "If-Modified-Since", "in": "header", "description": "If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body.\n\nIf the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header.", "type": "string", "format": "date-time" } ], "responses": { "200": { "description": "" }, "304": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } } } }, "/app_transparency": { "get": { "operationId": "GET_app_transparency", "summary": "App Transparency", "tags": [ "Reports" ], "description": "See or query the Meta Endpoint for required fields and parameters.", "responses": { "200": { "description": "", "schema": {} } } } }, "/app_transparency/meta": { "get": { "operationId": "GET_app_transparency-meta", "summary": "App Transparency Meta", "tags": [ "Reports" ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "Description": { "type": "string" }, "Name": { "type": "string" }, "Type": { "type": "string" }, "URI_Data": { "type": "string" }, "URI_Meta": { "type": "string" }, "Version": { "type": "integer" }, "currency": { "type": "string" }, "data_retention": { "type": "string" }, "default_metrics": { "type": "array", "items": { "type": "string" } }, "structure": { "type": "object", "properties": { "dimensions": { "type": "object", "properties": { "advertiser_id": { "type": "object", "properties": { "access": { "type": "boolean" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "advertiser_name": { "type": "object", "properties": { "maxLength": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "agency_id": { "type": "object", "properties": { "access": { "type": "boolean" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "agency_name": { "type": "object", "properties": { "maxLength": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "app_id": { "type": "object", "properties": { "maxLength": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "attribution_group": { "type": "object", "properties": { "maxLength": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } } }, "campaign_budget": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "campaign_currency_code": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "campaign_end_date": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "campaign_goal_type": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } } }, "campaign_goal_value": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "campaign_id": { "type": "object", "properties": { "access": { "type": "boolean" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "campaign_initial_start_date": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "campaign_name": { "type": "object", "properties": { "maxLength": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "campaign_start_date": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "campaign_timezone": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "campaign_timezone_code": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "exchange_id": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "exchange_name": { "type": "object", "properties": { "maxLength": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "organization_id": { "type": "object", "properties": { "access": { "type": "boolean" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "organization_name": { "type": "object", "properties": { "maxLength": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "strategy_budget": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "strategy_channel": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } } }, "strategy_end_date": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "strategy_goal_type": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } } }, "strategy_goal_value": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "strategy_id": { "type": "object", "properties": { "access": { "type": "boolean" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "strategy_name": { "type": "object", "properties": { "maxLength": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "strategy_start_date": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "strategy_supply_type": { "type": "object", "properties": { "maxLength": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } } }, "strategy_type": { "type": "object", "properties": { "maxLength": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" } } } } }, "metrics": { "type": "object", "properties": { "clicks": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "ctc": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "ctr": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "impressions": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "media_cost": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "media_cost_cpa": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "media_cost_cpc": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "media_cost_cpm": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "media_cost_pc_cpa": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "media_cost_pv_cpa": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "post_click_conversions": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "post_view_conversions": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "rr_per_1k_imps": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "total_ad_cost": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "total_ad_cost_cpa": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "total_ad_cost_cpc": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "total_ad_cost_cpm": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "total_ad_cost_pc_cpa": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "total_ad_cost_pv_cpa": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "total_conversions": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "total_spend": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "total_spend_cpa": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "total_spend_cpc": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "total_spend_cpm": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "total_spend_pc_cpa": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "total_spend_pv_cpa": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_close": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_collapse": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_companion_clicks": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_companion_ctr": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_companion_impressions": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_complete": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_complete_rate": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_engaged_impressions": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_engaged_rate": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_expand": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_first_quartile": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_first_quartile_rate": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_fullscreen": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_midpoint": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_midpoint_rate": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_mute": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_pause": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_play_rate": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_resume": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_rewind": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_skip": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_skippable_impressions": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_skipped_impressions": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_skipped_rate": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_start": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_third_quartile": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_third_quartile_rate": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "video_unmute": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } } } }, "time_field": { "type": "object", "properties": { "date": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } } } } } }, "time_aggregation": { "type": "string" }, "time_rollups": { "type": "array", "items": { "type": "string" } }, "time_windows": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string" } } } } }, "description": "Get App Transparency Meta" } }, "/audence_index": { "get": { "operationId": "GET_audence_index", "summary": "Audience Index", "tags": [ "Reports" ], "description": "The Audience Index Report measures how your site visitors or media viewers compare to the internet population as a whole. It’s created by classifying your Audience (as defined by pixel, campaign, or strategy) cookies according to 3rd party segments, and then comparing the result to how the broader internet fits those segments. Use it to gain a better understanding of the demographics you are reaching.\n\n# API Endpoints\n\nThe Audience Index Report is divided into two different endpoints, one for media and one for pixels.\n\nCampaign and strategy dimensions are available in:\n\n`$API_BASE/audience_index`\n\nThe pixel dimension is available in:\n\n`$API_BASE/audience_index_pixel`\n\nNote: Pixels will only appear in the `/audience_index_pixel` report if they have at least 30 matches with all `audience_name` fields under a given `audience_path`. If a pixel has a small number of loads, it will most likely fail to meet this criteria.\n\n# Important Fields\n\n### Report-Specific Fields\n\n`audience_name` - this field provides the name of the 3rd party segment that’s being matched. Best practice is to always include audience_name in your report, otherwise audience_index values will be aggregated across selected dimensions, and it won't be a sensical metric.\n\n`audience_path` - segments are organized in hierarchies. For example, the “dentist” segment lives under the Demographic > Employment > Occupations > Health categories. The `audience_path` field shows this relationship. It is also used to help calculate the audience index, as shown below.\n\n`audience_index` - this field is a relative value that describes the composition of your audience as compared to the internet average using segments provided by 3rd party data companies. If the index value for a given segment is 100, it means that your audience contains the same proportion of that demographic as the overall internet. If the value is greater than 100, your audience is over-indexed with that segment - that is, it consists of a greater portion of that segment than the general internet population does. If it’s less than 100, your audience is under-indexed. For example, a sporting goods retailer might hope that the customers they target with a golf supplies campaign would over-index on BlueKai’s “Interest/Sports/Golf” segment. If the index for this segment is 150, it means that the share of customers with an interest in golf is 50% higher in the retailer’s audience than it is in the total internet population.\n\nNOTE: The `audience_name` dimension and `audience_index` metric are what make the Audience Index Report unique. In fact, the report would be useless without these fields, so always be sure to include them.\n\n### Time Fields\n`audience_index` is available as an interval report. Currently only one `time_window` is supported: `last_14_days`. The only `time_aggregation` available is “all\".\n\n# Updates\n\nData is updated weekly (Sunday). Check the Last-Modified date in the header for more specific timing.\n\n# Calculations\n\nThe `audience_index` field is calculated as follows:\n\n- x = unique customers in pixel pool, strategy media viewers, or campaign media viewers\n- y = x in segment / x in segment path\n- z = Total Internet in segment / Total Internet in segment path\n`segment_index` = y/z * 100\n\n# Example\n\nHere’s how the Audience Index Report would help a youth apparel retailer determine whether they are successfully reaching the “age 18-24” age demographic.\n\n1. We look at the desired campaign/pixel/strategy and count total matched people against all of the 3rd party provider's age data: 400,000\n2. We look at the same campaign/pixel/strategy data for 18-24: 100,000\n3. So, 25% of your matched strategy, campaign or pixel data falls into the “age 18 to 24” segment\n4. We look at all cookies the 3rd party has matched to the broader internet for ALL of the age segments: 1,000,000\n5. We look at how many cookies the 3rd party has matched to the broader internet for people in the “age 18-24” segment: 200,000\n6. So, the 3rd party says that 20% of all internet cookies are between 18 and 24\n7. Therefore the `audience_index` is 125 (25/20)", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" }, { "name": "dimensions", "in": "query", "description": "Selects the dimension fields to use in grouping rows.\n\nThis should be a comma-separated list of dimension field names.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": true, "type": "string" }, { "name": "metrics", "in": "query", "description": "Controls the selection of metric fields.\n\nThis should be a comma-separated list of metric field names.\n\nIf not specified, this will default to the metric fields specified by the `default_metrics` property of the #endpoint:XLZxmeHNEAsLXfPht.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": false, "type": "string" }, { "name": "filter", "in": "query", "description": "Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": true, "type": "string" }, { "name": "having", "in": "query", "description": "Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": false, "type": "string" }, { "name": "time_rollup", "in": "query", "description": "The allowed values are specified by the time_rollups report meta property. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "time_window", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "start_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": false, "type": "string", "default": "yesterday" }, { "name": "order", "in": "query", "description": "Controls the sorting of the groups.\n\nThis should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed.\n\nThe first field has the most significance in sorting.", "required": false, "type": "string" }, { "name": "page_limit", "in": "query", "description": "Controls the maximum number of rows of data.\n\nThis parameter is required, if page_offset is one or greater.", "required": false, "type": "integer", "minimum": 1, "default": "unlimited" }, { "name": "page_offset", "in": "query", "description": "Controls how many pages to skip.", "required": false, "type": "integer", "minimum": 0 }, { "name": "precision", "in": "query", "description": "Controls how many digits to the right of the decimal places to display for float types.", "required": false, "type": "integer", "minimum": 0, "maximum": 8, "default": 8 }, { "name": "Accept-Encoding:", "in": "header", "description": "If the client supports the compression methods also supported by the server (currently `gzip` and `deflate`), the response data set (`text`\\/`csv`) will be returned in a compressed format. The metadata and error responses will not be compressed.\n\nIn order to receive the data in compressed format, the client must use the HTTP request header `Accept-Encoding`, and enumerate the preferred compression methods (see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). If the header `Accept-Encoding` is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format.\n\n ### request \n Accept-Encoding: gzip,deflate \n\n ### response \n Content-Encoding: gzip \n Content-Type: text/csv; charset=UTF-8 ", "type": "string", "enum": [ "gzip,deflate" ] }, { "name": "If-Modified-Since", "in": "header", "description": "If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body.\n\nIf the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header.", "type": "string", "format": "date-time" } ], "responses": { "200": { "description": "" }, "304": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } } } }, "/audence_index/meta": { "get": { "operationId": "GET_audence_index-meta", "summary": "Audience Index Meta", "tags": [ "Reports" ], "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" } ], "responses": { "200": { "description": "", "schema": { "title": "Full Report Description", "allOf": [ { "title": "Brief Report Description", "type": "object", "properties": { "Name": { "type": "string", "description": "This is the human-readable name of the report. It is not recognized by any API input." }, "Version": { "type": "integer", "description": "This is the version of the report. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details." }, "Description": { "type": "string" }, "URI_Data": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:kbWhxp8szYZXNMBre endpoint." }, "URI_Meta": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:XLZxmeHNEAsLXfPht." }, "Transition": { "type": "object", "description": "Reports may change over time. This object will be present if the report will undergo a breaking change. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "replaced_by": { "type": "string", "format": "uri", "description": "The URL where the metadata for the next version of the report may be found." }, "transition_date": { "type": "string", "format": "date-time", "description": "After this GMT time the current version of the report will no longer be available." }, "next_version": { "type": "integer", "description": "The version replacing the current version of the report." } }, "required": [ "replaced_by", "transition_date", "next_version" ] }, "Deprecation": { "type": "object", "description": "Reports may be deprecated all together, or superseded by another report. This object will be present if the report is scheduled for deprecation. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "superseded_by": { "type": "string", "format": "uri", "description": "Optionally provides the metadata URI for the superseding report." }, "deprecation_date": { "type": "string", "format": "date-time", "description": "The GMT time when the report will no longer be available. When a report is past its `deprecation_date` it will no longer appear in the #endpoint:zMKJNurbLQddPfSfN. All endpoints having to do specifically with that report will return a 410 GONE response." } }, "required": [ "deprecation_date" ] } }, "required": [ "Name", "Version", "URI_Data", "URI_Meta" ] }, { "type": "object", "properties": { "Type": { "type": "string" }, "currency": { "type": "string", "description": "Provides information about the currency of the `metrics` fields typed as \"money\".\n\nWhen set to \"campaign currency\", the currency varies from record to record. To determine the currency for a particular record, the campaign_currency_code `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the currency for all records of the report." }, "data_retention": { "type": "string", "description": "Indicates how far back data is available. This can be a date, datetime, or time window as specified by the \"time_window\" and \"Special Time Windows\" sections of #docTextSection:GYrNjxjRCDjDrqcu7. This property should be used very loosely. It may not be accurate. It is meant to give a general idea." }, "default_metrics": { "type": "array", "description": "This is the list of metrics that will be returned if the `metrics` parameter is not specified in a call to the #endpoint:kbWhxp8szYZXNMBre endpoint.", "items": { "type": "string" } }, "structure": { "type": "object", "required": [ "time_field", "dimensions", "metrics" ], "properties": { "time_field": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "dimensions": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "metrics": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." } } }, "time_aggregation": { "type": "string", "description": "This property indicates the finest granularity of the `time_field`. For reports with a `time_field` of the `datetime` type, this will be \"by_hour\", \"by_day\", etc. When the type is `interval`, this will be \"various\"." }, "time_rollups": { "type": "array", "description": "This property indicates the available levels of granularity for the `time_field`. It lists the valid values of the `time_rollup` parameter used for the #endpoint:kbWhxp8szYZXNMBre endpoint. For reports with a `time_field` of the `datetime` type, this tends to be a combination of \"by_hour\", \"by_day\", \"by_week\", \"by_month\", \"all\", etc. When the type is `interval`, this will only include \"all\".", "items": { "type": "string" } }, "time_windows": { "type": "array", "description": "Lists the acceptable formats for the `time_window` parameter used by the #endpoint:kbWhxp8szYZXNMBre endpoint. Some values may be used as is, others may need to be modified. For details see the time_window section of #docTextSection:GYrNjxjRCDjDrqcu7.", "items": { "type": "string" } }, "timezone": { "type": "string", "description": "Provides information about the timezone of the `time_field` for the report.\n\nWhen set to \"campaign timezone\", the timezone varies from record to record. To determine the currency for a particular record, the campaign_timezone `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the timezone for all records of the report." } }, "required": [ "default_metrics", "structure", "time_rollups", "time_windows" ] } ] } } }, "description": "Get Audience Index Meta" } }, "/audience_index_pixel": { "get": { "operationId": "GET_audience_index_pixel", "summary": "Audience Index Pixel", "tags": [ "Reports" ], "description": "Special index metrics for comparing your site visitors to 3rd party segments. Broken out by audience name and pixel. Currently available in one interval: last 14 days.", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" }, { "name": "dimensions", "in": "query", "description": "Selects the dimension fields to use in grouping rows.\n\nThis should be a comma-separated list of dimension field names.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": true, "type": "string" }, { "name": "metrics", "in": "query", "description": "Controls the selection of metric fields.\n\nThis should be a comma-separated list of metric field names.\n\nIf not specified, this will default to the metric fields specified by the `default_metrics` property of the #endpoint:XLZxmeHNEAsLXfPht.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": false, "type": "string" }, { "name": "filter", "in": "query", "description": "Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": true, "type": "string" }, { "name": "having", "in": "query", "description": "Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": false, "type": "string" }, { "name": "time_rollup", "in": "query", "description": "The allowed values are specified by the time_rollups report meta property. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "time_window", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "start_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": false, "type": "string", "default": "yesterday" }, { "name": "order", "in": "query", "description": "Controls the sorting of the groups.\n\nThis should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed.\n\nThe first field has the most significance in sorting.", "required": false, "type": "string" }, { "name": "page_limit", "in": "query", "description": "Controls the maximum number of rows of data.\n\nThis parameter is required, if page_offset is one or greater.", "required": false, "type": "integer", "minimum": 1, "default": "unlimited" }, { "name": "page_offset", "in": "query", "description": "Controls how many pages to skip.", "required": false, "type": "integer", "minimum": 0 }, { "name": "precision", "in": "query", "description": "Controls how many digits to the right of the decimal places to display for float types.", "required": false, "type": "integer", "minimum": 0, "maximum": 8, "default": 8 }, { "name": "Accept-Encoding:", "in": "header", "description": "If the client supports the compression methods also supported by the server (currently `gzip` and `deflate`), the response data set (`text`\\/`csv`) will be returned in a compressed format. The metadata and error responses will not be compressed.\n\nIn order to receive the data in compressed format, the client must use the HTTP request header `Accept-Encoding`, and enumerate the preferred compression methods (see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). If the header `Accept-Encoding` is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format.\n\n ### request \n Accept-Encoding: gzip,deflate \n\n ### response \n Content-Encoding: gzip \n Content-Type: text/csv; charset=UTF-8 ", "type": "string", "enum": [ "gzip,deflate" ] }, { "name": "If-Modified-Since", "in": "header", "description": "If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body.\n\nIf the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header.", "type": "string", "format": "date-time" } ], "responses": { "200": { "description": "" }, "304": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } } } }, "/audience_index_pixel/meta": { "get": { "operationId": "GET_audience_index_pixel-meta", "summary": "Audience Index Pixel Meta", "tags": [ "Reports" ], "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" } ], "responses": { "200": { "description": "", "schema": { "title": "Full Report Description", "allOf": [ { "title": "Brief Report Description", "type": "object", "properties": { "Name": { "type": "string", "description": "This is the human-readable name of the report. It is not recognized by any API input." }, "Version": { "type": "integer", "description": "This is the version of the report. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details." }, "Description": { "type": "string" }, "URI_Data": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:kbWhxp8szYZXNMBre endpoint." }, "URI_Meta": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:XLZxmeHNEAsLXfPht." }, "Transition": { "type": "object", "description": "Reports may change over time. This object will be present if the report will undergo a breaking change. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "replaced_by": { "type": "string", "format": "uri", "description": "The URL where the metadata for the next version of the report may be found." }, "transition_date": { "type": "string", "format": "date-time", "description": "After this GMT time the current version of the report will no longer be available." }, "next_version": { "type": "integer", "description": "The version replacing the current version of the report." } }, "required": [ "replaced_by", "transition_date", "next_version" ] }, "Deprecation": { "type": "object", "description": "Reports may be deprecated all together, or superseded by another report. This object will be present if the report is scheduled for deprecation. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "superseded_by": { "type": "string", "format": "uri", "description": "Optionally provides the metadata URI for the superseding report." }, "deprecation_date": { "type": "string", "format": "date-time", "description": "The GMT time when the report will no longer be available. When a report is past its `deprecation_date` it will no longer appear in the #endpoint:zMKJNurbLQddPfSfN. All endpoints having to do specifically with that report will return a 410 GONE response." } }, "required": [ "deprecation_date" ] } }, "required": [ "Name", "Version", "URI_Data", "URI_Meta" ] }, { "type": "object", "properties": { "Type": { "type": "string" }, "currency": { "type": "string", "description": "Provides information about the currency of the `metrics` fields typed as \"money\".\n\nWhen set to \"campaign currency\", the currency varies from record to record. To determine the currency for a particular record, the campaign_currency_code `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the currency for all records of the report." }, "data_retention": { "type": "string", "description": "Indicates how far back data is available. This can be a date, datetime, or time window as specified by the \"time_window\" and \"Special Time Windows\" sections of #docTextSection:GYrNjxjRCDjDrqcu7. This property should be used very loosely. It may not be accurate. It is meant to give a general idea." }, "default_metrics": { "type": "array", "description": "This is the list of metrics that will be returned if the `metrics` parameter is not specified in a call to the #endpoint:kbWhxp8szYZXNMBre endpoint.", "items": { "type": "string" } }, "structure": { "type": "object", "required": [ "time_field", "dimensions", "metrics" ], "properties": { "time_field": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "dimensions": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "metrics": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." } } }, "time_aggregation": { "type": "string", "description": "This property indicates the finest granularity of the `time_field`. For reports with a `time_field` of the `datetime` type, this will be \"by_hour\", \"by_day\", etc. When the type is `interval`, this will be \"various\"." }, "time_rollups": { "type": "array", "description": "This property indicates the available levels of granularity for the `time_field`. It lists the valid values of the `time_rollup` parameter used for the #endpoint:kbWhxp8szYZXNMBre endpoint. For reports with a `time_field` of the `datetime` type, this tends to be a combination of \"by_hour\", \"by_day\", \"by_week\", \"by_month\", \"all\", etc. When the type is `interval`, this will only include \"all\".", "items": { "type": "string" } }, "time_windows": { "type": "array", "description": "Lists the acceptable formats for the `time_window` parameter used by the #endpoint:kbWhxp8szYZXNMBre endpoint. Some values may be used as is, others may need to be modified. For details see the time_window section of #docTextSection:GYrNjxjRCDjDrqcu7.", "items": { "type": "string" } }, "timezone": { "type": "string", "description": "Provides information about the timezone of the `time_field` for the report.\n\nWhen set to \"campaign timezone\", the timezone varies from record to record. To determine the currency for a particular record, the campaign_timezone `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the timezone for all records of the report." } }, "required": [ "default_metrics", "structure", "time_rollups", "time_windows" ] } ] } } }, "description": "Get Audience Index Pixel Meta" } }, "/day_part": { "get": { "operationId": "GET_day_part", "summary": "Day Part", "tags": [ "Reports" ], "description": "Standard performance metrics broken out by time of day and day of week. Available in standard intervals.", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" }, { "name": "dimensions", "in": "query", "description": "Selects the dimension fields to use in grouping rows.\n\nThis should be a comma-separated list of dimension field names.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": true, "type": "string" }, { "name": "metrics", "in": "query", "description": "Controls the selection of metric fields.\n\nThis should be a comma-separated list of metric field names.\n\nIf not specified, this will default to the metric fields specified by the `default_metrics` property of the #endpoint:XLZxmeHNEAsLXfPht.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": false, "type": "string" }, { "name": "filter", "in": "query", "description": "Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": true, "type": "string" }, { "name": "having", "in": "query", "description": "Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": false, "type": "string" }, { "name": "time_rollup", "in": "query", "description": "The allowed values are specified by the time_rollups report meta property. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "time_window", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "start_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": false, "type": "string", "default": "yesterday" }, { "name": "order", "in": "query", "description": "Controls the sorting of the groups.\n\nThis should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed.\n\nThe first field has the most significance in sorting.", "required": false, "type": "string" }, { "name": "page_limit", "in": "query", "description": "Controls the maximum number of rows of data.\n\nThis parameter is required, if page_offset is one or greater.", "required": false, "type": "integer", "minimum": 1, "default": "unlimited" }, { "name": "page_offset", "in": "query", "description": "Controls how many pages to skip.", "required": false, "type": "integer", "minimum": 0 }, { "name": "precision", "in": "query", "description": "Controls how many digits to the right of the decimal places to display for float types.", "required": false, "type": "integer", "minimum": 0, "maximum": 8, "default": 8 }, { "name": "Accept-Encoding:", "in": "header", "description": "If the client supports the compression methods also supported by the server (currently `gzip` and `deflate`), the response data set (`text`\\/`csv`) will be returned in a compressed format. The metadata and error responses will not be compressed.\n\nIn order to receive the data in compressed format, the client must use the HTTP request header `Accept-Encoding`, and enumerate the preferred compression methods (see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). If the header `Accept-Encoding` is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format.\n\n ### request \n Accept-Encoding: gzip,deflate \n\n ### response \n Content-Encoding: gzip \n Content-Type: text/csv; charset=UTF-8 ", "type": "string", "enum": [ "gzip,deflate" ] }, { "name": "If-Modified-Since", "in": "header", "description": "If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body.\n\nIf the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header.", "type": "string", "format": "date-time" } ], "responses": { "200": { "description": "" }, "304": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } } } }, "/day_part/meta": { "get": { "operationId": "GET_day_part-meta", "summary": "Day Part Meta", "tags": [ "Reports" ], "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" } ], "responses": { "200": { "description": "", "schema": { "title": "Full Report Description", "allOf": [ { "title": "Brief Report Description", "type": "object", "properties": { "Name": { "type": "string", "description": "This is the human-readable name of the report. It is not recognized by any API input." }, "Version": { "type": "integer", "description": "This is the version of the report. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details." }, "Description": { "type": "string" }, "URI_Data": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:kbWhxp8szYZXNMBre endpoint." }, "URI_Meta": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:XLZxmeHNEAsLXfPht." }, "Transition": { "type": "object", "description": "Reports may change over time. This object will be present if the report will undergo a breaking change. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "replaced_by": { "type": "string", "format": "uri", "description": "The URL where the metadata for the next version of the report may be found." }, "transition_date": { "type": "string", "format": "date-time", "description": "After this GMT time the current version of the report will no longer be available." }, "next_version": { "type": "integer", "description": "The version replacing the current version of the report." } }, "required": [ "replaced_by", "transition_date", "next_version" ] }, "Deprecation": { "type": "object", "description": "Reports may be deprecated all together, or superseded by another report. This object will be present if the report is scheduled for deprecation. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "superseded_by": { "type": "string", "format": "uri", "description": "Optionally provides the metadata URI for the superseding report." }, "deprecation_date": { "type": "string", "format": "date-time", "description": "The GMT time when the report will no longer be available. When a report is past its `deprecation_date` it will no longer appear in the #endpoint:zMKJNurbLQddPfSfN. All endpoints having to do specifically with that report will return a 410 GONE response." } }, "required": [ "deprecation_date" ] } }, "required": [ "Name", "Version", "URI_Data", "URI_Meta" ] }, { "type": "object", "properties": { "Type": { "type": "string" }, "currency": { "type": "string", "description": "Provides information about the currency of the `metrics` fields typed as \"money\".\n\nWhen set to \"campaign currency\", the currency varies from record to record. To determine the currency for a particular record, the campaign_currency_code `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the currency for all records of the report." }, "data_retention": { "type": "string", "description": "Indicates how far back data is available. This can be a date, datetime, or time window as specified by the \"time_window\" and \"Special Time Windows\" sections of #docTextSection:GYrNjxjRCDjDrqcu7. This property should be used very loosely. It may not be accurate. It is meant to give a general idea." }, "default_metrics": { "type": "array", "description": "This is the list of metrics that will be returned if the `metrics` parameter is not specified in a call to the #endpoint:kbWhxp8szYZXNMBre endpoint.", "items": { "type": "string" } }, "structure": { "type": "object", "required": [ "time_field", "dimensions", "metrics" ], "properties": { "time_field": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "dimensions": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "metrics": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." } } }, "time_aggregation": { "type": "string", "description": "This property indicates the finest granularity of the `time_field`. For reports with a `time_field` of the `datetime` type, this will be \"by_hour\", \"by_day\", etc. When the type is `interval`, this will be \"various\"." }, "time_rollups": { "type": "array", "description": "This property indicates the available levels of granularity for the `time_field`. It lists the valid values of the `time_rollup` parameter used for the #endpoint:kbWhxp8szYZXNMBre endpoint. For reports with a `time_field` of the `datetime` type, this tends to be a combination of \"by_hour\", \"by_day\", \"by_week\", \"by_month\", \"all\", etc. When the type is `interval`, this will only include \"all\".", "items": { "type": "string" } }, "time_windows": { "type": "array", "description": "Lists the acceptable formats for the `time_window` parameter used by the #endpoint:kbWhxp8szYZXNMBre endpoint. Some values may be used as is, others may need to be modified. For details see the time_window section of #docTextSection:GYrNjxjRCDjDrqcu7.", "items": { "type": "string" } }, "timezone": { "type": "string", "description": "Provides information about the timezone of the `time_field` for the report.\n\nWhen set to \"campaign timezone\", the timezone varies from record to record. To determine the currency for a particular record, the campaign_timezone `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the timezone for all records of the report." } }, "required": [ "default_metrics", "structure", "time_rollups", "time_windows" ] } ] } } }, "description": "Get Day Part Meta" } }, "/deals": { "get": { "operationId": "GET_deals", "summary": "Deals", "tags": [ "Reports" ], "description": "See or query the Meta Endpoint for required fields and parameters.\r\n\r\nBackground:\r\n\r\nThe Deals endpoint contains metrics describing the path from a matched bid opportunity (biddable) to a delivered impression (win) for private marketplace deals. Metrics from this endpoint will allow traders to observe the health of one or more deals. This will allow traders to make a more informed decision about what deals would be an ideal supply source for a particular strategy before committing test budget to it. Additionally, these metrics will help traders troubleshoot strategies targeting PMPs by providing deal win/loss metrics in isolation rather than having them tied to a creative or strategy. This helps traders understand how a deal is affecting their ability to scale more quickly and accurately.\r\n\r\nUpdate Times:\r\n\r\nThis endpoint refreshes at the top of every hour, adding 1 hour of data within every refresh, on a one hour delay. For example, data from 1:00 – 1:59 AM will become available at roughly 3:00 AM.\r\n\r\nAuthorization:\r\n\r\nThe deals endpoint uses the Private Marketplace Exchange (PMP-E) api for authorization - https://mediamath-pmp.api-docs.io/v1/private-marketplace-exchange-pmp-e/deals. Through the /deals endpoint, users can only receive reporting on deals in which their user is permissioned to the owner entity of the deal. A user permissioned to the owner entity of a deal indicates that the user has both read and write access of the deal. \r\n\r\nTo check what deals your user has read and write access to within a particular organization, please make the following get request to the Private Marketplace Exchange API:\r\nhttps://api.mediamath.com/media/v1.0/deals?owner.organization_id=[organization_id]\r\n\r\nRequired Access Fields\r\n\r\nAPI calls must filter by the combination of organization id and deal id. Calls can include only one organization id and one to many deal id's as long as all of the deals belong to the organization. For example:\r\n\r\nfilter=organization_id%3D[organization_id]%26deal_id%3D[deal_id]%2C[deal_id]", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" }, { "name": "dimensions", "in": "query", "description": "Selects the dimension fields to use in grouping rows.\n\nThis should be a comma-separated list of dimension field names.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": true, "type": "string" }, { "name": "metrics", "in": "query", "description": "Controls the selection of metric fields.\n\nThis should be a comma-separated list of metric field names.\n\nIf not specified, this will default to the metric fields specified by the `default_metrics` property of the #endpoint:XLZxmeHNEAsLXfPht.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": false, "type": "string" }, { "name": "filter", "in": "query", "description": "Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": true, "type": "string" }, { "name": "having", "in": "query", "description": "Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": false, "type": "string" }, { "name": "time_rollup", "in": "query", "description": "The allowed values are specified by the time_rollups report meta property. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "time_window", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "start_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": false, "type": "string", "default": "yesterday" }, { "name": "order", "in": "query", "description": "Controls the sorting of the groups.\n\nThis should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed.\n\nThe first field has the most significance in sorting.", "required": false, "type": "string" }, { "name": "page_limit", "in": "query", "description": "Controls the maximum number of rows of data.\n\nThis parameter is required, if page_offset is one or greater.", "required": false, "type": "integer", "minimum": 1, "default": "unlimited" }, { "name": "page_offset", "in": "query", "description": "Controls how many pages to skip.", "required": false, "type": "integer", "minimum": 0 }, { "name": "precision", "in": "query", "description": "Controls how many digits to the right of the decimal places to display for float types.", "required": false, "type": "integer", "minimum": 0, "maximum": 8, "default": 8 }, { "name": "Accept-Encoding:", "in": "header", "description": "If the client supports the compression methods also supported by the server (currently `gzip` and `deflate`), the response data set (`text`\\/`csv`) will be returned in a compressed format. The metadata and error responses will not be compressed.\n\nIn order to receive the data in compressed format, the client must use the HTTP request header `Accept-Encoding`, and enumerate the preferred compression methods (see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). If the header `Accept-Encoding` is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format.\n\n ### request \n Accept-Encoding: gzip,deflate \n\n ### response \n Content-Encoding: gzip \n Content-Type: text/csv; charset=UTF-8 ", "type": "string", "enum": [ "gzip,deflate" ] }, { "name": "If-Modified-Since", "in": "header", "description": "If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body.\n\nIf the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header.", "type": "string", "format": "date-time" } ], "responses": { "200": { "description": "" }, "304": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } } } }, "/deals/meta": { "get": { "operationId": "GET_deals-meta", "summary": "Deals Meta", "tags": [ "Reports" ], "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "Description": { "type": "string" }, "Name": { "type": "string" }, "Type": { "type": "string" }, "URI_Data": { "type": "string" }, "URI_Meta": { "type": "string" }, "Version": { "type": "integer" }, "currency": { "type": "string" }, "data_retention": { "type": "string" }, "default_metrics": { "type": "array", "items": { "type": "string" } }, "structure": { "type": "object", "properties": { "dimensions": { "type": "object", "properties": { "deal_currency_code": { "type": "object", "properties": { "maxLength": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "deal_end_date": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "deal_external_id": { "type": "object", "properties": { "maxLength": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "deal_id": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "deal_name": { "type": "object", "properties": { "maxLength": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "deal_price": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "deal_price_method": { "type": "object", "properties": { "maxLength": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } } }, "deal_price_type": { "type": "object", "properties": { "maxLength": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } } }, "deal_start_date": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "exchange_id": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "organization_id": { "type": "object", "properties": { "access": { "type": "boolean" }, "name": { "type": "string" }, "type": { "type": "string" } } } } }, "metrics": { "type": "object", "properties": { "bid_rate": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "biddables": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "bids": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "win_rate": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } }, "wins": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } } } }, "time_field": { "type": "object", "properties": { "date": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } } } } } }, "time_aggregation": { "type": "string" }, "time_rollups": { "type": "array", "items": { "type": "string" } }, "time_windows": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string" } } } } }, "description": "Get Deals Meta" } }, "/device_technology": { "get": { "operationId": "GET_device_technology", "summary": "Device Technology", "tags": [ "Reports" ], "description": "Standard performance metrics broken out by technology dimensions including browser, operating system, and connection type. Available in custom date ranges or intervals with the option to aggregate by day, week, or month.\n\n## Versions\n\nThe API allows you to determine the version of the Device Technology Report by presenting a query parameter of `?v1` or `?v2`.\n\nStarting October 3rd, 2017 `v2` reports will include:\n\n- Device Brand – eg: Apple, Amazon, and Google\n- Device Model – eg: iPhone, Kindle Fire, Pixel\n- Browser Version – eg: Google Chrome\n- OS Version – eg: Windows 10\n\nThis insight will allow you to plan and assess performance based on device and browser, now inclusive of Mobile devices. Please note this release does not include targeting for these fields.\n\nThe `v2` reports will return data starting from September 2nd, 2017. New data will be added to the reports moving forward, accumulating to the full 90 days of data; the max number of days a user is currently able to pull technology report data for.\n\n* All existing saved/scheduled technology reports in Data Export will continue to pull data from the old reporting framework until November 1st, 2017. However, these reports will no longer be editable, meaning you may only export or deactivate the reports in the interim.\n* Additionally, all currently saved/scheduled technology reports will be **automatically deactivated on November 1st, 2017.**\n* From November 1st, 2017 technology reports will pull data from the `v2` version of the reports by default.\n* From November 1st, 2017 technology reports that query the `v1` version will result in a 304\n* The export will also contain 31 days of data starting from September 2nd, 2017 and accumulate to the full 90 days.\n\n\n## Migration\n\nAfter November 1st, any requests to the `device_technology` endpoint that specify removed metrics *will fail with an 'invalid request' error*. It is strongly recommended that you compare the v1 and v2 definitions of the device technology report /meta endpoint.\n\n## Dimensions\n\n- Added `device_type`\n- Added `os_version`\n- Added `operating_system`\n- Added `inventory_type`\n- Added `device_model`\n- Added `device_make`\n- Added `browser_version`\n- Added `browser`\n\n- Removed `browser_id`\n- Removed `browser_name`\n- Removed `device_id`\n- Removed `device_name`\n- Removed `inventory_type_id`\n- Removed `inventory_type_name`\n- Removed `os_id`\n- Removed `os_name`\n\n\n## Metrics\n\n- Added `viewability_rate_100_percent`\n- Added `viewability_rate`\n- Added `in_view`\n- Added `in_view_100_percent`\n- Added `in_view_15_seconds`\n- Added `in_view_15_seconds_rate`\n- Added `in_view_5_seconds`\n- Added `in_view_5_seconds_rate`\n- Added `measurability_rate`\n- Added `measurable`\n- Added `media_cost_vcpm`\n- Added `total_ad_cost_vcpm`\n- Added `total_spend_vcpm`\n\n## Time Windows\n\n- Added `campaign_to_date`", "parameters": [ { "name": "v1", "in": "query", "type": "string" }, { "name": "v2", "in": "query", "type": "string" }, { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" }, { "name": "dimensions", "in": "query", "description": "Selects the dimension fields to use in grouping rows.\n\nThis should be a comma-separated list of dimension field names.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": true, "type": "string" }, { "name": "metrics", "in": "query", "description": "Controls the selection of metric fields.\n\nThis should be a comma-separated list of metric field names.\n\nIf not specified, this will default to the metric fields specified by the `default_metrics` property of the #endpoint:XLZxmeHNEAsLXfPht.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": false, "type": "string" }, { "name": "filter", "in": "query", "description": "Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": true, "type": "string" }, { "name": "having", "in": "query", "description": "Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": false, "type": "string" }, { "name": "time_rollup", "in": "query", "description": "The allowed values are specified by the time_rollups report meta property. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "time_window", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "start_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": false, "type": "string", "default": "yesterday" }, { "name": "order", "in": "query", "description": "Controls the sorting of the groups.\n\nThis should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed.\n\nThe first field has the most significance in sorting.", "required": false, "type": "string" }, { "name": "page_limit", "in": "query", "description": "Controls the maximum number of rows of data.\n\nThis parameter is required, if page_offset is one or greater.", "required": false, "type": "integer", "minimum": 1, "default": "unlimited" }, { "name": "page_offset", "in": "query", "description": "Controls how many pages to skip.", "required": false, "type": "integer", "minimum": 0 }, { "name": "precision", "in": "query", "description": "Controls how many digits to the right of the decimal places to display for float types.", "required": false, "type": "integer", "minimum": 0, "maximum": 8, "default": 8 }, { "name": "Accept-Encoding:", "in": "header", "description": "If the client supports the compression methods also supported by the server (currently `gzip` and `deflate`), the response data set (`text`\\/`csv`) will be returned in a compressed format. The metadata and error responses will not be compressed.\n\nIn order to receive the data in compressed format, the client must use the HTTP request header `Accept-Encoding`, and enumerate the preferred compression methods (see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). If the header `Accept-Encoding` is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format.\n\n ### request \n Accept-Encoding: gzip,deflate \n\n ### response \n Content-Encoding: gzip \n Content-Type: text/csv; charset=UTF-8 ", "type": "string", "enum": [ "gzip,deflate" ] }, { "name": "If-Modified-Since", "in": "header", "description": "If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body.\n\nIf the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header.", "type": "string", "format": "date-time" } ], "responses": { "200": { "description": "" }, "304": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } } } }, "/device_technology/meta": { "get": { "operationId": "GET_device_technology-meta", "summary": "Device Technology Meta", "tags": [ "Reports" ], "description": "## Versions\n\nThe API allows you to determine the version of the Device Technology Report by presenting a query parameter of `?v1` or `?v2`.\n\nStarting October 3rd, 2017 `v2` reports will include:\n\n- Device Brand – eg: Apple, Amazon, and Google\n- Device Model – eg: iPhone, Kindle Fire, Pixel\n- Browser Version – eg: Google Chrome\n- OS Version – eg: Windows 10\n\nThis insight will allow you to plan and assess performance based on device and browser, now inclusive of Mobile devices. Please note this release does not include targeting for these fields.\n\nInitially, the `v2` reports will only contain 31 days of data starting from September 2nd, 2017. New data will be added to the reports moving forward, accumulating to the full 90 days of data; the max number of days a user is currently able to pull technology report data for.\n\n* All existing saved/scheduled technology reports in Data Export will continue to pull data from the old reporting framework until November 1st, 2017. However, these reports will no longer be editable, meaning you may only export or deactivate the reports in the interim.\n* Additionally, all currently saved/scheduled technology reports will be **automatically deactivated on November 1st, 2017.**\n* From November 1st, 2017 technology reports will pull data from the `v2` version of the reports by default.\n* The export will also contain 31 days of data starting from September 2nd, 2017 and accumulate to the full 90 days.", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" } ], "responses": { "200": { "description": "", "schema": { "title": "Full Report Description", "allOf": [ { "title": "Brief Report Description", "type": "object", "properties": { "Name": { "type": "string", "description": "This is the human-readable name of the report. It is not recognized by any API input." }, "Version": { "type": "integer", "description": "This is the version of the report. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details." }, "Description": { "type": "string" }, "URI_Data": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:kbWhxp8szYZXNMBre endpoint." }, "URI_Meta": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:XLZxmeHNEAsLXfPht." }, "Transition": { "type": "object", "description": "Reports may change over time. This object will be present if the report will undergo a breaking change. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "replaced_by": { "type": "string", "format": "uri", "description": "The URL where the metadata for the next version of the report may be found." }, "transition_date": { "type": "string", "format": "date-time", "description": "After this GMT time the current version of the report will no longer be available." }, "next_version": { "type": "integer", "description": "The version replacing the current version of the report." } }, "required": [ "replaced_by", "transition_date", "next_version" ] }, "Deprecation": { "type": "object", "description": "Reports may be deprecated all together, or superseded by another report. This object will be present if the report is scheduled for deprecation. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "superseded_by": { "type": "string", "format": "uri", "description": "Optionally provides the metadata URI for the superseding report." }, "deprecation_date": { "type": "string", "format": "date-time", "description": "The GMT time when the report will no longer be available. When a report is past its `deprecation_date` it will no longer appear in the #endpoint:zMKJNurbLQddPfSfN. All endpoints having to do specifically with that report will return a 410 GONE response." } }, "required": [ "deprecation_date" ] } }, "required": [ "Name", "Version", "URI_Data", "URI_Meta" ] }, { "type": "object", "properties": { "Type": { "type": "string" }, "currency": { "type": "string", "description": "Provides information about the currency of the `metrics` fields typed as \"money\".\n\nWhen set to \"campaign currency\", the currency varies from record to record. To determine the currency for a particular record, the campaign_currency_code `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the currency for all records of the report." }, "data_retention": { "type": "string", "description": "Indicates how far back data is available. This can be a date, datetime, or time window as specified by the \"time_window\" and \"Special Time Windows\" sections of #docTextSection:GYrNjxjRCDjDrqcu7. This property should be used very loosely. It may not be accurate. It is meant to give a general idea." }, "default_metrics": { "type": "array", "description": "This is the list of metrics that will be returned if the `metrics` parameter is not specified in a call to the #endpoint:kbWhxp8szYZXNMBre endpoint.", "items": { "type": "string" } }, "structure": { "type": "object", "required": [ "time_field", "dimensions", "metrics" ], "properties": { "time_field": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "dimensions": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "metrics": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." } } }, "time_aggregation": { "type": "string", "description": "This property indicates the finest granularity of the `time_field`. For reports with a `time_field` of the `datetime` type, this will be \"by_hour\", \"by_day\", etc. When the type is `interval`, this will be \"various\"." }, "time_rollups": { "type": "array", "description": "This property indicates the available levels of granularity for the `time_field`. It lists the valid values of the `time_rollup` parameter used for the #endpoint:kbWhxp8szYZXNMBre endpoint. For reports with a `time_field` of the `datetime` type, this tends to be a combination of \"by_hour\", \"by_day\", \"by_week\", \"by_month\", \"all\", etc. When the type is `interval`, this will only include \"all\".", "items": { "type": "string" } }, "time_windows": { "type": "array", "description": "Lists the acceptable formats for the `time_window` parameter used by the #endpoint:kbWhxp8szYZXNMBre endpoint. Some values may be used as is, others may need to be modified. For details see the time_window section of #docTextSection:GYrNjxjRCDjDrqcu7.", "items": { "type": "string" } }, "timezone": { "type": "string", "description": "Provides information about the timezone of the `time_field` for the report.\n\nWhen set to \"campaign timezone\", the timezone varies from record to record. To determine the currency for a particular record, the campaign_timezone `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the timezone for all records of the report." } }, "required": [ "default_metrics", "structure", "time_rollups", "time_windows" ] } ] } } } } }, "/geo": { "get": { "operationId": "GET_geo", "summary": "Geo", "tags": [ "Reports" ], "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" }, { "name": "dimensions", "in": "query", "description": "Selects the dimension fields to use in grouping rows.\n\nThis should be a comma-separated list of dimension field names.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": true, "type": "string" }, { "name": "metrics", "in": "query", "description": "Controls the selection of metric fields.\n\nThis should be a comma-separated list of metric field names.\n\nIf not specified, this will default to the metric fields specified by the `default_metrics` property of the #endpoint:XLZxmeHNEAsLXfPht.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": false, "type": "string" }, { "name": "filter", "in": "query", "description": "Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": true, "type": "string" }, { "name": "having", "in": "query", "description": "Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": false, "type": "string" }, { "name": "time_rollup", "in": "query", "description": "The allowed values are specified by the time_rollups report meta property. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "time_window", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "start_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": false, "type": "string", "default": "yesterday" }, { "name": "order", "in": "query", "description": "Controls the sorting of the groups.\n\nThis should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed.\n\nThe first field has the most significance in sorting.", "required": false, "type": "string" }, { "name": "page_limit", "in": "query", "description": "Controls the maximum number of rows of data.\n\nThis parameter is required, if page_offset is one or greater.", "required": false, "type": "integer", "minimum": 1, "default": "unlimited" }, { "name": "page_offset", "in": "query", "description": "Controls how many pages to skip.", "required": false, "type": "integer", "minimum": 0 }, { "name": "precision", "in": "query", "description": "Controls how many digits to the right of the decimal places to display for float types.", "required": false, "type": "integer", "minimum": 0, "maximum": 8, "default": 8 }, { "name": "Accept-Encoding:", "in": "header", "description": "If the client supports the compression methods also supported by the server (currently `gzip` and `deflate`), the response data set (`text`\\/`csv`) will be returned in a compressed format. The metadata and error responses will not be compressed.\n\nIn order to receive the data in compressed format, the client must use the HTTP request header `Accept-Encoding`, and enumerate the preferred compression methods (see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). If the header `Accept-Encoding` is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format.\n\n ### request \n Accept-Encoding: gzip,deflate \n\n ### response \n Content-Encoding: gzip \n Content-Type: text/csv; charset=UTF-8 ", "type": "string", "enum": [ "gzip,deflate" ] }, { "name": "If-Modified-Since", "in": "header", "description": "If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body.\n\nIf the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header.", "type": "string", "format": "date-time" } ], "responses": { "200": { "description": "" }, "304": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "description": "Get Geo" } }, "/geo/meta": { "get": { "operationId": "GET_geo-meta", "summary": "Geo Meta", "tags": [ "Reports" ], "description": "Standard performance metrics broken out by geographic dimensions including country, region, and metro area. Available in standard intervals.", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" } ], "responses": { "200": { "description": "", "schema": { "title": "Full Report Description", "allOf": [ { "title": "Brief Report Description", "type": "object", "properties": { "Name": { "type": "string", "description": "This is the human-readable name of the report. It is not recognized by any API input." }, "Version": { "type": "integer", "description": "This is the version of the report. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details." }, "Description": { "type": "string" }, "URI_Data": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:kbWhxp8szYZXNMBre endpoint." }, "URI_Meta": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:XLZxmeHNEAsLXfPht." }, "Transition": { "type": "object", "description": "Reports may change over time. This object will be present if the report will undergo a breaking change. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "replaced_by": { "type": "string", "format": "uri", "description": "The URL where the metadata for the next version of the report may be found." }, "transition_date": { "type": "string", "format": "date-time", "description": "After this GMT time the current version of the report will no longer be available." }, "next_version": { "type": "integer", "description": "The version replacing the current version of the report." } }, "required": [ "replaced_by", "transition_date", "next_version" ] }, "Deprecation": { "type": "object", "description": "Reports may be deprecated all together, or superseded by another report. This object will be present if the report is scheduled for deprecation. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "superseded_by": { "type": "string", "format": "uri", "description": "Optionally provides the metadata URI for the superseding report." }, "deprecation_date": { "type": "string", "format": "date-time", "description": "The GMT time when the report will no longer be available. When a report is past its `deprecation_date` it will no longer appear in the #endpoint:zMKJNurbLQddPfSfN. All endpoints having to do specifically with that report will return a 410 GONE response." } }, "required": [ "deprecation_date" ] } }, "required": [ "Name", "Version", "URI_Data", "URI_Meta" ] }, { "type": "object", "properties": { "Type": { "type": "string" }, "currency": { "type": "string", "description": "Provides information about the currency of the `metrics` fields typed as \"money\".\n\nWhen set to \"campaign currency\", the currency varies from record to record. To determine the currency for a particular record, the campaign_currency_code `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the currency for all records of the report." }, "data_retention": { "type": "string", "description": "Indicates how far back data is available. This can be a date, datetime, or time window as specified by the \"time_window\" and \"Special Time Windows\" sections of #docTextSection:GYrNjxjRCDjDrqcu7. This property should be used very loosely. It may not be accurate. It is meant to give a general idea." }, "default_metrics": { "type": "array", "description": "This is the list of metrics that will be returned if the `metrics` parameter is not specified in a call to the #endpoint:kbWhxp8szYZXNMBre endpoint.", "items": { "type": "string" } }, "structure": { "type": "object", "required": [ "time_field", "dimensions", "metrics" ], "properties": { "time_field": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "dimensions": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "metrics": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." } } }, "time_aggregation": { "type": "string", "description": "This property indicates the finest granularity of the `time_field`. For reports with a `time_field` of the `datetime` type, this will be \"by_hour\", \"by_day\", etc. When the type is `interval`, this will be \"various\"." }, "time_rollups": { "type": "array", "description": "This property indicates the available levels of granularity for the `time_field`. It lists the valid values of the `time_rollup` parameter used for the #endpoint:kbWhxp8szYZXNMBre endpoint. For reports with a `time_field` of the `datetime` type, this tends to be a combination of \"by_hour\", \"by_day\", \"by_week\", \"by_month\", \"all\", etc. When the type is `interval`, this will only include \"all\".", "items": { "type": "string" } }, "time_windows": { "type": "array", "description": "Lists the acceptable formats for the `time_window` parameter used by the #endpoint:kbWhxp8szYZXNMBre endpoint. Some values may be used as is, others may need to be modified. For details see the time_window section of #docTextSection:GYrNjxjRCDjDrqcu7.", "items": { "type": "string" } }, "timezone": { "type": "string", "description": "Provides information about the timezone of the `time_field` for the report.\n\nWhen set to \"campaign timezone\", the timezone varies from record to record. To determine the currency for a particular record, the campaign_timezone `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the timezone for all records of the report." } }, "required": [ "default_metrics", "structure", "time_rollups", "time_windows" ] } ] } } } } }, "/performance": { "get": { "operationId": "GET_performance", "summary": "Performance", "tags": [ "Reports" ], "description": "Standard performance metrics in campaign currency and broken out by our widest array of dimensions. Available in custom date ranges or intervals with the option to aggregate by day, week, or month.", "parameters": [ { "name": "dimensions", "in": "query", "description": "Selects the dimension fields to use in grouping rows.\n\nThis should be a comma-separated list of dimension field names.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": true, "type": "string" }, { "name": "metrics", "in": "query", "description": "Controls the selection of metric fields.\n\nThis should be a comma-separated list of metric field names.\n\nIf not specified, this will default to the metric fields specified by the `default_metrics` property of the #endpoint:XLZxmeHNEAsLXfPht.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": false, "type": "string" }, { "name": "filter", "in": "query", "description": "Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": true, "type": "string" }, { "name": "having", "in": "query", "description": "Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": false, "type": "string" }, { "name": "time_rollup", "in": "query", "description": "The allowed values are specified by the time_rollups report meta property. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "time_window", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "start_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": false, "type": "string", "default": "yesterday" }, { "name": "order", "in": "query", "description": "Controls the sorting of the groups.\n\nThis should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed.\n\nThe first field has the most significance in sorting.", "required": false, "type": "string" }, { "name": "page_limit", "in": "query", "description": "Controls the maximum number of rows of data.\n\nThis parameter is required, if page_offset is one or greater.", "required": false, "type": "integer", "minimum": 1, "default": "unlimited" }, { "name": "page_offset", "in": "query", "description": "Controls how many pages to skip.", "required": false, "type": "integer", "minimum": 0 }, { "name": "precision", "in": "query", "description": "Controls how many digits to the right of the decimal places to display for float types.", "required": false, "type": "integer", "minimum": 0, "maximum": 8, "default": 8 }, { "name": "Accept-Encoding:", "in": "header", "description": "If the client supports the compression methods also supported by the server (currently `gzip` and `deflate`), the response data set (`text`\\/`csv`) will be returned in a compressed format. The metadata and error responses will not be compressed.\n\nIn order to receive the data in compressed format, the client must use the HTTP request header `Accept-Encoding`, and enumerate the preferred compression methods (see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). If the header `Accept-Encoding` is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format.\n\n ### request \n Accept-Encoding: gzip,deflate \n\n ### response \n Content-Encoding: gzip \n Content-Type: text/csv; charset=UTF-8 ", "type": "string", "enum": [ "gzip,deflate" ] }, { "name": "If-Modified-Since", "in": "header", "description": "If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body.\n\nIf the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header.", "type": "string", "format": "date-time" }, { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" } ], "responses": { "200": { "description": "" }, "304": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } } } }, "/performance/meta": { "get": { "operationId": "GET_performance-meta", "summary": "Performance Meta", "tags": [ "Reports" ], "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" } ], "responses": { "200": { "description": "", "schema": { "title": "Full Report Description", "allOf": [ { "title": "Brief Report Description", "type": "object", "properties": { "Name": { "type": "string", "description": "This is the human-readable name of the report. It is not recognized by any API input." }, "Version": { "type": "integer", "description": "This is the version of the report. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details." }, "Description": { "type": "string" }, "URI_Data": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:kbWhxp8szYZXNMBre endpoint." }, "URI_Meta": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:XLZxmeHNEAsLXfPht." }, "Transition": { "type": "object", "description": "Reports may change over time. This object will be present if the report will undergo a breaking change. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "replaced_by": { "type": "string", "format": "uri", "description": "The URL where the metadata for the next version of the report may be found." }, "transition_date": { "type": "string", "format": "date-time", "description": "After this GMT time the current version of the report will no longer be available." }, "next_version": { "type": "integer", "description": "The version replacing the current version of the report." } }, "required": [ "replaced_by", "transition_date", "next_version" ] }, "Deprecation": { "type": "object", "description": "Reports may be deprecated all together, or superseded by another report. This object will be present if the report is scheduled for deprecation. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "superseded_by": { "type": "string", "format": "uri", "description": "Optionally provides the metadata URI for the superseding report." }, "deprecation_date": { "type": "string", "format": "date-time", "description": "The GMT time when the report will no longer be available. When a report is past its `deprecation_date` it will no longer appear in the #endpoint:zMKJNurbLQddPfSfN. All endpoints having to do specifically with that report will return a 410 GONE response." } }, "required": [ "deprecation_date" ] } }, "required": [ "Name", "Version", "URI_Data", "URI_Meta" ] }, { "type": "object", "properties": { "Type": { "type": "string" }, "currency": { "type": "string", "description": "Provides information about the currency of the `metrics` fields typed as \"money\".\n\nWhen set to \"campaign currency\", the currency varies from record to record. To determine the currency for a particular record, the campaign_currency_code `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the currency for all records of the report." }, "data_retention": { "type": "string", "description": "Indicates how far back data is available. This can be a date, datetime, or time window as specified by the \"time_window\" and \"Special Time Windows\" sections of #docTextSection:GYrNjxjRCDjDrqcu7. This property should be used very loosely. It may not be accurate. It is meant to give a general idea." }, "default_metrics": { "type": "array", "description": "This is the list of metrics that will be returned if the `metrics` parameter is not specified in a call to the #endpoint:kbWhxp8szYZXNMBre endpoint.", "items": { "type": "string" } }, "structure": { "type": "object", "required": [ "time_field", "dimensions", "metrics" ], "properties": { "time_field": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "dimensions": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "metrics": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." } } }, "time_aggregation": { "type": "string", "description": "This property indicates the finest granularity of the `time_field`. For reports with a `time_field` of the `datetime` type, this will be \"by_hour\", \"by_day\", etc. When the type is `interval`, this will be \"various\"." }, "time_rollups": { "type": "array", "description": "This property indicates the available levels of granularity for the `time_field`. It lists the valid values of the `time_rollup` parameter used for the #endpoint:kbWhxp8szYZXNMBre endpoint. For reports with a `time_field` of the `datetime` type, this tends to be a combination of \"by_hour\", \"by_day\", \"by_week\", \"by_month\", \"all\", etc. When the type is `interval`, this will only include \"all\".", "items": { "type": "string" } }, "time_windows": { "type": "array", "description": "Lists the acceptable formats for the `time_window` parameter used by the #endpoint:kbWhxp8szYZXNMBre endpoint. Some values may be used as is, others may need to be modified. For details see the time_window section of #docTextSection:GYrNjxjRCDjDrqcu7.", "items": { "type": "string" } }, "timezone": { "type": "string", "description": "Provides information about the timezone of the `time_field` for the report.\n\nWhen set to \"campaign timezone\", the timezone varies from record to record. To determine the currency for a particular record, the campaign_timezone `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the timezone for all records of the report." } }, "required": [ "default_metrics", "structure", "time_rollups", "time_windows" ] } ] } } }, "description": "Get Performance Meta" } }, "/postal_code": { "get": { "operationId": "GET_postal_code", "summary": "Postal Code", "tags": [ "Reports" ], "description": "The Postal Code Report breaks out performance metrics by postal code. Use it to optimize and validate strategies that use postal code targeting. \r\n\r\n# API Endpoints\r\n\r\nThe Postal Code Report is available at:\r\n\r\n`$API_BASE/postal_code`\r\n\r\n# Important Fields\r\n\r\n### Report-Specific Dimensions and Metrics\r\n\r\n`postal_code` - The postal code dimension corresponds to postal codes as they are uploaded into t1 for targeting. This includes a country code followed by the postal code, with no space or punctuation. For example, an impression served to a computer at MediaMath's Broadway office (US ZIP code 10018) would have \"us10018\" as its postal code. If a postal code is unknown, it will still be shown with the country code: ex. \"us-unknown\". If not, it will appear as simply \"unknown\". \r\n\r\nNOTE: The postal code report only breaks out strategies by postal code if those strategies are targeting or anti-targeting postal codes. If a strategy stops or starts targeting postal codes, you may see unexpected postal code values in the report for the day that the change was made. This is because the bidder reacts to your targeting changes immediately, but our report only takes them into account when it refreshes. In order to prevent this, it is recommend that users create a dedicated strategy for postal code targeting.\r\n\r\n### Date Range\r\n\r\nThe Postal Code Report is available by day for a rolling 30 days.\r\n\r\n# Updates\r\n\r\nData is updated three times daily.", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" }, { "name": "dimensions", "in": "query", "description": "Selects the dimension fields to use in grouping rows.\n\nThis should be a comma-separated list of dimension field names.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": true, "type": "string" }, { "name": "metrics", "in": "query", "description": "Controls the selection of metric fields.\n\nThis should be a comma-separated list of metric field names.\n\nIf not specified, this will default to the metric fields specified by the `default_metrics` property of the #endpoint:XLZxmeHNEAsLXfPht.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": false, "type": "string" }, { "name": "filter", "in": "query", "description": "Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": true, "type": "string" }, { "name": "having", "in": "query", "description": "Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": false, "type": "string" }, { "name": "time_rollup", "in": "query", "description": "The allowed values are specified by the time_rollups report meta property. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "time_window", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "start_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": false, "type": "string", "default": "yesterday" }, { "name": "order", "in": "query", "description": "Controls the sorting of the groups.\n\nThis should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed.\n\nThe first field has the most significance in sorting.", "required": false, "type": "string" }, { "name": "page_limit", "in": "query", "description": "Controls the maximum number of rows of data.\n\nThis parameter is required, if page_offset is one or greater.", "required": false, "type": "integer", "minimum": 1, "default": "unlimited" }, { "name": "page_offset", "in": "query", "description": "Controls how many pages to skip.", "required": false, "type": "integer", "minimum": 0 }, { "name": "precision", "in": "query", "description": "Controls how many digits to the right of the decimal places to display for float types.", "required": false, "type": "integer", "minimum": 0, "maximum": 8, "default": 8 }, { "name": "Accept-Encoding:", "in": "header", "description": "If the client supports the compression methods also supported by the server (currently `gzip` and `deflate`), the response data set (`text`\\/`csv`) will be returned in a compressed format. The metadata and error responses will not be compressed.\n\nIn order to receive the data in compressed format, the client must use the HTTP request header `Accept-Encoding`, and enumerate the preferred compression methods (see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). If the header `Accept-Encoding` is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format.\n\n ### request \n Accept-Encoding: gzip,deflate \n\n ### response \n Content-Encoding: gzip \n Content-Type: text/csv; charset=UTF-8 ", "type": "string", "enum": [ "gzip,deflate" ] }, { "name": "If-Modified-Since", "in": "header", "description": "If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body.\n\nIf the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header.", "type": "string", "format": "date-time" } ], "responses": { "200": { "description": "" }, "304": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } } } }, "/postal_code/meta": { "get": { "operationId": "GET_postal_code-meta", "summary": "Postal Code Meta", "tags": [ "Reports" ], "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" } ], "responses": { "200": { "description": "", "schema": { "title": "Full Report Description", "allOf": [ { "title": "Brief Report Description", "type": "object", "properties": { "Name": { "type": "string", "description": "This is the human-readable name of the report. It is not recognized by any API input." }, "Version": { "type": "integer", "description": "This is the version of the report. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details." }, "Description": { "type": "string" }, "URI_Data": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:kbWhxp8szYZXNMBre endpoint." }, "URI_Meta": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:XLZxmeHNEAsLXfPht." }, "Transition": { "type": "object", "description": "Reports may change over time. This object will be present if the report will undergo a breaking change. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "replaced_by": { "type": "string", "format": "uri", "description": "The URL where the metadata for the next version of the report may be found." }, "transition_date": { "type": "string", "format": "date-time", "description": "After this GMT time the current version of the report will no longer be available." }, "next_version": { "type": "integer", "description": "The version replacing the current version of the report." } }, "required": [ "replaced_by", "transition_date", "next_version" ] }, "Deprecation": { "type": "object", "description": "Reports may be deprecated all together, or superseded by another report. This object will be present if the report is scheduled for deprecation. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "superseded_by": { "type": "string", "format": "uri", "description": "Optionally provides the metadata URI for the superseding report." }, "deprecation_date": { "type": "string", "format": "date-time", "description": "The GMT time when the report will no longer be available. When a report is past its `deprecation_date` it will no longer appear in the #endpoint:zMKJNurbLQddPfSfN. All endpoints having to do specifically with that report will return a 410 GONE response." } }, "required": [ "deprecation_date" ] } }, "required": [ "Name", "Version", "URI_Data", "URI_Meta" ] }, { "type": "object", "properties": { "Type": { "type": "string" }, "currency": { "type": "string", "description": "Provides information about the currency of the `metrics` fields typed as \"money\".\n\nWhen set to \"campaign currency\", the currency varies from record to record. To determine the currency for a particular record, the campaign_currency_code `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the currency for all records of the report." }, "data_retention": { "type": "string", "description": "Indicates how far back data is available. This can be a date, datetime, or time window as specified by the \"time_window\" and \"Special Time Windows\" sections of #docTextSection:GYrNjxjRCDjDrqcu7. This property should be used very loosely. It may not be accurate. It is meant to give a general idea." }, "default_metrics": { "type": "array", "description": "This is the list of metrics that will be returned if the `metrics` parameter is not specified in a call to the #endpoint:kbWhxp8szYZXNMBre endpoint.", "items": { "type": "string" } }, "structure": { "type": "object", "required": [ "time_field", "dimensions", "metrics" ], "properties": { "time_field": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "dimensions": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "metrics": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." } } }, "time_aggregation": { "type": "string", "description": "This property indicates the finest granularity of the `time_field`. For reports with a `time_field` of the `datetime` type, this will be \"by_hour\", \"by_day\", etc. When the type is `interval`, this will be \"various\"." }, "time_rollups": { "type": "array", "description": "This property indicates the available levels of granularity for the `time_field`. It lists the valid values of the `time_rollup` parameter used for the #endpoint:kbWhxp8szYZXNMBre endpoint. For reports with a `time_field` of the `datetime` type, this tends to be a combination of \"by_hour\", \"by_day\", \"by_week\", \"by_month\", \"all\", etc. When the type is `interval`, this will only include \"all\".", "items": { "type": "string" } }, "time_windows": { "type": "array", "description": "Lists the acceptable formats for the `time_window` parameter used by the #endpoint:kbWhxp8szYZXNMBre endpoint. Some values may be used as is, others may need to be modified. For details see the time_window section of #docTextSection:GYrNjxjRCDjDrqcu7.", "items": { "type": "string" } }, "timezone": { "type": "string", "description": "Provides information about the timezone of the `time_field` for the report.\n\nWhen set to \"campaign timezone\", the timezone varies from record to record. To determine the currency for a particular record, the campaign_timezone `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the timezone for all records of the report." } }, "required": [ "default_metrics", "structure", "time_rollups", "time_windows" ] } ] } } }, "description": "Get Postal Code Meta" } }, "/pulse": { "get": { "operationId": "GET_pulse", "summary": "Pulse", "tags": [ "Reports" ], "description": "Standard performance metrics broken out by standard dimensions, available in precise time windows - down to the hour - with the option to aggregate by hour or day.", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" }, { "name": "dimensions", "in": "query", "description": "Selects the dimension fields to use in grouping rows.\n\nThis should be a comma-separated list of dimension field names.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": true, "type": "string" }, { "name": "metrics", "in": "query", "description": "Controls the selection of metric fields.\n\nThis should be a comma-separated list of metric field names.\n\nIf not specified, this will default to the metric fields specified by the `default_metrics` property of the #endpoint:XLZxmeHNEAsLXfPht.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": false, "type": "string" }, { "name": "filter", "in": "query", "description": "Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": true, "type": "string" }, { "name": "having", "in": "query", "description": "Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": false, "type": "string" }, { "name": "time_rollup", "in": "query", "description": "The allowed values are specified by the time_rollups report meta property. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "time_window", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "start_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": false, "type": "string", "default": "yesterday" }, { "name": "order", "in": "query", "description": "Controls the sorting of the groups.\n\nThis should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed.\n\nThe first field has the most significance in sorting.", "required": false, "type": "string" }, { "name": "page_limit", "in": "query", "description": "Controls the maximum number of rows of data.\n\nThis parameter is required, if page_offset is one or greater.", "required": false, "type": "integer", "minimum": 1, "default": "unlimited" }, { "name": "page_offset", "in": "query", "description": "Controls how many pages to skip.", "required": false, "type": "integer", "minimum": 0 }, { "name": "precision", "in": "query", "description": "Controls how many digits to the right of the decimal places to display for float types.", "required": false, "type": "integer", "minimum": 0, "maximum": 8, "default": 8 }, { "name": "Accept-Encoding:", "in": "header", "description": "If the client supports the compression methods also supported by the server (currently `gzip` and `deflate`), the response data set (`text`\\/`csv`) will be returned in a compressed format. The metadata and error responses will not be compressed.\n\nIn order to receive the data in compressed format, the client must use the HTTP request header `Accept-Encoding`, and enumerate the preferred compression methods (see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). If the header `Accept-Encoding` is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format.\n\n ### request \n Accept-Encoding: gzip,deflate \n\n ### response \n Content-Encoding: gzip \n Content-Type: text/csv; charset=UTF-8 ", "type": "string", "enum": [ "gzip,deflate" ] }, { "name": "If-Modified-Since", "in": "header", "description": "If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body.\n\nIf the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header.", "type": "string", "format": "date-time" } ], "responses": { "200": { "description": "" }, "304": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } } } }, "/pulse/meta": { "get": { "operationId": "GET_pulse-meta", "summary": "Pulse Meta", "tags": [ "Reports" ], "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" } ], "responses": { "200": { "description": "", "schema": { "title": "Full Report Description", "allOf": [ { "title": "Brief Report Description", "type": "object", "properties": { "Name": { "type": "string", "description": "This is the human-readable name of the report. It is not recognized by any API input." }, "Version": { "type": "integer", "description": "This is the version of the report. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details." }, "Description": { "type": "string" }, "URI_Data": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:kbWhxp8szYZXNMBre endpoint." }, "URI_Meta": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:XLZxmeHNEAsLXfPht." }, "Transition": { "type": "object", "description": "Reports may change over time. This object will be present if the report will undergo a breaking change. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "replaced_by": { "type": "string", "format": "uri", "description": "The URL where the metadata for the next version of the report may be found." }, "transition_date": { "type": "string", "format": "date-time", "description": "After this GMT time the current version of the report will no longer be available." }, "next_version": { "type": "integer", "description": "The version replacing the current version of the report." } }, "required": [ "replaced_by", "transition_date", "next_version" ] }, "Deprecation": { "type": "object", "description": "Reports may be deprecated all together, or superseded by another report. This object will be present if the report is scheduled for deprecation. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "superseded_by": { "type": "string", "format": "uri", "description": "Optionally provides the metadata URI for the superseding report." }, "deprecation_date": { "type": "string", "format": "date-time", "description": "The GMT time when the report will no longer be available. When a report is past its `deprecation_date` it will no longer appear in the #endpoint:zMKJNurbLQddPfSfN. All endpoints having to do specifically with that report will return a 410 GONE response." } }, "required": [ "deprecation_date" ] } }, "required": [ "Name", "Version", "URI_Data", "URI_Meta" ] }, { "type": "object", "properties": { "Type": { "type": "string" }, "currency": { "type": "string", "description": "Provides information about the currency of the `metrics` fields typed as \"money\".\n\nWhen set to \"campaign currency\", the currency varies from record to record. To determine the currency for a particular record, the campaign_currency_code `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the currency for all records of the report." }, "data_retention": { "type": "string", "description": "Indicates how far back data is available. This can be a date, datetime, or time window as specified by the \"time_window\" and \"Special Time Windows\" sections of #docTextSection:GYrNjxjRCDjDrqcu7. This property should be used very loosely. It may not be accurate. It is meant to give a general idea." }, "default_metrics": { "type": "array", "description": "This is the list of metrics that will be returned if the `metrics` parameter is not specified in a call to the #endpoint:kbWhxp8szYZXNMBre endpoint.", "items": { "type": "string" } }, "structure": { "type": "object", "required": [ "time_field", "dimensions", "metrics" ], "properties": { "time_field": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "dimensions": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "metrics": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." } } }, "time_aggregation": { "type": "string", "description": "This property indicates the finest granularity of the `time_field`. For reports with a `time_field` of the `datetime` type, this will be \"by_hour\", \"by_day\", etc. When the type is `interval`, this will be \"various\"." }, "time_rollups": { "type": "array", "description": "This property indicates the available levels of granularity for the `time_field`. It lists the valid values of the `time_rollup` parameter used for the #endpoint:kbWhxp8szYZXNMBre endpoint. For reports with a `time_field` of the `datetime` type, this tends to be a combination of \"by_hour\", \"by_day\", \"by_week\", \"by_month\", \"all\", etc. When the type is `interval`, this will only include \"all\".", "items": { "type": "string" } }, "time_windows": { "type": "array", "description": "Lists the acceptable formats for the `time_window` parameter used by the #endpoint:kbWhxp8szYZXNMBre endpoint. Some values may be used as is, others may need to be modified. For details see the time_window section of #docTextSection:GYrNjxjRCDjDrqcu7.", "items": { "type": "string" } }, "timezone": { "type": "string", "description": "Provides information about the timezone of the `time_field` for the report.\n\nWhen set to \"campaign timezone\", the timezone varies from record to record. To determine the currency for a particular record, the campaign_timezone `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the timezone for all records of the report." } }, "required": [ "default_metrics", "structure", "time_rollups", "time_windows" ] } ] } } }, "description": "Get Pulse Meta" } }, "/reach_frequency": { "get": { "operationId": "GET_reach_frequency", "summary": "Reach Frequency", "tags": [ "Reports" ], "description": "The Reach and Frequency report measures the number of unique users your ads are reaching and the frequency with which your users see those ads. Use it to monitor your reach, or to understand how the number of ads a customer sees influences their click and conversion behavior.\r\n\r\n# API Endpoints\r\n\r\nThe Reach and Frequency Report is available at:\r\n\r\n`$API_BASE/reach_frequency`\r\n\r\n# Important Fields\r\n\r\n### Report-Specific Fields\r\n\r\n`frequency` - shows the average number of times a unique user saw media from the given strategy or campaign\r\n\r\n`frequency_bin` - provides bins for ranges of frequency values. It’s useful for creating a histogram to show the distribution of frequency, or for analyzing how frequency correlates to performance metrics.\r\n\r\n`uniques` - measures the number of unique users who viewed an impression from the given campaign or strategy. Uniques are identified using cookies, so this number could be slightly overstated if your audience uses many different devices or clears their cookies often.\r\n\r\nNOTE: Uniques and frequencies are only counted for campaigns and strategies. Including advertiser or organization may be useful as metadata, but if you do not include campaign or strategy, uniques will be aggregated without de-duping and your data will be inaccurate. For this reason, you should always include either the campaign or strategy dimensions.\r\n\r\n### Time Fields\r\n\r\n`reach_frequency` is available as an interval report. It supports four time windows: yesterday, `last_7_days`, `last_14_days`, and `last_30_days`. The only `time_aggregation` available is “all”.\r\n\r\n# Updates\r\n\r\nData is updated daily. Check the Last-Modified date in the header for more specific timing.", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" }, { "name": "dimensions", "in": "query", "description": "Selects the dimension fields to use in grouping rows.\n\nThis should be a comma-separated list of dimension field names.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": true, "type": "string" }, { "name": "metrics", "in": "query", "description": "Controls the selection of metric fields.\n\nThis should be a comma-separated list of metric field names.\n\nIf not specified, this will default to the metric fields specified by the `default_metrics` property of the #endpoint:XLZxmeHNEAsLXfPht.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": false, "type": "string" }, { "name": "filter", "in": "query", "description": "Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": true, "type": "string" }, { "name": "having", "in": "query", "description": "Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": false, "type": "string" }, { "name": "time_rollup", "in": "query", "description": "The allowed values are specified by the time_rollups report meta property. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "time_window", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "start_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": false, "type": "string", "default": "yesterday" }, { "name": "order", "in": "query", "description": "Controls the sorting of the groups.\n\nThis should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed.\n\nThe first field has the most significance in sorting.", "required": false, "type": "string" }, { "name": "page_limit", "in": "query", "description": "Controls the maximum number of rows of data.\n\nThis parameter is required, if page_offset is one or greater.", "required": false, "type": "integer", "minimum": 1, "default": "unlimited" }, { "name": "page_offset", "in": "query", "description": "Controls how many pages to skip.", "required": false, "type": "integer", "minimum": 0 }, { "name": "precision", "in": "query", "description": "Controls how many digits to the right of the decimal places to display for float types.", "required": false, "type": "integer", "minimum": 0, "maximum": 8, "default": 8 }, { "name": "Accept-Encoding:", "in": "header", "description": "If the client supports the compression methods also supported by the server (currently `gzip` and `deflate`), the response data set (`text`\\/`csv`) will be returned in a compressed format. The metadata and error responses will not be compressed.\n\nIn order to receive the data in compressed format, the client must use the HTTP request header `Accept-Encoding`, and enumerate the preferred compression methods (see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). If the header `Accept-Encoding` is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format.\n\n ### request \n Accept-Encoding: gzip,deflate \n\n ### response \n Content-Encoding: gzip \n Content-Type: text/csv; charset=UTF-8 ", "type": "string", "enum": [ "gzip,deflate" ] }, { "name": "If-Modified-Since", "in": "header", "description": "If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body.\n\nIf the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header.", "type": "string", "format": "date-time" } ], "responses": { "200": { "description": "" }, "304": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } } } }, "/reach_frequency/meta": { "get": { "operationId": "GET_reach_frequency-meta", "summary": "Reach Frequency Meta", "tags": [ "Reports" ], "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" } ], "responses": { "200": { "description": "", "schema": { "title": "Full Report Description", "allOf": [ { "title": "Brief Report Description", "type": "object", "properties": { "Name": { "type": "string", "description": "This is the human-readable name of the report. It is not recognized by any API input." }, "Version": { "type": "integer", "description": "This is the version of the report. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details." }, "Description": { "type": "string" }, "URI_Data": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:kbWhxp8szYZXNMBre endpoint." }, "URI_Meta": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:XLZxmeHNEAsLXfPht." }, "Transition": { "type": "object", "description": "Reports may change over time. This object will be present if the report will undergo a breaking change. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "replaced_by": { "type": "string", "format": "uri", "description": "The URL where the metadata for the next version of the report may be found." }, "transition_date": { "type": "string", "format": "date-time", "description": "After this GMT time the current version of the report will no longer be available." }, "next_version": { "type": "integer", "description": "The version replacing the current version of the report." } }, "required": [ "replaced_by", "transition_date", "next_version" ] }, "Deprecation": { "type": "object", "description": "Reports may be deprecated all together, or superseded by another report. This object will be present if the report is scheduled for deprecation. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "superseded_by": { "type": "string", "format": "uri", "description": "Optionally provides the metadata URI for the superseding report." }, "deprecation_date": { "type": "string", "format": "date-time", "description": "The GMT time when the report will no longer be available. When a report is past its `deprecation_date` it will no longer appear in the #endpoint:zMKJNurbLQddPfSfN. All endpoints having to do specifically with that report will return a 410 GONE response." } }, "required": [ "deprecation_date" ] } }, "required": [ "Name", "Version", "URI_Data", "URI_Meta" ] }, { "type": "object", "properties": { "Type": { "type": "string" }, "currency": { "type": "string", "description": "Provides information about the currency of the `metrics` fields typed as \"money\".\n\nWhen set to \"campaign currency\", the currency varies from record to record. To determine the currency for a particular record, the campaign_currency_code `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the currency for all records of the report." }, "data_retention": { "type": "string", "description": "Indicates how far back data is available. This can be a date, datetime, or time window as specified by the \"time_window\" and \"Special Time Windows\" sections of #docTextSection:GYrNjxjRCDjDrqcu7. This property should be used very loosely. It may not be accurate. It is meant to give a general idea." }, "default_metrics": { "type": "array", "description": "This is the list of metrics that will be returned if the `metrics` parameter is not specified in a call to the #endpoint:kbWhxp8szYZXNMBre endpoint.", "items": { "type": "string" } }, "structure": { "type": "object", "required": [ "time_field", "dimensions", "metrics" ], "properties": { "time_field": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "dimensions": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "metrics": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." } } }, "time_aggregation": { "type": "string", "description": "This property indicates the finest granularity of the `time_field`. For reports with a `time_field` of the `datetime` type, this will be \"by_hour\", \"by_day\", etc. When the type is `interval`, this will be \"various\"." }, "time_rollups": { "type": "array", "description": "This property indicates the available levels of granularity for the `time_field`. It lists the valid values of the `time_rollup` parameter used for the #endpoint:kbWhxp8szYZXNMBre endpoint. For reports with a `time_field` of the `datetime` type, this tends to be a combination of \"by_hour\", \"by_day\", \"by_week\", \"by_month\", \"all\", etc. When the type is `interval`, this will only include \"all\".", "items": { "type": "string" } }, "time_windows": { "type": "array", "description": "Lists the acceptable formats for the `time_window` parameter used by the #endpoint:kbWhxp8szYZXNMBre endpoint. Some values may be used as is, others may need to be modified. For details see the time_window section of #docTextSection:GYrNjxjRCDjDrqcu7.", "items": { "type": "string" } }, "timezone": { "type": "string", "description": "Provides information about the timezone of the `time_field` for the report.\n\nWhen set to \"campaign timezone\", the timezone varies from record to record. To determine the currency for a particular record, the campaign_timezone `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the timezone for all records of the report." } }, "required": [ "default_metrics", "structure", "time_rollups", "time_windows" ] } ] } } }, "description": "Get Reach Frequency Meta" } }, "/site_transparency": { "get": { "operationId": "GET_site_transparency", "summary": "Site Transparency", "tags": [ "Reports" ], "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" }, { "name": "dimensions", "in": "query", "description": "Selects the dimension fields to use in grouping rows.\n\nThis should be a comma-separated list of dimension field names.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": true, "type": "string" }, { "name": "metrics", "in": "query", "description": "Controls the selection of metric fields.\n\nThis should be a comma-separated list of metric field names.\n\nIf not specified, this will default to the metric fields specified by the `default_metrics` property of the #endpoint:XLZxmeHNEAsLXfPht.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": false, "type": "string" }, { "name": "filter", "in": "query", "description": "Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": true, "type": "string" }, { "name": "having", "in": "query", "description": "Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": false, "type": "string" }, { "name": "time_rollup", "in": "query", "description": "The allowed values are specified by the time_rollups report meta property. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "time_window", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "start_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": false, "type": "string", "default": "yesterday" }, { "name": "order", "in": "query", "description": "Controls the sorting of the groups.\n\nThis should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed.\n\nThe first field has the most significance in sorting.", "required": false, "type": "string" }, { "name": "page_limit", "in": "query", "description": "Controls the maximum number of rows of data.\n\nThis parameter is required, if page_offset is one or greater.", "required": false, "type": "integer", "minimum": 1, "default": "unlimited" }, { "name": "page_offset", "in": "query", "description": "Controls how many pages to skip.", "required": false, "type": "integer", "minimum": 0 }, { "name": "precision", "in": "query", "description": "Controls how many digits to the right of the decimal places to display for float types.", "required": false, "type": "integer", "minimum": 0, "maximum": 8, "default": 8 }, { "name": "Accept-Encoding:", "in": "header", "description": "If the client supports the compression methods also supported by the server (currently `gzip` and `deflate`), the response data set (`text`\\/`csv`) will be returned in a compressed format. The metadata and error responses will not be compressed.\n\nIn order to receive the data in compressed format, the client must use the HTTP request header `Accept-Encoding`, and enumerate the preferred compression methods (see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). If the header `Accept-Encoding` is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format.\n\n ### request \n Accept-Encoding: gzip,deflate \n\n ### response \n Content-Encoding: gzip \n Content-Type: text/csv; charset=UTF-8 ", "type": "string", "enum": [ "gzip,deflate" ] }, { "name": "If-Modified-Since", "in": "header", "description": "If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body.\n\nIf the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header.", "type": "string", "format": "date-time" } ], "responses": { "200": { "description": "" }, "304": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "description": "Get Site Transparency" } }, "/site_transparency/meta": { "get": { "operationId": "GET_site_transparency-meta", "summary": "Site Transparency Meta", "tags": [ "Reports" ], "description": "Standard performance metrics broken out by the domain of the inventory. Available in standard intervals.", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" } ], "responses": { "200": { "description": "", "schema": { "title": "Full Report Description", "allOf": [ { "title": "Brief Report Description", "type": "object", "properties": { "Name": { "type": "string", "description": "This is the human-readable name of the report. It is not recognized by any API input." }, "Version": { "type": "integer", "description": "This is the version of the report. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details." }, "Description": { "type": "string" }, "URI_Data": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:kbWhxp8szYZXNMBre endpoint." }, "URI_Meta": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:XLZxmeHNEAsLXfPht." }, "Transition": { "type": "object", "description": "Reports may change over time. This object will be present if the report will undergo a breaking change. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "replaced_by": { "type": "string", "format": "uri", "description": "The URL where the metadata for the next version of the report may be found." }, "transition_date": { "type": "string", "format": "date-time", "description": "After this GMT time the current version of the report will no longer be available." }, "next_version": { "type": "integer", "description": "The version replacing the current version of the report." } }, "required": [ "replaced_by", "transition_date", "next_version" ] }, "Deprecation": { "type": "object", "description": "Reports may be deprecated all together, or superseded by another report. This object will be present if the report is scheduled for deprecation. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "superseded_by": { "type": "string", "format": "uri", "description": "Optionally provides the metadata URI for the superseding report." }, "deprecation_date": { "type": "string", "format": "date-time", "description": "The GMT time when the report will no longer be available. When a report is past its `deprecation_date` it will no longer appear in the #endpoint:zMKJNurbLQddPfSfN. All endpoints having to do specifically with that report will return a 410 GONE response." } }, "required": [ "deprecation_date" ] } }, "required": [ "Name", "Version", "URI_Data", "URI_Meta" ] }, { "type": "object", "properties": { "Type": { "type": "string" }, "currency": { "type": "string", "description": "Provides information about the currency of the `metrics` fields typed as \"money\".\n\nWhen set to \"campaign currency\", the currency varies from record to record. To determine the currency for a particular record, the campaign_currency_code `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the currency for all records of the report." }, "data_retention": { "type": "string", "description": "Indicates how far back data is available. This can be a date, datetime, or time window as specified by the \"time_window\" and \"Special Time Windows\" sections of #docTextSection:GYrNjxjRCDjDrqcu7. This property should be used very loosely. It may not be accurate. It is meant to give a general idea." }, "default_metrics": { "type": "array", "description": "This is the list of metrics that will be returned if the `metrics` parameter is not specified in a call to the #endpoint:kbWhxp8szYZXNMBre endpoint.", "items": { "type": "string" } }, "structure": { "type": "object", "required": [ "time_field", "dimensions", "metrics" ], "properties": { "time_field": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "dimensions": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "metrics": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." } } }, "time_aggregation": { "type": "string", "description": "This property indicates the finest granularity of the `time_field`. For reports with a `time_field` of the `datetime` type, this will be \"by_hour\", \"by_day\", etc. When the type is `interval`, this will be \"various\"." }, "time_rollups": { "type": "array", "description": "This property indicates the available levels of granularity for the `time_field`. It lists the valid values of the `time_rollup` parameter used for the #endpoint:kbWhxp8szYZXNMBre endpoint. For reports with a `time_field` of the `datetime` type, this tends to be a combination of \"by_hour\", \"by_day\", \"by_week\", \"by_month\", \"all\", etc. When the type is `interval`, this will only include \"all\".", "items": { "type": "string" } }, "time_windows": { "type": "array", "description": "Lists the acceptable formats for the `time_window` parameter used by the #endpoint:kbWhxp8szYZXNMBre endpoint. Some values may be used as is, others may need to be modified. For details see the time_window section of #docTextSection:GYrNjxjRCDjDrqcu7.", "items": { "type": "string" } }, "timezone": { "type": "string", "description": "Provides information about the timezone of the `time_field` for the report.\n\nWhen set to \"campaign timezone\", the timezone varies from record to record. To determine the currency for a particular record, the campaign_timezone `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the timezone for all records of the report." } }, "required": [ "default_metrics", "structure", "time_rollups", "time_windows" ] } ] } } } } }, "/video": { "get": { "operationId": "GET_video", "summary": "Video", "tags": [ "Reports" ], "description": "Video-specific metrics such as completion rate, skips, and fullscreens broken out by a wide array of dimensions. Available in custom date-ranges or intervals with the option to aggregate by day, week, or month.", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" }, { "name": "dimensions", "in": "query", "description": "Selects the dimension fields to use in grouping rows.\n\nThis should be a comma-separated list of dimension field names.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": true, "type": "string" }, { "name": "metrics", "in": "query", "description": "Controls the selection of metric fields.\n\nThis should be a comma-separated list of metric field names.\n\nIf not specified, this will default to the metric fields specified by the `default_metrics` property of the #endpoint:XLZxmeHNEAsLXfPht.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": false, "type": "string" }, { "name": "filter", "in": "query", "description": "Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": true, "type": "string" }, { "name": "having", "in": "query", "description": "Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": false, "type": "string" }, { "name": "time_rollup", "in": "query", "description": "The allowed values are specified by the time_rollups report meta property. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "time_window", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "start_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": false, "type": "string", "default": "yesterday" }, { "name": "order", "in": "query", "description": "Controls the sorting of the groups.\n\nThis should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed.\n\nThe first field has the most significance in sorting.", "required": false, "type": "string" }, { "name": "page_limit", "in": "query", "description": "Controls the maximum number of rows of data.\n\nThis parameter is required, if page_offset is one or greater.", "required": false, "type": "integer", "minimum": 1, "default": "unlimited" }, { "name": "page_offset", "in": "query", "description": "Controls how many pages to skip.", "required": false, "type": "integer", "minimum": 0 }, { "name": "precision", "in": "query", "description": "Controls how many digits to the right of the decimal places to display for float types.", "required": false, "type": "integer", "minimum": 0, "maximum": 8, "default": 8 }, { "name": "Accept-Encoding:", "in": "header", "description": "If the client supports the compression methods also supported by the server (currently `gzip` and `deflate`), the response data set (`text`\\/`csv`) will be returned in a compressed format. The metadata and error responses will not be compressed.\n\nIn order to receive the data in compressed format, the client must use the HTTP request header `Accept-Encoding`, and enumerate the preferred compression methods (see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). If the header `Accept-Encoding` is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format.\n\n ### request \n Accept-Encoding: gzip,deflate \n\n ### response \n Content-Encoding: gzip \n Content-Type: text/csv; charset=UTF-8 ", "type": "string", "enum": [ "gzip,deflate" ] }, { "name": "If-Modified-Since", "in": "header", "description": "If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body.\n\nIf the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header.", "type": "string", "format": "date-time" } ], "responses": { "200": { "description": "" }, "304": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } } } }, "/video/meta": { "get": { "operationId": "GET_video-meta", "summary": "Video Meta", "tags": [ "Reports" ], "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" } ], "responses": { "200": { "description": "", "schema": { "title": "Full Report Description", "allOf": [ { "title": "Brief Report Description", "type": "object", "properties": { "Name": { "type": "string", "description": "This is the human-readable name of the report. It is not recognized by any API input." }, "Version": { "type": "integer", "description": "This is the version of the report. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details." }, "Description": { "type": "string" }, "URI_Data": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:kbWhxp8szYZXNMBre endpoint." }, "URI_Meta": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:XLZxmeHNEAsLXfPht." }, "Transition": { "type": "object", "description": "Reports may change over time. This object will be present if the report will undergo a breaking change. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "replaced_by": { "type": "string", "format": "uri", "description": "The URL where the metadata for the next version of the report may be found." }, "transition_date": { "type": "string", "format": "date-time", "description": "After this GMT time the current version of the report will no longer be available." }, "next_version": { "type": "integer", "description": "The version replacing the current version of the report." } }, "required": [ "replaced_by", "transition_date", "next_version" ] }, "Deprecation": { "type": "object", "description": "Reports may be deprecated all together, or superseded by another report. This object will be present if the report is scheduled for deprecation. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "superseded_by": { "type": "string", "format": "uri", "description": "Optionally provides the metadata URI for the superseding report." }, "deprecation_date": { "type": "string", "format": "date-time", "description": "The GMT time when the report will no longer be available. When a report is past its `deprecation_date` it will no longer appear in the #endpoint:zMKJNurbLQddPfSfN. All endpoints having to do specifically with that report will return a 410 GONE response." } }, "required": [ "deprecation_date" ] } }, "required": [ "Name", "Version", "URI_Data", "URI_Meta" ] }, { "type": "object", "properties": { "Type": { "type": "string" }, "currency": { "type": "string", "description": "Provides information about the currency of the `metrics` fields typed as \"money\".\n\nWhen set to \"campaign currency\", the currency varies from record to record. To determine the currency for a particular record, the campaign_currency_code `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the currency for all records of the report." }, "data_retention": { "type": "string", "description": "Indicates how far back data is available. This can be a date, datetime, or time window as specified by the \"time_window\" and \"Special Time Windows\" sections of #docTextSection:GYrNjxjRCDjDrqcu7. This property should be used very loosely. It may not be accurate. It is meant to give a general idea." }, "default_metrics": { "type": "array", "description": "This is the list of metrics that will be returned if the `metrics` parameter is not specified in a call to the #endpoint:kbWhxp8szYZXNMBre endpoint.", "items": { "type": "string" } }, "structure": { "type": "object", "required": [ "time_field", "dimensions", "metrics" ], "properties": { "time_field": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "dimensions": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "metrics": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." } } }, "time_aggregation": { "type": "string", "description": "This property indicates the finest granularity of the `time_field`. For reports with a `time_field` of the `datetime` type, this will be \"by_hour\", \"by_day\", etc. When the type is `interval`, this will be \"various\"." }, "time_rollups": { "type": "array", "description": "This property indicates the available levels of granularity for the `time_field`. It lists the valid values of the `time_rollup` parameter used for the #endpoint:kbWhxp8szYZXNMBre endpoint. For reports with a `time_field` of the `datetime` type, this tends to be a combination of \"by_hour\", \"by_day\", \"by_week\", \"by_month\", \"all\", etc. When the type is `interval`, this will only include \"all\".", "items": { "type": "string" } }, "time_windows": { "type": "array", "description": "Lists the acceptable formats for the `time_window` parameter used by the #endpoint:kbWhxp8szYZXNMBre endpoint. Some values may be used as is, others may need to be modified. For details see the time_window section of #docTextSection:GYrNjxjRCDjDrqcu7.", "items": { "type": "string" } }, "timezone": { "type": "string", "description": "Provides information about the timezone of the `time_field` for the report.\n\nWhen set to \"campaign timezone\", the timezone varies from record to record. To determine the currency for a particular record, the campaign_timezone `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the timezone for all records of the report." } }, "required": [ "default_metrics", "structure", "time_rollups", "time_windows" ] } ] } } }, "description": "Get Video Meta" } }, "/watermark": { "get": { "operationId": "GET_watermark", "summary": "Watermark", "tags": [ "Reports" ], "description": "Watermark metrics show how many impressions and how much spend went towards the brain's learning activities. Viewable by campaign and strategy dimensions and available by day.", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" }, { "name": "dimensions", "in": "query", "description": "Selects the dimension fields to use in grouping rows.\n\nThis should be a comma-separated list of dimension field names.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": true, "type": "string" }, { "name": "metrics", "in": "query", "description": "Controls the selection of metric fields.\n\nThis should be a comma-separated list of metric field names.\n\nIf not specified, this will default to the metric fields specified by the `default_metrics` property of the #endpoint:XLZxmeHNEAsLXfPht.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": false, "type": "string" }, { "name": "filter", "in": "query", "description": "Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": true, "type": "string" }, { "name": "having", "in": "query", "description": "Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": false, "type": "string" }, { "name": "time_rollup", "in": "query", "description": "The allowed values are specified by the time_rollups report meta property. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "time_window", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "start_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": false, "type": "string", "default": "yesterday" }, { "name": "order", "in": "query", "description": "Controls the sorting of the groups.\n\nThis should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed.\n\nThe first field has the most significance in sorting.", "required": false, "type": "string" }, { "name": "page_limit", "in": "query", "description": "Controls the maximum number of rows of data.\n\nThis parameter is required, if page_offset is one or greater.", "required": false, "type": "integer", "minimum": 1, "default": "unlimited" }, { "name": "page_offset", "in": "query", "description": "Controls how many pages to skip.", "required": false, "type": "integer", "minimum": 0 }, { "name": "precision", "in": "query", "description": "Controls how many digits to the right of the decimal places to display for float types.", "required": false, "type": "integer", "minimum": 0, "maximum": 8, "default": 8 }, { "name": "Accept-Encoding:", "in": "header", "description": "If the client supports the compression methods also supported by the server (currently `gzip` and `deflate`), the response data set (`text`\\/`csv`) will be returned in a compressed format. The metadata and error responses will not be compressed.\n\nIn order to receive the data in compressed format, the client must use the HTTP request header `Accept-Encoding`, and enumerate the preferred compression methods (see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). If the header `Accept-Encoding` is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format.\n\n ### request \n Accept-Encoding: gzip,deflate \n\n ### response \n Content-Encoding: gzip \n Content-Type: text/csv; charset=UTF-8 ", "type": "string", "enum": [ "gzip,deflate" ] }, { "name": "If-Modified-Since", "in": "header", "description": "If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body.\n\nIf the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header.", "type": "string", "format": "date-time" } ], "responses": { "200": { "description": "" }, "304": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } } } }, "/watermark/meta": { "get": { "operationId": "GET_watermark-meta", "summary": "Watermark Meta", "tags": [ "Reports" ], "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" } ], "responses": { "200": { "description": "", "schema": { "title": "Full Report Description", "allOf": [ { "title": "Brief Report Description", "type": "object", "properties": { "Name": { "type": "string", "description": "This is the human-readable name of the report. It is not recognized by any API input." }, "Version": { "type": "integer", "description": "This is the version of the report. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details." }, "Description": { "type": "string" }, "URI_Data": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:kbWhxp8szYZXNMBre endpoint." }, "URI_Meta": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:XLZxmeHNEAsLXfPht." }, "Transition": { "type": "object", "description": "Reports may change over time. This object will be present if the report will undergo a breaking change. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "replaced_by": { "type": "string", "format": "uri", "description": "The URL where the metadata for the next version of the report may be found." }, "transition_date": { "type": "string", "format": "date-time", "description": "After this GMT time the current version of the report will no longer be available." }, "next_version": { "type": "integer", "description": "The version replacing the current version of the report." } }, "required": [ "replaced_by", "transition_date", "next_version" ] }, "Deprecation": { "type": "object", "description": "Reports may be deprecated all together, or superseded by another report. This object will be present if the report is scheduled for deprecation. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "superseded_by": { "type": "string", "format": "uri", "description": "Optionally provides the metadata URI for the superseding report." }, "deprecation_date": { "type": "string", "format": "date-time", "description": "The GMT time when the report will no longer be available. When a report is past its `deprecation_date` it will no longer appear in the #endpoint:zMKJNurbLQddPfSfN. All endpoints having to do specifically with that report will return a 410 GONE response." } }, "required": [ "deprecation_date" ] } }, "required": [ "Name", "Version", "URI_Data", "URI_Meta" ] }, { "type": "object", "properties": { "Type": { "type": "string" }, "currency": { "type": "string", "description": "Provides information about the currency of the `metrics` fields typed as \"money\".\n\nWhen set to \"campaign currency\", the currency varies from record to record. To determine the currency for a particular record, the campaign_currency_code `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the currency for all records of the report." }, "data_retention": { "type": "string", "description": "Indicates how far back data is available. This can be a date, datetime, or time window as specified by the \"time_window\" and \"Special Time Windows\" sections of #docTextSection:GYrNjxjRCDjDrqcu7. This property should be used very loosely. It may not be accurate. It is meant to give a general idea." }, "default_metrics": { "type": "array", "description": "This is the list of metrics that will be returned if the `metrics` parameter is not specified in a call to the #endpoint:kbWhxp8szYZXNMBre endpoint.", "items": { "type": "string" } }, "structure": { "type": "object", "required": [ "time_field", "dimensions", "metrics" ], "properties": { "time_field": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "dimensions": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "metrics": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." } } }, "time_aggregation": { "type": "string", "description": "This property indicates the finest granularity of the `time_field`. For reports with a `time_field` of the `datetime` type, this will be \"by_hour\", \"by_day\", etc. When the type is `interval`, this will be \"various\"." }, "time_rollups": { "type": "array", "description": "This property indicates the available levels of granularity for the `time_field`. It lists the valid values of the `time_rollup` parameter used for the #endpoint:kbWhxp8szYZXNMBre endpoint. For reports with a `time_field` of the `datetime` type, this tends to be a combination of \"by_hour\", \"by_day\", \"by_week\", \"by_month\", \"all\", etc. When the type is `interval`, this will only include \"all\".", "items": { "type": "string" } }, "time_windows": { "type": "array", "description": "Lists the acceptable formats for the `time_window` parameter used by the #endpoint:kbWhxp8szYZXNMBre endpoint. Some values may be used as is, others may need to be modified. For details see the time_window section of #docTextSection:GYrNjxjRCDjDrqcu7.", "items": { "type": "string" } }, "timezone": { "type": "string", "description": "Provides information about the timezone of the `time_field` for the report.\n\nWhen set to \"campaign timezone\", the timezone varies from record to record. To determine the currency for a particular record, the campaign_timezone `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the timezone for all records of the report." } }, "required": [ "default_metrics", "structure", "time_rollups", "time_windows" ] } ] } } }, "description": "Get Watermark Meta" } }, "/win_loss": { "get": { "operationId": "GET_win_loss", "summary": "Win Loss", "tags": [ "Reports" ], "description": "Metrics describe the auction before a win or even a bid has taken place. Broken out by strategy, exchange, and deal dimensions and available by hour.", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" }, { "name": "dimensions", "in": "query", "description": "Selects the dimension fields to use in grouping rows.\n\nThis should be a comma-separated list of dimension field names.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": true, "type": "string" }, { "name": "metrics", "in": "query", "description": "Controls the selection of metric fields.\n\nThis should be a comma-separated list of metric field names.\n\nIf not specified, this will default to the metric fields specified by the `default_metrics` property of the #endpoint:XLZxmeHNEAsLXfPht.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": false, "type": "string" }, { "name": "filter", "in": "query", "description": "Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": true, "type": "string" }, { "name": "having", "in": "query", "description": "Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": false, "type": "string" }, { "name": "time_rollup", "in": "query", "description": "The allowed values are specified by the time_rollups report meta property. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "time_window", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "start_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": false, "type": "string", "default": "yesterday" }, { "name": "order", "in": "query", "description": "Controls the sorting of the groups.\n\nThis should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed.\n\nThe first field has the most significance in sorting.", "required": false, "type": "string" }, { "name": "page_limit", "in": "query", "description": "Controls the maximum number of rows of data.\n\nThis parameter is required, if page_offset is one or greater.", "required": false, "type": "integer", "minimum": 1, "default": "unlimited" }, { "name": "page_offset", "in": "query", "description": "Controls how many pages to skip.", "required": false, "type": "integer", "minimum": 0 }, { "name": "precision", "in": "query", "description": "Controls how many digits to the right of the decimal places to display for float types.", "required": false, "type": "integer", "minimum": 0, "maximum": 8, "default": 8 }, { "name": "Accept-Encoding:", "in": "header", "description": "If the client supports the compression methods also supported by the server (currently `gzip` and `deflate`), the response data set (`text`\\/`csv`) will be returned in a compressed format. The metadata and error responses will not be compressed.\n\nIn order to receive the data in compressed format, the client must use the HTTP request header `Accept-Encoding`, and enumerate the preferred compression methods (see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). If the header `Accept-Encoding` is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format.\n\n ### request \n Accept-Encoding: gzip,deflate \n\n ### response \n Content-Encoding: gzip \n Content-Type: text/csv; charset=UTF-8 ", "type": "string", "enum": [ "gzip,deflate" ] }, { "name": "If-Modified-Since", "in": "header", "description": "If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body.\n\nIf the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header.", "type": "string", "format": "date-time" } ], "responses": { "200": { "description": "" }, "304": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } } } }, "/win_loss/meta": { "get": { "operationId": "GET_win_loss-meta", "summary": "Win Loss Meta", "tags": [ "Reports" ], "description": "Metrics describe the auction before a win or even a bid has taken place. Broken out by strategy, exchange, and deal dimensions and available by hour.", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" } ], "responses": { "200": { "description": "", "schema": { "title": "Full Report Description", "allOf": [ { "title": "Brief Report Description", "type": "object", "properties": { "Name": { "type": "string", "description": "This is the human-readable name of the report. It is not recognized by any API input." }, "Version": { "type": "integer", "description": "This is the version of the report. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details." }, "Description": { "type": "string" }, "URI_Data": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:kbWhxp8szYZXNMBre endpoint." }, "URI_Meta": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:XLZxmeHNEAsLXfPht." }, "Transition": { "type": "object", "description": "Reports may change over time. This object will be present if the report will undergo a breaking change. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "replaced_by": { "type": "string", "format": "uri", "description": "The URL where the metadata for the next version of the report may be found." }, "transition_date": { "type": "string", "format": "date-time", "description": "After this GMT time the current version of the report will no longer be available." }, "next_version": { "type": "integer", "description": "The version replacing the current version of the report." } }, "required": [ "replaced_by", "transition_date", "next_version" ] }, "Deprecation": { "type": "object", "description": "Reports may be deprecated all together, or superseded by another report. This object will be present if the report is scheduled for deprecation. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "superseded_by": { "type": "string", "format": "uri", "description": "Optionally provides the metadata URI for the superseding report." }, "deprecation_date": { "type": "string", "format": "date-time", "description": "The GMT time when the report will no longer be available. When a report is past its `deprecation_date` it will no longer appear in the #endpoint:zMKJNurbLQddPfSfN. All endpoints having to do specifically with that report will return a 410 GONE response." } }, "required": [ "deprecation_date" ] } }, "required": [ "Name", "Version", "URI_Data", "URI_Meta" ] }, { "type": "object", "properties": { "Type": { "type": "string" }, "currency": { "type": "string", "description": "Provides information about the currency of the `metrics` fields typed as \"money\".\n\nWhen set to \"campaign currency\", the currency varies from record to record. To determine the currency for a particular record, the campaign_currency_code `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the currency for all records of the report." }, "data_retention": { "type": "string", "description": "Indicates how far back data is available. This can be a date, datetime, or time window as specified by the \"time_window\" and \"Special Time Windows\" sections of #docTextSection:GYrNjxjRCDjDrqcu7. This property should be used very loosely. It may not be accurate. It is meant to give a general idea." }, "default_metrics": { "type": "array", "description": "This is the list of metrics that will be returned if the `metrics` parameter is not specified in a call to the #endpoint:kbWhxp8szYZXNMBre endpoint.", "items": { "type": "string" } }, "structure": { "type": "object", "required": [ "time_field", "dimensions", "metrics" ], "properties": { "time_field": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "dimensions": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "metrics": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." } } }, "time_aggregation": { "type": "string", "description": "This property indicates the finest granularity of the `time_field`. For reports with a `time_field` of the `datetime` type, this will be \"by_hour\", \"by_day\", etc. When the type is `interval`, this will be \"various\"." }, "time_rollups": { "type": "array", "description": "This property indicates the available levels of granularity for the `time_field`. It lists the valid values of the `time_rollup` parameter used for the #endpoint:kbWhxp8szYZXNMBre endpoint. For reports with a `time_field` of the `datetime` type, this tends to be a combination of \"by_hour\", \"by_day\", \"by_week\", \"by_month\", \"all\", etc. When the type is `interval`, this will only include \"all\".", "items": { "type": "string" } }, "time_windows": { "type": "array", "description": "Lists the acceptable formats for the `time_window` parameter used by the #endpoint:kbWhxp8szYZXNMBre endpoint. Some values may be used as is, others may need to be modified. For details see the time_window section of #docTextSection:GYrNjxjRCDjDrqcu7.", "items": { "type": "string" } }, "timezone": { "type": "string", "description": "Provides information about the timezone of the `time_field` for the report.\n\nWhen set to \"campaign timezone\", the timezone varies from record to record. To determine the currency for a particular record, the campaign_timezone `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the timezone for all records of the report." } }, "required": [ "default_metrics", "structure", "time_rollups", "time_windows" ] } ] } } } } }, "/win_loss_creative": { "get": { "operationId": "GET_win_loss_creative", "summary": "Win/Loss by Creative", "tags": [ "Reports" ], "description": "Metrics describe the auction before a win has taken place. Broken out by creative dimensions and available by hour.", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" }, { "name": "dimensions", "in": "query", "description": "Selects the dimension fields to use in grouping rows.\n\nThis should be a comma-separated list of dimension field names.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": true, "type": "string" }, { "name": "metrics", "in": "query", "description": "Controls the selection of metric fields.\n\nThis should be a comma-separated list of metric field names.\n\nIf not specified, this will default to the metric fields specified by the `default_metrics` property of the #endpoint:XLZxmeHNEAsLXfPht.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": false, "type": "string" }, { "name": "filter", "in": "query", "description": "Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": true, "type": "string" }, { "name": "having", "in": "query", "description": "Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": false, "type": "string" }, { "name": "time_rollup", "in": "query", "description": "The allowed values are specified by the time_rollups report meta property. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "time_window", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "start_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": false, "type": "string", "default": "yesterday" }, { "name": "order", "in": "query", "description": "Controls the sorting of the groups.\n\nThis should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed.\n\nThe first field has the most significance in sorting.", "required": false, "type": "string" }, { "name": "page_limit", "in": "query", "description": "Controls the maximum number of rows of data.\n\nThis parameter is required, if page_offset is one or greater.", "required": false, "type": "integer", "minimum": 1, "default": "unlimited" }, { "name": "page_offset", "in": "query", "description": "Controls how many pages to skip.", "required": false, "type": "integer", "minimum": 0 }, { "name": "precision", "in": "query", "description": "Controls how many digits to the right of the decimal places to display for float types.", "required": false, "type": "integer", "minimum": 0, "maximum": 8, "default": 8 }, { "name": "Accept-Encoding:", "in": "header", "description": "If the client supports the compression methods also supported by the server (currently `gzip` and `deflate`), the response data set (`text`\\/`csv`) will be returned in a compressed format. The metadata and error responses will not be compressed.\n\nIn order to receive the data in compressed format, the client must use the HTTP request header `Accept-Encoding`, and enumerate the preferred compression methods (see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). If the header `Accept-Encoding` is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format.\n\n ### request \n Accept-Encoding: gzip,deflate \n\n ### response \n Content-Encoding: gzip \n Content-Type: text/csv; charset=UTF-8 ", "type": "string", "enum": [ "gzip,deflate" ] }, { "name": "If-Modified-Since", "in": "header", "description": "If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body.\n\nIf the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header.", "type": "string", "format": "date-time" } ], "responses": { "200": { "description": "" }, "304": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } } } }, "/win_loss_creative/meta": { "get": { "operationId": "GET_win_loss_creative-meta", "summary": "Win/Loss by Creative Meta", "tags": [ "Reports" ], "description": "Metrics describe the auction before a win has taken place. Broken out by creative dimensions and available by hour.", "parameters": [ { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" } ], "responses": { "200": { "description": "", "schema": { "title": "Full Report Description", "allOf": [ { "title": "Brief Report Description", "type": "object", "properties": { "Name": { "type": "string", "description": "This is the human-readable name of the report. It is not recognized by any API input." }, "Version": { "type": "integer", "description": "This is the version of the report. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details." }, "Description": { "type": "string" }, "URI_Data": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:kbWhxp8szYZXNMBre endpoint." }, "URI_Meta": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:XLZxmeHNEAsLXfPht." }, "Transition": { "type": "object", "description": "Reports may change over time. This object will be present if the report will undergo a breaking change. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "replaced_by": { "type": "string", "format": "uri", "description": "The URL where the metadata for the next version of the report may be found." }, "transition_date": { "type": "string", "format": "date-time", "description": "After this GMT time the current version of the report will no longer be available." }, "next_version": { "type": "integer", "description": "The version replacing the current version of the report." } }, "required": [ "replaced_by", "transition_date", "next_version" ] }, "Deprecation": { "type": "object", "description": "Reports may be deprecated all together, or superseded by another report. This object will be present if the report is scheduled for deprecation. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "superseded_by": { "type": "string", "format": "uri", "description": "Optionally provides the metadata URI for the superseding report." }, "deprecation_date": { "type": "string", "format": "date-time", "description": "The GMT time when the report will no longer be available. When a report is past its `deprecation_date` it will no longer appear in the #endpoint:zMKJNurbLQddPfSfN. All endpoints having to do specifically with that report will return a 410 GONE response." } }, "required": [ "deprecation_date" ] } }, "required": [ "Name", "Version", "URI_Data", "URI_Meta" ] }, { "type": "object", "properties": { "Type": { "type": "string" }, "currency": { "type": "string", "description": "Provides information about the currency of the `metrics` fields typed as \"money\".\n\nWhen set to \"campaign currency\", the currency varies from record to record. To determine the currency for a particular record, the campaign_currency_code `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the currency for all records of the report." }, "data_retention": { "type": "string", "description": "Indicates how far back data is available. This can be a date, datetime, or time window as specified by the \"time_window\" and \"Special Time Windows\" sections of #docTextSection:GYrNjxjRCDjDrqcu7. This property should be used very loosely. It may not be accurate. It is meant to give a general idea." }, "default_metrics": { "type": "array", "description": "This is the list of metrics that will be returned if the `metrics` parameter is not specified in a call to the #endpoint:kbWhxp8szYZXNMBre endpoint.", "items": { "type": "string" } }, "structure": { "type": "object", "required": [ "time_field", "dimensions", "metrics" ], "properties": { "time_field": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "dimensions": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "metrics": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." } } }, "time_aggregation": { "type": "string", "description": "This property indicates the finest granularity of the `time_field`. For reports with a `time_field` of the `datetime` type, this will be \"by_hour\", \"by_day\", etc. When the type is `interval`, this will be \"various\"." }, "time_rollups": { "type": "array", "description": "This property indicates the available levels of granularity for the `time_field`. It lists the valid values of the `time_rollup` parameter used for the #endpoint:kbWhxp8szYZXNMBre endpoint. For reports with a `time_field` of the `datetime` type, this tends to be a combination of \"by_hour\", \"by_day\", \"by_week\", \"by_month\", \"all\", etc. When the type is `interval`, this will only include \"all\".", "items": { "type": "string" } }, "time_windows": { "type": "array", "description": "Lists the acceptable formats for the `time_window` parameter used by the #endpoint:kbWhxp8szYZXNMBre endpoint. Some values may be used as is, others may need to be modified. For details see the time_window section of #docTextSection:GYrNjxjRCDjDrqcu7.", "items": { "type": "string" } }, "timezone": { "type": "string", "description": "Provides information about the timezone of the `time_field` for the report.\n\nWhen set to \"campaign timezone\", the timezone varies from record to record. To determine the currency for a particular record, the campaign_timezone `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the timezone for all records of the report." } }, "required": [ "default_metrics", "structure", "time_rollups", "time_windows" ] } ] } } } } } }, "parameters": { "trait:cookieAuth:Cookie": { "name": "Cookie", "in": "header", "required": true, "type": "string", "default": "adama_session=<>" }, "trait:jsonResponse:Accept": { "name": "Accept", "in": "header", "required": false, "type": "string", "default": "application/vnd.mediamath.v1+json" }, "trait:limit:page_limit": { "name": "page_limit", "in": "query", "required": false, "type": "integer", "minimum": 1, "maximum": 100 }, "trait:limit:page_offset": { "name": "page_offset", "in": "query", "description": "Index of the first element in the collection to retrieve", "required": false, "type": "integer" }, "trait:oAuth2Jwt:Authorization": { "name": "Authorization", "in": "header", "description": "The OAuth2 token. See https://mediamath-auth.api-docs.io/v2/oauth2/oauth2-api-access for more information.", "required": true, "type": "string", "pattern": "Bearer .*" }, "trait:querying:q": { "name": "q", "in": "query", "required": false, "type": "string", "items": { "type": "string" } }, "trait:returnAdditionalEntityProperties:full": { "name": "full", "in": "query", "description": "To include all properties for all entities returned by the API call, use `full=*:`", "required": false, "type": "string", "default": "", "items": { "type": "string" } }, "trait:returnAdditionalEntityProperties:with": { "name": "with", "in": "query", "required": false, "type": "string", "items": { "type": "string" } }, "trait:sorting:sort_by": { "name": "sort_by", "in": "query", "description": "name", "required": false, "type": "string", "items": { "type": "string" } }, "trait:requestsCustomTimeWindow:dimensions": { "name": "dimensions", "in": "query", "description": "Selects the dimension fields to use in grouping rows.\n\nThis should be a comma-separated list of dimension field names.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": true, "type": "string" }, "trait:requestsCustomTimeWindow:metrics": { "name": "metrics", "in": "query", "description": "Controls the selection of metric fields.\n\nThis should be a comma-separated list of metric field names.\n\nIf not specified, this will default to the metric fields specified by the `default_metrics` property of the #endpoint:XLZxmeHNEAsLXfPht.\n\nThe position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output.", "required": false, "type": "string" }, "trait:requestsCustomTimeWindow:filter": { "name": "filter", "in": "query", "description": "Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": true, "type": "string" }, "trait:requestsCustomTimeWindow:having": { "name": "having", "in": "query", "description": "Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of #endpoint:kbWhxp8szYZXNMBre for more information about interpretation and accepted formats.", "required": false, "type": "string" }, "trait:requestsCustomTimeWindow:time_rollup": { "name": "time_rollup", "in": "query", "description": "The allowed values are specified by the time_rollups report meta property. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, "trait:requestsCustomTimeWindow:time_window": { "name": "time_window", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, "trait:requestsCustomTimeWindow:start_date": { "name": "start_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": true, "type": "string" }, "trait:requestsCustomTimeWindow:end_date": { "name": "end_date", "in": "query", "description": "Controls filtering against the time field for the report. See the Time Field section of #endpoint:XLZxmeHNEAsLXfPht for more information.", "required": false, "type": "string", "default": "yesterday" }, "trait:requestsCustomTimeWindow:order": { "name": "order", "in": "query", "description": "Controls the sorting of the groups.\n\nThis should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed.\n\nThe first field has the most significance in sorting.", "required": false, "type": "string" }, "trait:requestsCustomTimeWindow:page_limit": { "name": "page_limit", "in": "query", "description": "Controls the maximum number of rows of data.\n\nThis parameter is required, if page_offset is one or greater.", "required": false, "type": "integer", "minimum": 1, "default": "unlimited" }, "trait:requestsCustomTimeWindow:page_offset": { "name": "page_offset", "in": "query", "description": "Controls how many pages to skip.", "required": false, "type": "integer", "minimum": 0 }, "trait:requestsCustomTimeWindow:precision": { "name": "precision", "in": "query", "description": "Controls how many digits to the right of the decimal places to display for float types.", "required": false, "type": "integer", "minimum": 0, "maximum": 8, "default": 8 }, "trait:requestsCustomTimeWindow:Accept-Encoding:": { "name": "Accept-Encoding:", "in": "header", "description": "If the client supports the compression methods also supported by the server (currently `gzip` and `deflate`), the response data set (`text`\\/`csv`) will be returned in a compressed format. The metadata and error responses will not be compressed.\n\nIn order to receive the data in compressed format, the client must use the HTTP request header `Accept-Encoding`, and enumerate the preferred compression methods (see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). If the header `Accept-Encoding` is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format.\n\n ### request \n Accept-Encoding: gzip,deflate \n\n ### response \n Content-Encoding: gzip \n Content-Type: text/csv; charset=UTF-8 ", "type": "string", "enum": [ "gzip,deflate" ] }, "trait:requestsCustomTimeWindow:If-Modified-Since": { "name": "If-Modified-Since", "in": "header", "description": "If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body.\n\nIf the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header.", "type": "string", "format": "date-time" } }, "responses": { "trait:notFoundAble:404": { "description": "", "schema": { "title": "Error Response", "type": "object", "properties": { "errors": { "title": "Errors", "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" } }, "required": [ "code", "message" ] } }, "meta": { "type": "object" } } } }, "trait:requestsCustomTimeWindow:200": { "description": "" }, "trait:requestsCustomTimeWindow:304": { "description": "" }, "trait:requestsCustomTimeWindow:400": { "description": "" }, "trait:requestsCustomTimeWindow:401": { "description": "" }, "trait:requestsCustomTimeWindow:403": { "description": "" }, "trait:requestsCustomTimeWindow:404": { "description": "" } }, "definitions": { "error-response": { "title": "Error Response", "type": "object", "properties": { "errors": { "title": "Errors", "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" } }, "required": [ "code", "message" ] } }, "meta": { "type": "object" } } }, "errors": { "title": "Errors", "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" } }, "required": [ "code", "message" ] } }, "t1-meta": { "title": "meta", "description": "Meta response for all API endpoints", "type": "object", "properties": { "etag": { "type": "string" }, "count": { "type": "integer" }, "called_on": { "type": "string" }, "status": { "type": "string" }, "offset": { "type": [ "integer", "string" ] }, "total_count": { "type": "integer" } } }, "brief-report-description": { "title": "Brief Report Description", "type": "object", "properties": { "Name": { "type": "string", "description": "This is the human-readable name of the report. It is not recognized by any API input." }, "Version": { "type": "integer", "description": "This is the version of the report. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details." }, "Description": { "type": "string" }, "URI_Data": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:kbWhxp8szYZXNMBre endpoint." }, "URI_Meta": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:XLZxmeHNEAsLXfPht." }, "Transition": { "type": "object", "description": "Reports may change over time. This object will be present if the report will undergo a breaking change. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "replaced_by": { "type": "string", "format": "uri", "description": "The URL where the metadata for the next version of the report may be found." }, "transition_date": { "type": "string", "format": "date-time", "description": "After this GMT time the current version of the report will no longer be available." }, "next_version": { "type": "integer", "description": "The version replacing the current version of the report." } }, "required": [ "replaced_by", "transition_date", "next_version" ] }, "Deprecation": { "type": "object", "description": "Reports may be deprecated all together, or superseded by another report. This object will be present if the report is scheduled for deprecation. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "superseded_by": { "type": "string", "format": "uri", "description": "Optionally provides the metadata URI for the superseding report." }, "deprecation_date": { "type": "string", "format": "date-time", "description": "The GMT time when the report will no longer be available. When a report is past its `deprecation_date` it will no longer appear in the #endpoint:zMKJNurbLQddPfSfN. All endpoints having to do specifically with that report will return a 410 GONE response." } }, "required": [ "deprecation_date" ] } }, "required": [ "Name", "Version", "URI_Data", "URI_Meta" ] }, "full-report-description": { "title": "Full Report Description", "allOf": [ { "title": "Brief Report Description", "type": "object", "properties": { "Name": { "type": "string", "description": "This is the human-readable name of the report. It is not recognized by any API input." }, "Version": { "type": "integer", "description": "This is the version of the report. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details." }, "Description": { "type": "string" }, "URI_Data": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:kbWhxp8szYZXNMBre endpoint." }, "URI_Meta": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:XLZxmeHNEAsLXfPht." }, "Transition": { "type": "object", "description": "Reports may change over time. This object will be present if the report will undergo a breaking change. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "replaced_by": { "type": "string", "format": "uri", "description": "The URL where the metadata for the next version of the report may be found." }, "transition_date": { "type": "string", "format": "date-time", "description": "After this GMT time the current version of the report will no longer be available." }, "next_version": { "type": "integer", "description": "The version replacing the current version of the report." } }, "required": [ "replaced_by", "transition_date", "next_version" ] }, "Deprecation": { "type": "object", "description": "Reports may be deprecated all together, or superseded by another report. This object will be present if the report is scheduled for deprecation. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "superseded_by": { "type": "string", "format": "uri", "description": "Optionally provides the metadata URI for the superseding report." }, "deprecation_date": { "type": "string", "format": "date-time", "description": "The GMT time when the report will no longer be available. When a report is past its `deprecation_date` it will no longer appear in the #endpoint:zMKJNurbLQddPfSfN. All endpoints having to do specifically with that report will return a 410 GONE response." } }, "required": [ "deprecation_date" ] } }, "required": [ "Name", "Version", "URI_Data", "URI_Meta" ] }, { "type": "object", "properties": { "Type": { "type": "string" }, "currency": { "type": "string", "description": "Provides information about the currency of the `metrics` fields typed as \"money\".\n\nWhen set to \"campaign currency\", the currency varies from record to record. To determine the currency for a particular record, the campaign_currency_code `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the currency for all records of the report." }, "data_retention": { "type": "string", "description": "Indicates how far back data is available. This can be a date, datetime, or time window as specified by the \"time_window\" and \"Special Time Windows\" sections of #docTextSection:GYrNjxjRCDjDrqcu7. This property should be used very loosely. It may not be accurate. It is meant to give a general idea." }, "default_metrics": { "type": "array", "description": "This is the list of metrics that will be returned if the `metrics` parameter is not specified in a call to the #endpoint:kbWhxp8szYZXNMBre endpoint.", "items": { "type": "string" } }, "structure": { "type": "object", "required": [ "time_field", "dimensions", "metrics" ], "properties": { "time_field": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "dimensions": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." }, "metrics": { "type": "object", "additionalProperties": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "description": "Mapping of field names to #model:Fqbi8siNTuFGqA2W5." } } }, "time_aggregation": { "type": "string", "description": "This property indicates the finest granularity of the `time_field`. For reports with a `time_field` of the `datetime` type, this will be \"by_hour\", \"by_day\", etc. When the type is `interval`, this will be \"various\"." }, "time_rollups": { "type": "array", "description": "This property indicates the available levels of granularity for the `time_field`. It lists the valid values of the `time_rollup` parameter used for the #endpoint:kbWhxp8szYZXNMBre endpoint. For reports with a `time_field` of the `datetime` type, this tends to be a combination of \"by_hour\", \"by_day\", \"by_week\", \"by_month\", \"all\", etc. When the type is `interval`, this will only include \"all\".", "items": { "type": "string" } }, "time_windows": { "type": "array", "description": "Lists the acceptable formats for the `time_window` parameter used by the #endpoint:kbWhxp8szYZXNMBre endpoint. Some values may be used as is, others may need to be modified. For details see the time_window section of #docTextSection:GYrNjxjRCDjDrqcu7.", "items": { "type": "string" } }, "timezone": { "type": "string", "description": "Provides information about the timezone of the `time_field` for the report.\n\nWhen set to \"campaign timezone\", the timezone varies from record to record. To determine the currency for a particular record, the campaign_timezone `dimensions` field should be requested, if available for the report.\n\nAny other value should be taken to be the timezone for all records of the report." } }, "required": [ "default_metrics", "structure", "time_rollups", "time_windows" ] } ] }, "field-description": { "title": "Field Description", "type": "object", "properties": { "name": { "type": "string", "description": "This is the human-readable name of the field." }, "type": { "type": "string", "enum": [ "float", "money", "percent", "ratio", "integer", "count", "rank", "datetime", "string", "interval", "id", "bool", "boolean" ] }, "access": { "type": "boolean", "description": "This property is applicable to dimension fields only. Every request must have at least one filter or having predicate against a field with this property set." }, "description": { "type": "string" }, "maxLength": { "type": "number", "description": "This property describes the allowable length for string-typed fields." }, "values": { "type": "array", "description": "Enumerates the possible values that this field may represent. When using an equality predicate, all predicate values must match one of the enumerated entries.", "items": { "type": "string" } } }, "required": [ "name", "type" ] }, "reports-list": { "title": "Reports List", "type": "object", "properties": { "reports": { "type": "object", "additionalProperties": { "title": "Brief Report Description", "type": "object", "properties": { "Name": { "type": "string", "description": "This is the human-readable name of the report. It is not recognized by any API input." }, "Version": { "type": "integer", "description": "This is the version of the report. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details." }, "Description": { "type": "string" }, "URI_Data": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:kbWhxp8szYZXNMBre endpoint." }, "URI_Meta": { "type": "string", "format": "uri", "description": "This is the URI for the report's #endpoint:XLZxmeHNEAsLXfPht." }, "Transition": { "type": "object", "description": "Reports may change over time. This object will be present if the report will undergo a breaking change. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "replaced_by": { "type": "string", "format": "uri", "description": "The URL where the metadata for the next version of the report may be found." }, "transition_date": { "type": "string", "format": "date-time", "description": "After this GMT time the current version of the report will no longer be available." }, "next_version": { "type": "integer", "description": "The version replacing the current version of the report." } }, "required": [ "replaced_by", "transition_date", "next_version" ] }, "Deprecation": { "type": "object", "description": "Reports may be deprecated all together, or superseded by another report. This object will be present if the report is scheduled for deprecation. See the #docTextSection:T5kP5zT4RzQQu9HWn section for more details.", "properties": { "superseded_by": { "type": "string", "format": "uri", "description": "Optionally provides the metadata URI for the superseding report." }, "deprecation_date": { "type": "string", "format": "date-time", "description": "The GMT time when the report will no longer be available. When a report is past its `deprecation_date` it will no longer appear in the #endpoint:zMKJNurbLQddPfSfN. All endpoints having to do specifically with that report will return a 410 GONE response." } }, "required": [ "deprecation_date" ] } }, "required": [ "Name", "Version", "URI_Data", "URI_Meta" ] }, "description": "This is a mapping of report names to #model:DXB2r3wXGZsaAdrcB." } } } }, "securityDefinitions": { "Cookie Auth": { "type": "apiKey", "name": "adama_session", "in": "header", "description": "While most APIs at mediamath utilize the Auth token flow, the reporting API requires a session ID token from https://api.mediamath.com/api/v2.0/session.\n" } }, "x-stoplight": { "docs": { "includeDownloadLink": true } } }