Support Home > Analytics, Reports & API > API v1.0 – Reporting Methods

API v1.0 – Reporting Methods

DOCUMENT SUPERSEDED: The information that is contained within this document has been superseded. Refer to the current API Reporting support document for the latest integration instructions and procedures.

The Data Access API Integration provides additional reporting tools to supplement those available through the Kochava platform.

The Kochava platform provides extensive tools to track everything from impressions thru post-install events for connected devices. The API reporting method provides advertisers with the programmatic tools to gather performance data on an on-demand or scheduled basis.

This document describes the recommended approach to integrate with Kochava for the purpose of gathering data using the API reporting method. If you need help generating an API key, refer to our Create and Manage API Key support documentation.

 

WARNING: If the provided API Key does not match an existing app, a “error”:”App does not exist.” response will be returned. For further information, contact your Client Success Management team.

 

API Reporting Structure

 

Parameter Description Format Valid in Report Req.
api_key The api key linked to the app to report on. string Summary
Detail
Yes
app_guid Unique app ID that includes the app name and an alphanumerical string. string Summary
Detail
Yes
time_start Epoch (UTC) format in sec. Start time of the reporting, must be a full hour (2:00 acceptable, 2:15 not acceptable). string Summary
Detail
Yes
time_end Epoch (UTC) format in sec. End time of the reporting, must be in full hour (2:00 acceptable, 2:15 not acceptable). string Summary
Detail
Yes
traffic Traffic type and counters needed to report on. []string *Summary (click, impression, install, event, reengagement, trafficverif)
*Detail (click, impression, install, event, reengagement, trafficverif, influencer_imp, influencer_click)
Yes
traffic_including What is desired to be included, in addition to the regular fields for the detail report. []string Detail:
Attribution – install and click traffic
identity_link – install and event traffic
Trafficverifier – install and click traffic
Customparameter – all traffic
unattributed_traffic – unattributed traffic
No
traffic_grouping **The manner in which the summary report is grouped by. By default, the date (based on time series) and any other field included. string Summary No
time_zone What time zone should the date fields be shown in, in addition to UTC. (“America/New_York”, “America/Vancouver”, “America/Los_Angeles”, “Asia/Seoul”, “Europe/Paris”) string Summary
Detail
No
time_series ***Grouping period. []string Summary Yes
traffic_filtering What the report is limited to. map[string][]string Summary
Detail
No
custom_report_name The name of the report needed to be run. Overwrites the traffic, grouping and all other report structure. string Summary
Detail
Yes
delivery_format The format in which the report is generated. (comma delimited or JSON) string Summary
Detail
Yes
delivery_method The means by which the report is delivered. (S3link) []string Summary
Detail
No
notify The email to which the report link is sent. []string Summary
Detail
No

*For Detail reports limited to one traffic type, Summary can contain more than 1 traffic type.
** The list of fields can be obtained by using the grouping call.
*** 1=1 hour, 4=4 hour blocks (0-4, 4-8, 8-12, 12-16, 16-20, 20-24), if 24, group by day.


Requesting a Summary Reports

A Summary Report is a report showing counters for the traffic requested for a specific timeframe, and grouped by the fields requested in the API call. More than 1 counter can be selected by including multiple “traffic” parameters.

 

Post Endpoint:

https://reporting.api.kochava.com/summary

 

Sample Post Data:

 

Successful Response Example:

 

Error Response Example:

 

Grouping Fields for Summary Report:

This call returns the list of fields that can be used in the API for grouping the result.

 

Post Endpoint:

https://reporting.api.kochava.com/grouping

 

Sample Post Data:

 

Filtering Fields for Summary Report:

This call returns the list of fields that can be used in the API for filtering the data returned in the report.

 

Post Endpoint:

https://reporting.api.kochava.com/filtering

 

Sample Post Data:


Requesting a Detail Report

A Detail Report is a report showing original data for the traffic requested for a specific timeframe requested in the API call.

 

NOTE: For event traffic, the following events are excluded Install, _Install, _Click, _SessionBegin and _SessionEnd.

NOTE: If a filter is included with the request on events, only that event_name will be selected.

 

Post Endpoint:

https://reporting.api.kochava.com/detail

 

Sample Post Data:

 

Successful Response Example:

 

Error Response Example:

 

Obtaining a Report Status

Once a report has been successfully submitted, the status of the report can be obtained through an API call.

 

Post Endpoint:

https://reporting.api.kochava.com/progress

 

Sample Post Body:

 

Successful Response Example:

 

Error Response Example:

 

Delete a Queued Report

While a report is queued, it may be deleted. Once the report has run or is running, the operation cannot be canceled.

 

Post Endpoint:

https://reporting.api.kochava.com/delete

 

Sample Post Data:

 

Successful Response Example:

 

Error Response Example:

 

Reports Generated by API Key

It is possible to view the last reports submitted by a specific account (API key).

 

Post Endpoint:

https://reporting.api.kochava.com/tokens

 

Sample Post Data:

 

Successful Response Example:

 

Scheduling Reports Overview

Reports can be scheduled to run repeatedly as needed on a daily, weekly, monthly or quarterly basis. The start date and end date need to be calculated for every report run.

 

The following fields will assist in the scheduling:

Field Description
runon Defines when the report will run.
delay The value used to calculate the end date of the report from the runon time.
previoustime The difference between the start and end time.

 

Example:

Frequency RunOn Delay PreviousTime* Description
daily Hour
0
13
2
Hour
0
1
2
Hour
24
24
48
Start @ 0:00 for the past full day (24 hours)
Start @ 1:00 PM for the past 24 hrs (day -1 12:00 PM to 12:00PM)
Start @ 2:00 for the past full 2 days >=day-2@00:00 and < day:00:00(48 hours)
weekly dayID
1
1
6
1
Day
0
1
0
0
Day
7
7
5
2
Start on Monday @ 0:00 for the previous week (Mon->Sund)
Start on Monday @ 0:00 for the previous week (Sund->Sat)
Start on Saturday @ 0:00 for the previous weekday (Mon->Frid)
Start on Monday @ 0:00 for the previous weekend (Sat,Sund)
monthly dayDate
1
15
16
1
Day
0
14
0
0
Month
1
2
2
6
Run on the 1st of the month @ 0:00 for the entire previous month.
Run on the 15th of the month @ 0:00 for the previous 2 months
Run on the 16th for the previous month and 1/2 (1st of month -1 to 15 of current month)
Run on the 1st of the month @ 0:00 for the previous 6 months.

*The unit for “previous time” is different for each frequency because an hour/day/week is fixed. Month and Quarter are not fixed.

 

API Structures:

The structure for APIs are similar to the structures listed in the API Reporting Structure Section, with the following differences:

Parameter Difference Description Format Valid in Report Req.
time_start Removed
time_end Removed
frequency Added How often the report should run (hourly, daily, weekly, monthly or quarterly). string Summary
Detail
Yes
run_on Added When the report should run (on the x day, hour, minute, etc.). string Summary
Detail
Yes
previous_time Added What period of time is included in the report. string Summary
Detail
Yes
delay Added What is the end date of the report, based on when it ran. string Summary
Detail
Yes

 

Schedule a Summary Report

Post Endpoint:

https://reporting.api.kochava.com/schedule/summary

 

Sample Post Data:

 

Successful Response Example:

 

Schedule a Detail Report

Post Endpoint:

https://reporting.api.kochava.com/schedule/detail

 

Sample Post Data:

 

Successful Response Example:


Scheduled Reports Generated by API Key

It is possible to view the last reports submitted by a specific account (API key).

 

Post Endpoint:

https://reporting.api.kochava.com/schedule/tokens

 

Sample Post Data:

 

Successful Response Example: