03 - Reporting API - Generating a report

Notions

Date

A date is a JSON string with the following value:

Value Description Example
yyyy-MM-dd'T'HH:mm:ss
A simple date
1984-12-28T10:10:00

You can also use relative dates in direct or scheduled tasks. They will take their values relatively to the real job execution date.

A relative date is a JSON string, which can take these values:

Value Description Example
CURRENT_DAY+-x
the current day at midnight (0 hours, 0 minutes, 0 seconds, 0 ms), with the specified modifier
CURRENT_DAY-1 means yesterday
CURRENT_DAY+1 means tomorrow at midnight
CURRENT_HOUR+-x
the current hour (lowered to the 0th minute) with the specified modifier assume that the current time is 14h45;
then, CURRENT_HOUR+1 means 15h00
CURRENT_WEEK+-x
the current week (lowered to Monday morning at 00h00) with the specified modifier assume today is Wednesday;
then, CURRENT_WEEK+1 means: Monday morning at 00h00 in the upcoming week
CURRENT_MONTH+-x:
the current month (lowered to the first day of the month at 00h00) with the specified modifier assume today is 16th October;
then, CURRENT_MONTH+1 means 01 November at 00h00
NOW the current hour of execution

Job Periodicity

The Job Periodicity is a JSON string, which specifies the scheduling periodicity of a job. Below are its possible values:

Value Description Example
FIXED_DATE/yyyy-MM-dd'T'HH:mm:ss
The job will run exactly once, at the specified date
FIXED_DATE/2016-07-27T17:00:00
HOURLY*x
The job will run every x hours.                          
HOURLY*4=> the job will run every four hours
DAILY*x
The job will run every x days.
DAILY*4=> the job will run every four days
WEEKLY*x
The job will run every x weeks.
WEEKLY*4=> the job will run every 4 weeks
MONTHLY*x
The job will run every x months.
MONTHLY*2=> the job will run every 2 months

Note: if x is not specified, its default value is 1 (meaning every hour, every day...)

Task

A task defines

  • the fields contained in the generated report
  • the filters
  • the output destination
  • the output name
  • the scheduling (if available).

A task is considered "ONGOING" as long as it is still expected to generate new reports.

Task Instance

A task instance is the actual launch of a task. It includes among others:

  • the actual date range of the logs used
  • the filename generated
  • the file size
  • the instance status

For non-scheduled tasks, there will be one instance per task.
For scheduled task, there will be a new instance created for each execution of the task.

Generating a report

Request body

The body contains a JSON specifying the parameters of the report.

Property
Value Type
Notes
startDate
RelativeDate
The lower date of the logs to compute from.
Mandatory field
endDate
RelativeDate
The upper date of the logs to compute from.
Mandatory field
filter
[
  {
    String:String[],
    String:String[],
    ...
  },
  {
    String:String[],
    ...
  }
]
Each group is a dictionary containing one or more pair(s) of (criterion,value[])
A group is always an "OR" between criteria in the same dimension.
The logical connector between all groups is always an "AND".
advancedFilter is recommended (instead of filter).1
You can use only one of filter or advancedFilter at a time.
advancedFilter

Same function as filter plus these features1:
  • more operators: equal, not equal, starts with, contains, greater than, less than
  • allows for AND-connection of criteria of the same dimension
  • You can use only one of filter or advancedFilter at a time
fields
[
  String: {
    String:String,
    ...
  },
  ...
]

List of aggregation and metrics to be computed.2 Mandatory field
OutputParameters



outputDestination: String
SQL/HDFS/FTP: the type of output of the task (a file, an SQL table...).
Default: HDFS

datePattern: String
The pattern of all date fields in the output generated.
Note: SQL date format is forced to 'yyyyMMdd HH:mm:ss‘. Default: NET

timezone: String
NET/UTC/PARTNER
The timezone to be used in the output dates.
Note: the partner timezone is specific to RTB+.
Default: NET

sqlOutputTableName: String
The name of the SQL table to be generated. Note: if the table already exist, it will be completed, if possible.

relativeDirectory: String
The subdirectory to be used for FTP output (the base directory being the one of the network)

filenameTemplate: String
The file name to be generated.
You can insert a tag containing a relative date in this file name. This is useful for scheduled task which will generate different files every days, hours...

Example: report_[CURRENT_DAY].txt

Only one type of tag can be used at a time. The following is NOT valid: report_[CURRENT_DAY]_something_[CURRENT_HOUR]


displayHeader: boolean
True/False
specifies if the header will be included in the generated file (default: true)

encoding: String The encoding of the output file
Default: UTF-8
Choose from the Supported Encodings
onFinish
Actions to perform when computation is finished and has been handled

sendEmailsTo: String[] A list of e-mails which will be contacted once the report has been computed successfully
onError


sendEmailsTo: String[]
A list of emails internal to Smart AdServer which will be contacted when the report generation ends in an error

1 Learn more about Advanced filtering here

2 Learn more about Aggregation here

Response header

The response header may contain an error message which has these characteristics:

  • Property name: Error
  • Value type: String
  • Mandatory: no

Response body

The response body is A JSON object containing the taskid and taskinstanceid. 
These ids may be used to get information about this task from the other services
.

Example:

{
   "taskId":"751BF544-4DFC-4939-9306-5E1B0892D75E",
   "instanceId":"8624D930-444C-450D-A74F-C5603AD2FE12"
}

Exemple 1 - Basic input body

This input will generate a report containing the number of impressions, per insertion:

{  
   "startDate":"2016-02-09T00:00:00",
   "endDate":"2016-02-10T00:00:00",
   "fields":[  
      {  
         "Impressions":{  
         }
      },
      {  
         "InsertionName":{  
         }
      }
   ]
}

Example 2 - Input body with filter

This input is based on Example 1, but with restrictions regarding the SiteName and AdvertiserNames for each insertion:

  • SiteName => must be exactly "aufeminin.com" or "world" and
  • AdvertiserName => must be exactly "Smart AdServer"
{
   "startDate":"2016-02-09T00:00:00",
   "endDate":"2016-02-10T00:00:00",
   "fields":[
      {
         "InsertionName":{
         }
      },
      {
         "Impressions":{
         }
      }
   ],
   "filter":[
      {
         "SiteName":[
            "aufeminin.com",
            "world"
         ],
         "AdvertiserName":[
            "Smart AdServer"
         ]
      }
   ]
}

Example 3 - Input body with advancedFilter and outputParameters

This input is based on Example 1, but with complex filters:

  • PageName => must now CONTAIN "game"
  • CountryName => must be equal to one of the specified values
  • SiteName => must NOT BE EQUAL to "smart" nor "feminin"
{
   "startDate":"2016-02-09T00:00:00",
   "endDate":"2016-02-10T00:00:00",
   "fields":[
      {
         "InsertionId":{
         }
      },
      {
         "Impressions":{
         }
      }
   ],
   "advancedFilter":[
      [
         {
            "PageName":{
               "operator":"contains",
               "values":[
                  "game"
               ]
            }
         },
         {
            "CountryName":{
               "operator":"eq",
               "values":[
                  "united states",
                  "canada",
                  "brazil",
                  "mexico"
               ]
            }
         }
      ],
      [
         {
            "SiteName":{
               "operator":"neq",
               "values":[
                  "feminin",
                  "smart"
               ]
            }
         }
      ]
   ],
   "outputParameters":{
      "outputDestination":"SQL",
      "timeZone":"NET",
      "isScheduled":false,
      "keepOldOrder":false
   }
}

Example 4 - Input body with video metrics

{
   "startDate":"2016-02-09T00:00:00",
   "endDate":"2016-02-10T00:00:00",
   "fields":[
      {
         "InsertionName":{
         }
      },
      {
         "Impressions":{
         }
      },
      {
         "VideoCount":{
            "id":"10007"
         }
      }
   ]
}

Note: 10007 is the id of "inventory"; to get all events, go to the technical documentation and use the "events" resource.

Example 5 - Input body with keywords

{
   "startDate":"2016-02-09T00:00:00",
   "endDate":"2016-02-10T00:00:00",
   "fields":[
      {
         "InsertionName":{
         }
      },
      {
         "Impressions":{
         }
      },
      {
         "Keyword":{
            "value":"user_age"
         }
      },
      {
         "Keyword":{
            "value":"user_sexe"
         }
      }
   ]
}

Example 6 - Scheduled daily RTB report with FTP output

If you have an FTP directory provided by Smart AdServer, the output will be stored there.

Get back to your service contact if you do not have an FTP directory, yet.

{
   "scheduling":{
      "jobperiodicity":"DAILY",
      "schedulingStartDate":"2016-10-08T04:30:00",
      "schedulingEndDate":"2030-03-20T04:30:00"
   },
   "startDate":"CURRENT_DAY-1",
   "endDate":"CURRENT_DAY",
   "fields":[
      {
         "SiteId":{
         }
      },
      {
         "PageId":{
         }
      },
      {
         "SiteName":{
         }
      },
      {
         "FormatId":{
         }
      },
      {
         "ImpressionsTrueCount":{
         }
      },
      {
         "TotalPaidPriceTrueCount":{
         }
      }
   ],
   "outputParameters":{
      "outputDestination":"FTP",
      "fileNameDateFormat":"yyyyMMdd",
      "fileNameTemplate":"RTB_[CURRENT_DAY-1].csv",
      "relativeDirectory":"API_DAILY_STATS/RTB/",
      "datePattern":"dd/MM/yyyy HH:mm:ss"
   }
} 

Getting the report generation status

Request body

Entry point description HTTP method URI
Getting the report generation status GET http://reporting.smartadserverapis.com/[NETWORK_ID]/reports/
[TASKID]/instances/[TASK_INSTANCE_ID]

Response body

The response body is a JSON object containing the following properties.

Property Name
Value type
Comment
taskId String
taskInstanceId String
instanceStatus String The status of the report. The final value is "SUCCESS". Any other value means that the job is currently running, or failed.
creationDateUTC Date The date at which the report generation request was received
completionDateUTC Date The date at which the report generation was completed
statsMinDateUTC Date The actual begin date for the taken logs
statsMaxDateUTC Date The actual end date for the taken logs
nbOutputLines long Number of lines generated in the final file or table (only filled when a file or table was actually generated successfully)
jobProgress double The progression of the report computation: 0=Not started yet, 1=Report computed
taskOutputs Array
taskOutputs:taskId

taskOutputs:taskInstanceId

taskOutputs:outputStatus String Status of the generated file: SUCCESS/EMPTY/TOO_LARGE
taskOutputs:outputName String Name of the generated output (tablename or filename)
taskOutputs:nbOutputLines int Number of lines in the output
taskOutputs:filesize long The size of the file generated in bytes

Example - Result before report generation

{
    "taskReference": {
        "taskId": "7062BA69-1E84-423D-9E16-9C9C285F6C42",
        "taskStatus": "COMPLETE",
        "creationDateUTC": "2016-07-27T10:01:00",
        "createdBy": 6375,
        "externalRefId": 0,
        "networkIds": [73],
        "taskStartDate": {
            "relativeDateBase": "FIXED_DATE",
            "modifier": 0,
            "fixedDate": "2016-07-01T00:00:00"
        },
        "taskEndDate": {
            "relativeDateBase": "FIXED_DATE",
            "modifier": 0,
            "fixedDate": "2016-07-13T00:00:00"
        },
        "originalJSon": "{\"startDate\" : \"2016-07-01T00:00:00\",\n\"endDate\" : \"2016-07-13T00:00:00\",\n\"advancedFilter\": [],\n\t\t\"fields\": [{\n\t\t\t\"Day\": {}\n\t\t}, {\n\t\t\t\"InsertionId\": {}\n\t\t},{\n\t\t\t\"Impressions\": {}\n\t\t}\n\t\t],\n\t\t\"networkIds\": [73],\n\t\t\"outputParameters\": {\n\t\t\t\"outputDestination\": \"SQL\"\n}\n}"
    },
    "taskInstanceId": "BE4A15AF-B24F-4CB0-BE82-6A230CF13A16",
    "instanceStatus": "JOB_SUBMITTED",
    "instanceCreationDateUTC": "2016-07-27T10:01:00",
    "statsMinDateUTC": "2016-07-01T00:00:00",
    "statsMaxDateUTC": "2016-07-13T00:00:00",
    "nbOutputLines": 159
}

Example - Result after report generation

{
    "taskReference": {
        "taskId": "7062BA69-1E84-423D-9E16-9C9C285F6C42",
        "taskStatus": "COMPLETE",
        "creationDateUTC": "2016-07-27T10:01:00",
        "createdBy": 6375,
        "externalRefId": 0,
        "networkIds": [73],
        "taskStartDate": {
            "relativeDateBase": "FIXED_DATE",
            "modifier": 0,
            "fixedDate": "2016-07-01T00:00:00"
        },
        "taskEndDate": {
            "relativeDateBase": "FIXED_DATE",
            "modifier": 0,
            "fixedDate": "2016-07-13T00:00:00"
        },
        "originalJSon": "{\"startDate\" : \"2016-07-01T00:00:00\",\n\"endDate\" : \"2016-07-13T00:00:00\",\n\"advancedFilter\": [],\n\t\t\"fields\": [{\n\t\t\t\"Day\": {}\n\t\t}, {\n\t\t\t\"InsertionId\": {}\n\t\t},{\n\t\t\t\"Impressions\": {}\n\t\t}\n\t\t],\n\t\t\"networkIds\": [73],\n\t\t\"outputParameters\": {\n\t\t\t\"outputDestination\": \"SQL\"\n}\n}"
    },
    "taskInstanceId": "BE4A15AF-B24F-4CB0-BE82-6A230CF13A16",
    "instanceStatus": "SUCCESS",
    "instanceCreationDateUTC": "2016-07-27T10:01:00",
    "statsMinDateUTC": "2016-07-01T00:00:00",
    "statsMaxDateUTC": "2016-07-13T00:00:00",
    "nbOutputLines": 159,
    "taskOutputs": [{
        "settingId": 1,
        "statDomain": 5,
        "outputStatus": "SUCCESS",
        "outputName": "Extract_BE4A15AF_B24F_4CB0_BE82_6A230CF13A16_1",
        "nbOutputLines": -1,
        "filesize": 6906
    }]
}

Getting the report file

To get the report file, use this service (only applicable for HDFS outputs)

Entry point
description
HTTP
Method
URI
Get the report
GET
https://reporting.smartadserverapis.com/[NETWORK_ID]/reports/
[TASK_ID]/file

or

https://reporting.smartadserverapis.com/[NETWORK_ID]/reports/
[TASK_ID]/instances/[TASK_INSTANCE_ID]/file

Response body

The response body includes the generated report corresponding to the specified taskId and fileName, if available.

HTTP response errors

In case of errors (request cannot be processed), the response will include a status code indicating the type of error:

HTTP Status Code Description
401 Unauthorized
404
Not Found
500
Internal Server Error
Was this article helpful?
0 out of 0 found this helpful
Powered by Zendesk