Support Home > Analytics, Reports & API > API v1.3 – Querying API

API v1.3 – Querying API

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

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

The Free App Analytics 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.3 has been divided into the following sections:

The following document defines the structure and the methods for Querying the API.


Structure for Querying API

Parameter Description Format
api_key The api key linked to the app. 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

Post Endpoint:

https://reporting.api.kochava.com/v1.3/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

Post Endpoint:

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

 

Response Data:

{ 
    "status": "OK", 
    "valid_fields": [
            "country",
            "network",
            "campaign",  **  ONLY APPLY TO SUMMARY REPORT
            "site",
            "tracker",
            "creative"
    ]
}

Query Authorized Values for Timezones

Post Endpoint:

https://reporting.api.kochava.com/v1.3/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 returns 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…).

 

Post Endpoint:

https://reporting.api.kochava.com/v1.3/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 part 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 returns 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

 

Post Endpoint:

https://reporting.api.kochava.com/v1.3/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

Free App Analytics 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.

 

Post Endpoint:

https://reporting.api.kochava.com/v1.3/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"
}

 
 

Last Modified: May 23, 2022 at 12:57 pm