Log Endpoints v2 to v3 Migration Guide

The v2 Reporting API for accessing log-level data is going to become unavailable May 31st, 2016, and all customers will be required to change their code to use the new v3 of the API, as described below.

There are substantial differences between v2 and v3 of the Reporting API Log endpoints. It is a re-write from the ground up, designed to surface new data, improve performance, lower latency, and provide stronger adherence to industry standards and conventions for RESTful APIs.

Result Set Changes

Removed fields:

  • response_size is no longer returned
  • status_code - this can be found in the http response status_code

"Dot Fields (e.g. site.name) are no longer reported as a nested dictionary".

Result Before:

{
		     “status_code”: 200,
		     “data”: [
		           “site_id”: 12345,
		           “site”: {
			             “name”: “Atomic Dodgeball”
			       }
		     ]
	   }

Result After: (Note the “dot” in the field name ‘site.name’)

{
	          “data”: [
		            { 
                         "site_id" : 12345,
	                     "site.name" : "Atomic Dodgeball" 
                    }
	         ]
        }

Date Fields:

Dates are being returned in ISO-8601 format:

v2 date: "2016-01-06 00:05:08"
v3 date: "2016-01-06T00:05:08Z"

 

New Tables Available

Note that data for these three new tables is not as “fresh” as for other logs (Installs, Clicks, Events, etc.), and may run up to 6 hours behind real-time.

  • Opens
  • Impressions
  • Updates

 

URL Path Changes

As part of making the v3 API truly RESTful, all v3 Log endpoints now use the HTTP verb GET and no longer use verbs in the path (e.g. /find.json).  For this reason, the v2 actions are no longer applicable.

When using v3, your Advertiser ID must be part of the URL path as shown in the examples below in the field “advertiser_id”. To request your advertiser ID, use the following v2 call, (which will remain available after March):

http://api.mobileapptracking.com/v2/advertiser/find.json?api_key=yourapikey&fields=id

URL path actions that are supported under v2 but will not be supported under v3:

  • count
  • define

 

v2 Actions that are now accomplished via URL path differences:

The “find” action as used in v2 versus v3:

/v2/advertiser/stats//find.json
/v3/logs/advertisers//

The “findExportQueue” action as used in v2 versus v3:

/v2/advertiser/stats//findExportQueue.json
/v3/logs/advertisers//exports/

The “download” action as used in v2 versus v3:

/v2/export/download.jsonp?job_id=
/v3/logs/advertisers//exports/

Where “resource” is one of:

  • clicks
  • event_items (in v2 this was event/items)
  • events
  • impressions
  • installs
  • opens
  • postbacks
  • updates

 

Parameter Differences

start_date, end_date:

  • All v3 date(time)s are ISO-8601; e.g. 2016-01-28T15:15:05Z
  • Dates without times are considered as if 12:00 AM (first moment of the day). This is different from v2 which considers a timeless end_date to be the last second of the given day.
  • Dates without offsets (i.e. a timezone) default to the value provided for the timezone parameter. If the timezone parameter is not specified, the dates timezone defaults to the timezone set in your user account. If the timezone is not set in your user account, default is UTC.
  • Offsets are defined like so: 2016-01-28T15:15:05Z-8:00 for PST; must include time for offsets to work.
  • TUNE retains data indefinitely, but data is only made available via the API for the last 120 days. This is unchanged from v2 of the API, and applies to both export and non-export queries. Supplying a start_date older than 120 days will result in an error message.

 

timezone:

  • Renamed from the v2 "response_timezone" parameter. If no offsets are provided in the start_date and end_date, providing timezone controls the timezone for your request's start and end date. If the timezone parameter is not specified, the dates timezone defaults to the timezone set in your user account. If the timezone is not set in your user account, default is UTC.

 

response_format:

  • Renamed from the v2 "format" parameter used with find_export_queue.json calls. Either JSON or CSV can be selected; defaults to JSON.
    • For synchronous search calls to override default json response:
      • v2: use “find.csv?” in endpoint
      • v3: use “response_format=csv” in parameters
    • For asynchronous export calls when starting job in order to override default CSV format:
      • v2: use “format=json” in parameters
      • v3: Not yet supported, coming soon

 

group:

  • No longer supported.

 

page:

  • No longer supported.

 

limit:

  • Non Export Queries:
    • The limit parameter is now required for all non-export queries. If the limit parameter is left out, an error will be issued explaining that it is required.
    • The maximum allowed limit (for non-export requests) is 5000. If more than 5000 records are requested, an error message will be issued stating the limit.
    • If more than 5000 records are required, perform an export to retrieve all the records for the given call.
  • Export Queries
    • The limit parameter is now also required for export queries.
    • The maximum allowed limit for export queries is 2 million records each. If more than 2 million records are requested, an error message will be issued stating the limit.
    • If more than 2 million records are required, please make multiple requests with smaller time intervals to pull the data needed in "batches".

 

sort(v2) / sorts(v3):

    • Note that the parameter name has changed from singular, "sort", to plural, "sorts"
https://api.mobileapptracking.com/v2/advertiser/stats/installs/find?sorts=created+asc&fields=created,site&start_date=2016-01-06&end_date=2016-01-06&limit=1&api_key=yourapikey
  • The sort parameter in v2 took the form: sort[<field>] = [desc|asc]. For example: sort[site_id]=desc&sort[country_id]=asc
  • In v3, sort has the format: sorts=<field_name> [asc|desc]. For example: sorts=site_id asc,created desc
  • In v3, sorts are not supported for related entities (“dot fields”) in non-export calls. (e.g. site.name)
  • In v3, sorts are not supported for exports. If a sort parameter is supplied, an error message will be issued stating as such.

 

fields:

  • Fields 'profit' and 'currency_rate' are no longer available.
  • The following models are no longer available as related entities:
    • RecordsLogClicks referenced as stat_clicks
    • RecordsLogInstalls referenced as stat_installs
    • RecordsLogUpdates referenced as stat_updates
    • RecordsLogEvents referenced as stat_events
  • You can no longer specify entire related entity tables (for example, using fields=site,country). You must ask for the specific fields needed, for example:

Before: fields=created,site

Request:

https://api.mobileapptracking.com/v2/advertiser/stats/installs/find?fields=created,site&start_date=2016-01-06&end_date=2016-01-06&limit=1&api_key=yourapikey

Response:

{
  data: [
    {
      created: "2016-01-06 00:01:00", 
      site: {
        name: "TEST APP", 
        url: "", 
        mobile_app_type: "iOS", 
        ui_state: "", 
        google_analytics: "0", 
        enable_web_tracking: null, 
        conversion_redirect_url: null, 
        fb_app_id: "apperid", 
        appsfigure_name: null, 
        status: "active", 
        created: "2012-09-05 19:37:15", 
        modified: "2014-10-02 18:38:40", 
        id: 3626, 
        package_name: "20120905a", 
        logo_url: "", 
        logo_url_https: "", 
        ref_id: null, 
        store_app_id: null, 
        app_channel_id: 1, 
        conversion_key_id: 1708
      }
    }
  ]
}

After: fields=created,site.name,site.id

Request:

https://api.mobileapptracking.com/v3/logs/advertisers/877/installs?fields=created,site.name,site.id&start_date=2016-01-06T00:00:00Z&end_date=2016-01-06T23:59:59Z&limit=1&api_key=yourapikey

Response:

{
  data: [
    {
      site.id: 3626, 
      created: "2016-01-06T23:59:20Z", 
      site.name: "TEST APP"
    }
  ]
}

 

Examples:

v2:

https://api.mobileapptracking.com/v2/advertiser/stats/clicks/find.json

v3:

https://api.mobileapptracking.com/v3/logs/advertisers/877/clicks
  • "v3" marks this as requesting from the new API
  • "logs" is the service name and it goes right after /v3/ (replacing the less obvious "stats")
  • "877" -- the advertiser_id is part of the path.
  • "clicks" -- the log type is the same with the exception of event/items (v2) becoming event_items (v3)
  • No "find" or "count", no ".json"

Exporting one hour’s worth of clicks for one specific campaign and publisher:

https://api.mobileapptracking.com/v3/logs/advertisers/1234/exports/clicks?api_key=myapikeyabcdefghijk1234567&fields=created,site.name,campaign.name,campaign_url.name,publisher.name&sorts=created desc&filter=((campaign.name=’Atomic Dodgeball Campaign’) AND (publisher.name=’Mega Publisher’))&start_date=2015-01-31T23:00:00-800&end_date=2015-01-31T23:59:59Z&response_timezone=America/Los_Angeles

Downloading the export above:

https://api.mobileapptracking.com/v3/logs/advertisers/5490/exports/myexportkeyabcd1234?api_key=myapikeyabcdefghijk1234567

Synchronously requesting one hour’s worth of clicks for one specific campaign and publisher:

https://api.mobileapptracking.com/v3/logs/advertisers/1234/clicks?api_key=myapikeyabcdefghijk1234567&limit=100&fields=created,site.name,campaign.name,campaign_url.name,publisher.name&sorts=created desc&filter=((campaign.name=’Atomic Dodgeball Campaign’) AND (publisher.name=’Mega Publisher’))&start_date=2015-01-31T23:00:00-800&end_date=2015-01-31T23:59:59Z&response_timezone=America/Los_Angeles
Have a Question? Please contact support@tune.com for technical support.