Support Center

Kochava JSON API Documentation

Last Updated: Aug 05, 2014 04:27PM PDT

Mobile Advertiser Data Access API Integration Guide

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 downloads/installs of mobile apps and optimize the ad sources that are driving the quality installs at the right price using a publisher agnostic approach.  This API provides advertisers with the programmatic tools to gather performance data on a periodic basis.  The document describes the recommended approach to integrate with the Kochava system for the purpose of gathering this data.

Please find documentation on generating your API key here.

Get Apps Summary

To avoid the confusion of having to know which apps are registered (by ID) with Kochava, Kochava provides an API call which delivers a summary of all apps by account.
URL Parameter Example Value   Required
account account_name   yes
api_key 99e9215c24ee1842ceb513   yes

Sample URL to access campaign information:
 
http://control.kochava.com/v1/cpi/get_apps?account=account_name&api_key=99e9215c24ee1842ceb513
Response: A JSON array of
[{"name":"App Name","slug":"/app_name/","kochava_app_id":"koxxappnamexyz6b615","platform":"android","creation_date":"2012-11-29 08:23:27","sku":""}]

Campaign Summary

To understand the performance, in summary, of a campaign or all campaigns associated to an application, Kochava provides a JSON API with the following parameters and expected responses.
 
URL Parameter Example Value Description Required
start_date YYYY-MM-DD All data returned will be within the start_date and end_date (inclusive) Yes
end_date YYYY-MM-DD If not provided, returns one day of data (start_date only) No
timezone PST
(or: America/Los_Angeles)
If nothing is provided, defaults to UTC No
campaign_id kxxye-ipad164ea199e9215c24ee1842ceb513 Optional campaign ID.  If no ID is passed, then an enumeration of all campaigns for the given app is provided. No
kochava_app_id xxye-ipad164ea199e9215c24ee1842ceb513 Unique identifier of the application in the Kochava system.  Yes
api_key 99e9215c24ee1842ceb513 API Key provided with account for accessing data from the Kochava system. Yes
 
Sample URL to access campaign information:
 
http://control.kochava.com/v1/cpi/get_campaign_summary?start_date=2012-02-20&end_date=2012-03-31&kochava_app_id=xxxxxx&account=yyyyyy&timezone=pst&api_key=zzzzzz
 
Response: A JSON array of
[{"date":"2012-05-26","campaign_name":"V8","campaign_id":"kosampleapp45fbe954a509ea4fdcab75bb30f",
"impressions":"NA","clicks":0,"matched_installs":0,"spend":0},{"date":"2012-05-27","campaign_name":"V1",
"campaign_id":"kosampleapp45fbe954a509ea4fdcab75ea7f3","impressions":"NA","clicks":0,"matched_installs"
:0,"spend":0}]

Definitions of key/value responses:
"date"                             "2012-05-26"
"campaign_name"            This is the name of the Campaign
"campaign_id"                 "kosampleapp45fbe954a509ea4fdcab75bb30f" this is the campaign ID associated
                                       with the tracker
"impressions"                   RTB related does not pertain to CPC or CPI campaigns
"clicks"                            The # of clicks for this campaign that occured on "date"
"matched_installs"            The # of installs for this campaign that occured on "date"
"spend"                            The amount of spend for "campaign_name" on "date"

 

Campaign Specific Installs by Date

To understand the performance of a specific campaign, in detail, Kochava provides a JSON API with the following parameters and expected responses.  Kochava will provide any number of return device identifiers by populating the rtn_device_id_type provided that the advertiser sent Kochava the specific device id being requested.
URL Parameter Example Value Description Required
start_date YYYY-MM-DD Start date of data being queried. Yes
end_date YYYY-MM-DD End date of data being queried.  If not provided, returns one day of data (start_date only) Yes
timezone PST
(or: America/Los_Angeles)
If nothing is provided, defaults to UTC No
kochava_app_id kxxye-ipad165c24ee1842ca32039k2 Unique identifier of the application in the Kochava system. Yes
rtn_device_id_type android_id  | android_md5 | android_sha1 | imei | imei_md5 | imei_sha1 | udid | udid_md5 | udid_sha1 |idfa | idfv | Kochava_device_id | odin | mac String of device types that are being requested with each result, separated by comma “,”.  This is used in the event that both IMEI and Android_id are being requested for match. Yes
campaign_id kxxye-ipad164ea199e9215c24ee1842ceb513 If no campaign_id is sent, all live campaigns will be queried. Yes
api_key 4ea1kdk394jdkllks93kdj302ceb513 API Key provided with account for accessing data from the Kochava system. Yes
rtn_custom_id my_custom_id String representing a custom device identity as input via the identityLink feature of Kochava.  If rtn_custom_id is not included in the get request, nothing is returned.  If rtn_custom_id is passed, an additional column with named identity is included. If the value is not populated in Kochava, it will show as null in this api query. No
Sample URL to include in your application:

http://control.kochava.com/v1/cpi/get_installs?start_date=2012-02-20&end_date=2012-02-22&timezone=pst
&rtn_device_id_type=imei,android_id&campaign_id=kosampleapp45fbe954a509ea4fdcab75bb30f
&kochava_app_id=xxxxxx&api_key=yyyyyyyy&account=zzzzzzzzzz
Response: A JSON array of

[{"site_id":”ASDF1701D","network_id":"89","campaign_id":"kosampleapp45fbe954a509ea4fdcab75bb30f",
"creative":"2_320x50","click_date":"2012-05-26","bid_id":12345,"bid_price":0.034,"country_code":"NA",
"install_date":"2012-05-26","imei":"a10000face075e","android_id":"45df476cd919410d"},
{"site_id":"AOEUBSG75",'network_id":"11","campaign_id":"kosampleapp45fbe954a509ea4fdcab75bb30f”,
"creative":"","click_date":"2012-05-26","bid_id":0,"bid_price":0.04,"country_code":"NA", "install_date":
"2012-05-26","imei":"a000003070d3e3b","android_id":"4b58213cbf0d0fb2"}]

Definitions of key/value responses:
"site_id"                           The site_id is typically the app and/or locatio where the creative was served
"network_id"                     This is the network responsible for serving the creative
"campaign_id"                  Each tracker has a unique Campaign ID, this is the Campaign ID
                                       of the tracker that led to the install
"creative"                         This is the Creative_ID that was clicked which led to the install
"click_date"                      This is the timestamp of the click
"bid_id"                            This bid that is relevant to RTB
"bid_price"                        This is the price relative to the RTB
"country_code"                  The is the two character Country code (e.g. US/United States JP/Japan)
"install_date"                     This is the timestamp of the install notification
"imei"                                Internation Mobile Equipment Identifier
"android_id"                       A unique Android Device ID type
"idfa"                                 A unique iOS device Identifier for Advertisers
"idfv"                                  A unique iOS device Identifier for Vendors
"MAC"                               A unique identifier for both MAC and iOS, Media Access Control address


 

Enumerate Analytics Events
To understand the list of events being tracked, Kochava exposes the following API.

Sample Request URLs:
http://control.kochava.com/v1/cpi/get_events?kochava_app_id=koabcdef0123456789&api_key= abcdef0123456789&format=csv
 
Sample Response Data:
 
{
"name": "eventName1",
"segment_count": 4,
"segment_1": "Data",
"segment_2": "FB_Campaign",
"segment_3": "Network",
"segment_4": "Source"
},
 
{
"name": "eventName2",
"segment_count": 4,
"segment_1": "Data",
"segment_2": "FB_Campaign",
"segment_3": "Network",
"segment_4": "Source"
}
 
URL Parameter Example Value Description Required
kochava_app_id koappname0123456789abcdef Unique identifier of the application in the Kochava system.  Yes
api_key ABCDEFGH-5F0C-4641-9E18-FA745A32B172 API Key provided with account for accessing data from the Kochava system. Yes


Event Data

To understand post-install event data, Kochava provides event output with associated attribution information.
URL Parameter Example Value Description Required
Event_name InAppPurchase The name of the event yes
Max_records 100 Max records to output yes
kochava_app_id xxye-ipad164ea199e9215c24ee1842ceb513 Unique identifier of the application in the Kochava system.  Yes
api_key 99e9215c24ee1842ceb513 API Key provided with account for accessing data from the Kochava system. Yes
 
Filter Criteria:
&kochava_app_id     Kochava_App_ID (koappname0123456789abcdef)
&api_key            Unique API Key granting access to this Kochava Account (ab151cdf4844f27834d34a53adf277c3)
&event_name         Name of event (formatting, case sensitive - PlayerBoughtIAPVerified)
&max_rows           Events to export per page (default: 10000)
&max_time           Maximum page generation time (default: 180 seconds)
&time_start         When provided, exports only event data received after this timestamp
&date_start         When provided, exports only event data received after this strtotime() compatible date
&time_end           When provided, exports only event data received before this timestamp
&date_end           When provided, exports only event data received before this strtotime() compatible date
&attribution=false  When provided, skips attribution lookups for each device. This accelerates report generation at the cost of blank att_ columns
&device_data=true   When provided, enables detail lookups for each device. This slows down report generation, but populates the dev_ columns
&page=1             When returned records >= max_rows, gather subsequent "pages" of data using this filter
&format             Valid Export Formats: csv | json


Sample URL to access campaign information:
 
JSON export;
http://control.kochava.com/v1/cpi/get_event_data?kochava_app_id=koabcdef0123456789&api_key=abcdef0123456789&event_name=PlayerBoughtIAPVerified&max_rows=10000&time_start=1379980800&time_end=1380067200&page=1&format=json
 
CSV export;
http://control.kochava.com/v1/cpi/get_event_data?kochava_app_id=koabcdef0123456789&api_key=abcdef0123456789&event_name=PlayerBoughtIAPVerified&max_rows=100&date_start=Oct-01-2013%2022:00:00%20GMT&date_end=Oct-15-2013%2022:00:00%20GMT&page=1&format=csv
 
 
Sample Response Structure
{
"dev_id": "Kochava Device ID",
"att_camp": "Attribution Campaign",
"att_caid": "Attribution Campaign ID",
"att_tier": "Attribution Tier",
"att_trac": "Attribution Tracker",
"att_netw": "Attribution Network",
"att_site": "Attribution Site",
"att_crea": "Attribution Creative",
"dev_type": "Device Type",
"eng_acqu": "(int) Engagement Acquisition Date",
"eng_sess": "(int) Engagement Session Count - unique app usage instances to date",
"eng_dura": "(int) Engagement Duration - seconds spent in app to date",
"geo_code": "Geographical Code (State/Country)",
"geo_city": "Geographical City",
"eve_time": "(int) Event Time",
"eve_data": "Event Data - level id / purchase price / etc"
}
Sample Response Data: A JSON array of
  [{"dev_id":"KV64f9bdc32749d456dbcbe5938fc06988","att_camp":null,"att_caid":null,
"att_tier":null,"att_trac":null,"att_netw":null,"att_site":null,"att_crea":null,
"eng_acqu":1379368037,"eng_sess":2,"eng_dura":null,"geo_code":"US","geo_city":
"Oklahoma City","eve_time":1379368037,"eve_data":1},{"dev_id":
"KV8adb3c732ff191178db6fe6d58225bda","att_camp":null,"att_caid":null,
"att_tier":null,"att_trac":23432,"att_netw":"Facebook","att_site":null,"att_crea":
null,"eng_acqu":1379368033,"eng_sess":2,"eng_dura":null,"geo_code":"US","geo_city":
"Unknown","eve_time":1379368039,"eve_data":0.99}]
  Clicks API
 
The get_clicks api event provides clicks for a specified time and network. Due to the volume of data, the data is limited to 10,000 records at a time and must be pulled across multiple pages in order to collect all data. 
 
URL Parameter Example Value Description Required
&start_date 2014-06-04 Start date of data being queried. Yes
&end_date 2014-06-05 End Date of date being queried, pulls data less than date specified. Yes
&app 1234 Numeric App ID Yes
&api_key 99e9215c24ee1842ceb513 API Key provided with account for accessing data from the Kochava system. Yes
&network 99 This is the network responsible for serving the creative Yes
&format json Valid Export Formats: csv | json No, Defaults to JSON
&page 0 When returned records >= 10,000 records, gather subsequent "pages" of data using this filter No, but a hard limit of 10,000 records is set per page.
 
Sample Request URL:
 
Sample Response Data:
{
"Date (UTC)": "2014-06-17 01:58:34",
"Status": "publish",
"Primary Identifier": "12.345.67.89",
"Campaign ID": "kxxye-ipad164ea199e9215c24ee1842ceb513",
"Network ID": "471",
"Site ID": "none-provided",
"Creative ID": null,
"Click ID": "kochavaClickID12345",
"Kochava Click ID": null,
"Device ID": "device_id",
"Device ID Type": null,
"Device ID Is Hashed": null,
"Device ID Hash Method": null,
"Origination IP": null,
"Prior": null,
"Price": null
}

Contact Us

http://assets02.desk.com/
false
kochavamobile
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete