Payload Specifications

reportOption

Type JSON
Required YES
Description Parameters for report generation, described below.

dimesionTypeIds

Type array of integer
Required NO
Description Identify the types of Dimensions of the report. See Report Dimensions for detail. If omitted, the report will be time-dimension only.

metricTypeIds

Type array of integer
Required YES
Description Identify the measurements of the report. See Report Metrics for details.

accountIds

Type array of integer
Required NO
Description The report’s Advertiser Account IDs.

filterOptions

Type array of JSON object
Required NO
Description The filters on the dimensions.

filterOptions example

{
  "reportOption": {
    "timezone": "Asia/Shanghai",
    "currency": 3,
    "dimensionTypeIds": [ 1, 3, 4, 5, 6, 64 ],
    "filterOptions": [
      {
        "dimensionTypeId": 64,
        "isExcluded": false,
        "includeValues": [ {"id": 7} ]
      }
    ],
    "metricTypeIds": [ 1, 2, 23, 44, 46 ]
  },
  "intervalTypeId": 1,
  "dateTypeId": 11,
  "startDate": "2016-11-06T00:00:00",
  "endDate": "2016-11-06T23:59:59"
}

The report will be filtered to only contain data for Advertiser Groups (Dimension Id: 64) with Id of 7.

Note

A filter for Advertiser (Dimension Id: 4) will work, however it is recommended that the accountIds payload field be used instead.

having

Type array of JSON object
Required NO
Description The filters on the metrics.

having example

{
  "reportOption": {
    "timezone": "America/Los_Angeles",
    "currency": 4,
    "dimensionTypeIds": [ 5 ],
    "filterOptions": [
      {
        "includeValues": [
          {
            "name": "France",
            "id": "250"
          }
        ],
       "isExcluded": "false",
        "dimensionTypeId": 19
      }
    ],
    "metricTypeIds": [ 1, 2, 23 ],
    "having": {
      "type": "and",
      "havingSpecs": [
        {
          "type": "greaterThan",
          "metricTypeId": 1,
          "value": 1
        }
      ]
    }
  },
  "intervalTypeId": 2,
  "dateTypeId": 11,
  "startDate": "2016-11-01T00:00:00",
  "endDate": "2016-11-01T23:59:59"
}

timezone

Type String
Required NO
Description The time zone used for generating the reporting data. If it is not supplied, America/New_York is used as the default.
Value Offset
America/Los_Angeles UTC-8
America/Denver UTC-7
America/Chicago UTC-6
America/El_Salvador UTC-6
America/Mexico_City UTC-6
America/New_York UTC-5
America/Bogota UTC-5
America/Lima UTC-5
America/Halifax UTC-4
America/Puerto_Rico UTC-4
America/Argentina/Buenos_Aires UTC-3
America/Santiago UTC-3
America/Sao_Paulo UTC-2
Etc/GMT UTC+0
Europe/London UTC+0
Europe/Paris UTC+1
Asia/Jerusalem UTC+2
Asia/Debai UTC+4
Asia/Karachi UTC+5
Asia/Dhaka UTC+6
Asia/Jakarta UTC+7
Australia/Perth UTC+8
Asia/Shanghai UTC+8
Asia/Tokyo UTC+9
Australia/Sydney UTC+11
Pacific/Auckland UTC+13

currency

Type integer
Required NO
Description To identify the report’s currency type.
  1 Seat
  2 Advertiser
  3 Campaign
  4 USD (default)

limitSpec

Type JSON object
Required NO
Description To limit the number of rows in the report. The resultant report is top-n in metrics in descending or ascending order.

limitSpec example

{
  "reportOption": {
    "timezone": "America/Los_Angeles",
    "currency": 4,
    "dimensionTypeIds": [ 5 ],
    "filterOptions": [
      {
        "includeValues": [
          {
            "name": "France",
            "id": "250"
          }
        ],
       "isExcluded": "false",
        "dimensionTypeId": 19
      }
    ],
    "metricTypeIds": [ 1, 2, 23 ],
    "limitSpec": {
      "columns": [
        {
          "direction": "DESCENDING",
          "metricTypeId": 2
        }
      ],
      "limit": 10000,
      "type": "default"
    }
  },
  "intervalTypeId": 2,
  "dateTypeId": 11,
  "startDate": "2016-11-01T00:00:00",
  "endDate": "2016-11-01T23:59:59"
}

dateTypeId

Type integer
Required YES
Description To identify the type of date range (interval) in the report.
Value Date Type
1 Today
2 Yesterday
3 This Week
4 Last 7 Days
5 Last Week
6 Last 14 Days
7 Month to Date
8 Last 30 Days
9 Last Month
10 All Time
11 Custom Range

Note

The All Time setting would generate an extremely large report. Use it with a filter, and/or cumulative interval type.

intervalTypeId

Type integer
Required YES
Description To identify the type of time granularity of the report.
Value Interval Type
1 Cumulative
  One row, where each column in the row shows data for the entire range.
  For example, for a two-week date range, a Cumulative report shows two weeks worth of impressions, clicks, and conversions in a single row.
2 Day
  The number of rows depends on the date range, and one row represents one calendar day. Each row in a Day report shows the data for a specific date.
  For example, for a two-week date range, each of the 14 rows shows one day’s worth of impressions, clicks, and conversions.
3 Month
  The number of rows depends on the date range, and one row represents one full or partial calendar month.
4 Week
  The number of rows depends on the date range, and one row represents one calendar week.
  For example, for a two-week date range, each row in a Week report shows the impressions, clicks, and conversions for a specific week.
5 Hour
  There will be one row for each individual hour that has data. Each row represents a single pair of date and hour. For example, if the date range of the report is two full days, and we group by Hour, there will be 48 rows.

startDate

Type string
Required ONLY if dateTypeId is 11
Description Start time of date range of the report in the format yyyy-MM-dd'T'HH:mm:ss. For example: 2016-08-01T00:00:00. Note: if you supply an offset, ensure that it is equivalent to the timezone value.

endDate

Type string
Required ONLY if dateTypeId is 11
Description End time of date range of the report in the format yyyy-MM-dd'T'HH:mm:ss. For example: 2016-08-01T00:00:00. Note: if you supply an offset, ensure that it is equivalent to the timezone value.