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.
For clarity, our support documentation for API v1.4 has been divided into the following sections:
- Call Structure
- Querying API
- Requesting and Scheduling Reports
The following document defines the structure and the methods for Querying the API.
NOTE: There are several sources of Restricted data you will see across views in Query, Reporting and Analytics. This is data the media channel prohibits Kochava from sharing at the row level, but you will find the channel information contained in your summary reporting. Please reach out to your Kochava Client Success Management Team for more information.
Structure for Querying API
| Parameter | Description | Format |
|---|---|---|
| api_key | The api key linked to the user. | string |
| app_guid | The name of the app to report on. | string |
| token | The token ID of the report that was returned when the report was created. | string |
| max_tokens | Maximum number of requests to return. | int |
Query Authorized Fields for Grouping
Endpoint:
POST: https://reporting.api.kochava.com/v1.4/grouping
Response Data:
{
"status": "OK",
"valid_fields": [
"country",
"network",
"campaign",
"site",
"tracker",
"creative",
"state",
"dma",
"city",
"cp_0",
"cp_1",
"cp_2",
"cp_3",
"cp_4",
"cp_5",
"cp_6",
"cp_7",
"cp_8",
"cp_9"
]
}Query Authorized Fields for Filtering
Endpoint:
POST: https://reporting.api.kochava.com/v1.4/filtering
Response Data:
{
"status": "OK",
"valid_fields": [
"country",
"network",
"campaign", ** ONLY APPLY TO SUMMARY REPORT
"site",
"tracker",
"creative"
]
}Query Authorized Values for Timezones
Endpoint:
POST: https://reporting.api.kochava.com/v1.4/timezones
Response Data:
{
"status": "OK",
"valid_fields": [
"Africa/Abidjan",
"Africa/Accra",
"Africa/Addis_Ababa",
"Africa/Algiers",
"Africa/Asmara",
...
"US/Indiana-Starke",
"US/Michigan",
"US/Mountain",
"US/Pacific",
"US/Pacific-New",
"US/Samoa",
"UTC",
"W-SU",
"WET",
"Zulu"
]
}Query Report Templates
This call return the list of templates that have been created in the system (and stored in kochava_reports.templates. Each template is returned with the pre-set/default values for all the parameters (traffic, grouping, etc…).
Endpoint:
POST: https://reporting.api.kochava.com/v1.4/templates
Response Data:
{
"status": "OK",
"template_values": [
{
"name": "Click",
"category": "Detail",
"traffic": {
"click": true
},
"grouping": "",
"filtering": {
"country": true,
"network": true,
"tracker": true
},
"traffic_includes": {
"attribution": false,
"custom_parameters": false,
"identity_link": false,
"traffic_verification": false
},
"time_series": "",
"network_enabled": 1,
"admin_only": 0
},
{
"name": "Click Influencer",
"category": "Detail",
"traffic": {
"influencer_click": true
},
"grouping": "",
"filtering": {
"network": true
},
"traffic_includes": null,
"time_series": "",
"network_enabled": 0,
"admin_only": 0
},
{
"name": "Event",
"category": "Detail",
"traffic": {
"event": true
},
"grouping": "",
"filtering": {
"event_name": true,
"network": true
},
"traffic_includes": {
"attribution": false,
"custom_parameters": false,
"identity_link": false,
"traffic_verification": false,
"unattributed_traffic": false
},
"time_series": "",
"network_enabled": 0,
"admin_only": 0
},
{
"name": "Fractional",
"category": "Detail",
"traffic": {
"fractional": true
},
"grouping": "",
"filtering": {
"network": true
},
"traffic_includes": null,
"time_series": "",
"network_enabled": 0,
"admin_only": 1
},
{
"name": "Impression Influencer",
"category": "Detail",
"traffic": {
"influencer_imp": true
},
"grouping": "",
"filtering": {
"network": true
},
"traffic_includes": null,
"time_series": "",
"network_enabled": 0,
"admin_only": 1
},
{
"name": "Network",
"category": "Summary",
"traffic": {
"click": true,
"event": false,
"impression": true,
"install": true
},
"grouping": "{\n \"network\": true,\n \"campaign\": false,\n \"tracker\":false,\n \"site\": false,\n \"creative\": false,\n \"country\": false,\n \"dma\": false,\n \"state\": false,\n \"city\": false,\n \"cp_0\": false,\n \"cp_1\": false,\n \"cp_2\": false,\n \"cp_3\": false,\n \"cp_4\": false,\n \"cp_5\": false,\n \"cp_6\": false,\n \"cp_7\": false,\n \"cp_8\": false,\n \"cp_9\": false\n}",
"filtering": {
"country": true,
"network": true,
"tracker": true
},
"traffic_includes": null,
"time_series": "1",
"network_enabled": 1,
"admin_only": 0
}
]
}Query Columns Templates
By default, the Reporting system will generate report with all columns available (>100 in most cases). This may be too much for most request. Each report is broken up into several parts and for each part, columns can be removed or reordered to fit every users needs.
The call to the API is made for an API Key and app GUID. The report can be passed, however if it is not, all report columns will be returned. Each user can have default reports set to their individual preference. The call can limit to a report. This call return the list of “parts” and for each one, the order AND the fields selected and field available. If a call is made for all reports, it will return the reports that have specific default for that API Key/App and the default set-up for the ones without. For example, you may get the specific set-up for Install but get the default for Click and Event
Endpoint:
POST: https://reporting.api.kochava.com/v1.4/reportcolumns
Sample Post Data:
{
"api_key": "03B9A6AD-4CFB-439B-9B31-EBBB73A199BD",
"app_guid": "koyahoo-android53c9699b06059",
"report": "install"
}
Sample Response:
{
"status": "OK",
"template_values": [
{
"api_key": "DEFAULT",
"app_id": 0,
"report_type": "install",
"report_section": "default",
"section_order": 1,
"columns_selected": [
"install_matched_on",
"install_matched_by",
"install_status",
"install_impression_date_utc",
"install_impression_date_adjusted",
"install_click_date_utc",
"install_click_date_adjusted",
"install_date_utc",
"install_date_adjusted",
"kochava_click_id",
"partner_click_id",
"install_kochava_device_id",
"attribution_tracker",
"attribution_tracker_name",
"attribution_network",
"attribution_network_name",
"attribution_campaign",
"attribution_campaign_name",
"attribution_site",
"attribution_creative",
"installgeo_country_code",
"installgeo_country_name",
"installgeo_city",
"install_original_request",
"install_price",
"install_devices_ids",
"install_devices_idfa",
"install_devices_android_id",
"install_devices_adid",
"install_devices_custom",
"install_devices_waid",
"install_devices_email_0",
"install_devices_email_1",
"install_devices_ip",
"install_device_version",
"install_device_ua"
],
"columns_available": null
},
{
"api_key": "DEFAULT",
"app_id": 0,
"report_type": "install",
"report_section": "click_detail",
"section_order": 2,
"columns_selected": null,
"columns_available": [
"click_month",
"click_status",
"click_network",
"click_network_name",
"click_tracker",
"click_tracker_name",
"click_campaign",
"click_campaign_name",
"click_site",
"click_creative",
"click_country_code",
"click_ip",
"click_device_ver",
"click_device_ua",
"click_device_id",
"click_original_request",
"click_matched_impression",
"click_matched_install",
"click_identifiers",
"click_identifiers_idfa",
"click_identifiers_android_id",
"click_identifiers_android_id_md5",
"click_identifiers_android_id_sha1",
"click_identifiers_adid",
"click_identifiers_custom",
"click_identifiers_waid",
"click_identifiers_ip",
"click_identifiers_email_0",
"click_identifiers_email_1",
"click_geolocation",
"click_duplicate",
"clickgeo_continent_code",
"clickgeo_country_code",
"clickgeo_country_code3",
"clickgeo_country_name",
"clickgeo_region",
"clickgeo_postal_code",
"clickgeo_dma_code",
"clickgeo_city",
"clickgeo_area_code",
"clickgeo_longitude",
"clickgeo_latitude"
]
},
{
"api_key": "DEFAULT",
"app_id": 0,
"report_type": "install",
"report_section": "impression_detail",
"section_order": 3,
"columns_selected": null,
"columns_available": [
"impression_network",
"impression_network_name",
"impression_tracker",
"impression_tracker_name",
"impression_campaign",
"impression_campaign_name",
"impression_site",
"impression_creative",
"impression_country_code",
"impression_original_request",
"impression_matched_install",
"impression_matched_click",
"impression_ip",
"impression_imp_id",
"impression_identifiers",
"impression_device_ver",
"impression_kochava_imp_id"
]
},
{
"api_key": "DEFAULT",
"app_id": 0,
"report_type": "install",
"report_section": "geo_detail",
"section_order": 4,
"columns_selected": null,
"columns_available": [
"installgeo_continent_code",
"installgeo_country_code3",
"installgeo_region",
"installgeo_postal_code",
"installgeo_dma_code",
"installgeo_city",
"installgeo_area_code",
"installgeo_longitude",
"installgeo_latitude"
]
}
]
}Save/Update Columns Templates
Kochava stores a default selection/ordering of the columns for each type of report. That default is used by the UI AND when a report is submitted to the API with [ “default” ] as column_order segment. Once you have customized a report, you can save the set-up so that set-up will be the default for the next report you are submitting. The default is by API Key AND APP.
The call to the API is made for a API Key and the APP ID, not the GUID. It can only be made for 1 report type at the time.
Endpoint:
POST: https://reporting.api.kochava.com/v1.4/reportcolumns/update
Sample Post Data:
[
{
"api_key": "90EE38DE-3437-1A9F-8DCF-1EEBA217DE84",
"app_id": 1347,
"columns_selected": [
"kochava_click_id",
"partner_click_id",
"click_date_utc",
"click_date_adjusted",
"click_matched_impression",
"click_matched_install",
"click_network",
"click_network_name",
"click_tracker",
"click_tracker_name",
"click_campaign",
"click_campaign_name",
"click_site",
"click_creative",
"clickgeo_country_code",
"clickgeo_country_name",
"clickgeo_city",
"click_device_id",
"click_ip",
"click_device_ver",
"click_device_ua",
"click_original_request",
"click_identifiers",
"click_identifiers_idfa",
"click_identifiers_android_id",
"click_identifiers_android_id_md5",
"click_identifiers_android_id_sha1",
"click_identifiers_adid",
"click_identifiers_custom",
"click_identifiers_waid",
"click_identifiers_ip",
"click_identifiers_email_0",
"click_identifiers_email_1",
"click_duplicate"
],
"report_section": "click",
"report_type": "click",
"section_order": 1
},
{
"api_key": "90EE38DE-3437-1A9F-8DCF-1EEBA217DE84",
"app_id": 1347,
"columns_available": [
"impression_date_utc",
"impression_tracker_name",
"impression_campaign",
"impression_campaign_name",
"impression_site",
"impression_creative",
"impression_country_code",
"impression_original_request",
"impression_matched_install",
"impression_matched_click",
"impression_ip",
"impression_imp_id",
"impression_identifiers",
"impression_device_ver",
"impression_kochava_imp_id"
],
"columns_selected": [
"impression_date_adjusted",
"impression_network",
"impression_network_name",
"impression_tracker"
],
"report_section": "impression_detail",
"report_type": "click",
"section_order": 2
},
{
"api_key": "90EE38DE-3437-1A9F-8DCF-1EEBA217DE84",
"app_id": 1347,
"columns_available": [
"click_country_code",
"click_geolocation",
"clickgeo_continent_code",
"clickgeo_country_code3",
"clickgeo_region",
"clickgeo_postal_code",
"clickgeo_dma_code",
"clickgeo_area_code",
"clickgeo_longitude",
"clickgeo_latitude"
],
"report_section": "geo_detail",
"report_type": "click",
"section_order": 3
}
]
Sample Response Example:
{
"status": "OK"
}Filter Sets
Kochava’s Analytics provides the ability to save Audiences in order to be activated or exported. Audiences are sets of filters that describe the audience; filter sets do not preserve the time window they were created for which allows the filters to be reused in any context.
Endpoint:
POST: https://reporting.api.kochava.com/v1.4/filtersets
Sample Post Data:
{
"api_key": "00000000-0000-0000-0000-000000000000",
"app_guid": "kokochavabingodemo1347526e855c56f14",
}
Sample Response:
{
"status": 200,
"success": true,
"message": "success",
"filter_sets": [
{
"id": 4248,
"filter_name": "Custom View 381",
"user_id": 630748018,
"account_id": 5,
"platform": "",
"initial_app_id": 1347,
"initial_view": "eventdetail",
"created_dttm": "2017-07-14 22:23:43",
"last_updated_dttm": "2017-07-14 22:23:43",
"filters": {
"filters": [
{
"dimension": "app_name",
"modifier": "in",
"logic": "and",
"values": [
"Kochava Bingo Demo"
]
}
],
"currency_from": "usd",
"currency_to": "USD"
}
},
{
"id": 4762,
"filter_name": "Custom Filters 261",
"user_id": 630748018,
"account_id": 5,
"platform": "",
"initial_app_id": 1347,
"initial_view": "",
"created_dttm": "2017-08-17 17:33:45",
"last_updated_dttm": "2017-08-17 17:33:45",
"filters": {
"filters": [
{
"dimension": "app_name",
"modifier": "in",
"logic": "and",
"values": [
"Kochava Bingo Demo"
]
},
{
"dimension": "tv_brand_name",
"modifier": "in",
"logic": "and",
"values": [
"Liberty Mutual"
]
}
]
}
},
{
"id": 10471,
"filter_name": "US Users",
"user_id": 630748018,
"account_id": 5,
"platform": "",
"initial_app_id": 1347,
"initial_view": "",
"created_dttm": "2018-10-23 18:38:27",
"last_updated_dttm": "2018-10-23 18:38:27",
"filters": {
"filters": [
{
"dimension": "app_name",
"modifier": "in",
"logic": "and",
"values": [
"Kochava Bingo Demo"
]
},
{
"dimension": "geo_country",
"modifier": "in",
"logic": "and",
"values": [
"US"
]
}
]
}
}
]
}NOTE: Get Filter Sets for the user/app combination. The ID’s can be used in Audience Exports and Audience Activations.
