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

API v1.4 – Querying API

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.4 has been divided into the following sections:

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

 

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

CAUTION: If a request is sent that is a duplicate of another report currently queued or running, no token will be returned. The response will be returned with a status of “queued” or “running” for the duplicate report that was requested.

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

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.

 

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"
}

 
 

Last Modified: Nov 11, 2022 at 12:47 pm