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 on-demand basis. The document describes the recommended approach to integrate with the Kochava system for the purpose of gathering this data. If you need help generating an API key, please see our article on how to generate an API key.
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 Request URL:
http://control.kochava.com/v1/cpi/get_apps?account=account_name&api_key=99e9215c24ee1842ceb513″ target=”_blank”>http://control.kochava.com/v1/cpi/get_apps?account=account_name&api_key=99e9215c24ee1842ceb513
Sample Response Data:
1 2 3 4 5 6 7 8 | { "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 | Req. |
|---|---|---|---|
| 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 Pacific | 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 Request URL:
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” target=”_blank”>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
Sample Response Data:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | { "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 | Req. |
|---|---|---|---|
| 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 Pacific | No |
| kochava_app_id | kosampleapp45fbe954a509ea4fdcab75ea7f3 | 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 | kosampleapp45fbe954a509ea4fdcab75ea7f3 | If no campaign_id is sent, all live campaigns will be queried. | Yes |
| api_key | 4ea1kdk394jdkllks93kd2ceb513 | 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 Request URL:
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” target=”_blank”>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
Sample Response Data:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | { "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 location 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.
| URL Parameter | Example Value | Description | Req. |
|---|---|---|---|
| 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 |
| format | json | Define the format of the data returned – choose between JSON or CSV | Yes |
Sample Request URL:
http://control.kochava.com/v1/cpi/get_events?kochava_app_id=koabcdef0123456789&api_key=%20abcdef0123456789&format=csv” target=”_blank”>http://control.kochava.com/v1/cpi/get_events?kochava_app_id=koabcdef0123456789&api_key= abcdef0123456789&format=csv
Sample Response Data:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | { "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" } |
Event Data
To understand post-install event data, Kochava provides event output with associated attribution information.
| URL Parameter | Example Value | Description | Req. |
|---|---|---|---|
| Event_name | InAppPurchase | The name of the event | Yes |
| Max_records | 100 | Max records to output | Yes |
| kochava_app_id | kosampleapp45fbe954a509ea4fdcab75ea7f3 | 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
&page=1 When returned records >= max_rows, gather subsequent “pages” of data using this filter
&format Valid Export Formats: csv | json
&detail=verbose Returns device identifiers.
Sample Request URLs:
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”>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”>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 Data:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | { "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" } |
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.
| JSON Property | Example Value | Description | Req. |
|---|---|---|---|
| &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 | Kochava network id for publisher network for which click logs are desired | Yes |
| &format | json | Defines the output format of the reported data (default=JSON) | No |
| &page | 1 | Defines the page being queried. Max page length=10,000 records. If report length>10,000 records, specific pages must be queried to receive complete data set. (default=1) | No |
Sample Request URL:
http://control.kochava.com/v1/cpi/get_clicks?start_date=2014-06-04&end_date=2014-06-05&app=1234&api_key=99e9215c24ee1842ceb513&network=99&format=json&page=2″ target=”_blank”>http://control.kochava.com/v1/cpi/get_clicks?start_date=2014-06-04&end_date=2014-06-05&app=1234&api_key=99e92c24ee1842ceb513&network=99&format=json&page=2
Sample Response Data:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 | { "Date (Pacific)": "2014-06-17 01:58:34", "Status": "publish", "Primary Identifier": "12.345.67.89", "Campaign ID": "kosampleapp45fbe954a509ea4fdcab75ea7f3", "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 } |
