Overview

To ensure a smooth transition from TUNE to Branch, an Aggregate API was built specifically to minimize the number of changes you will need to make when pulling aggregate data. This is similar to TUNE’s Actuals API. 

 

So:

TUNE Actuals API == Branch Aggregate API

 

Outlined below is our recommended transition plan which will help you understand both the upcoming process as well as the similarities and differences between the TUNE Actuals API and the Branch Aggregate API.

 

Phase 1: Dual API Access

Within the next few weeks you will be given access to the Branch Dashboard. When you receive the login email, you can now query for your Actuals data from the Branch Aggregate API. This new API allows you to query data directly from the Branch system, but using the familiar TUNE field names.

 

In order to access the Branch Aggregate API, simply add the query parameter &branch_redirect=3 to all of your original TUNE Actuals API calls.  Doing so ensures that you are querying Branch for your data and not TUNE.

 

During this stage, we highly recommend you follow the instructions we provide to test out the Branch Aggregate API. You should examine the results from Branch, test pushing the data through your ETL processes, and ensure that all of your systems dependent on this data function as intended.

 

It is essential that you confirm run test calls using the new Branch Aggregate API during this phase. In the next phase you will no longer be able to query data from TUNE directly as you do now. 

 

Phase 2: Branch Aggregate API only

After your account has been migrated to the Branch infrastructure, there will no longer be any NEW data in TUNE's systems. All new requests to TUNE are immediately mirrored to Branch who will handle the requests and return a response. Once you receive notification of your final account migration, you must rely on the Branch Aggregate API to query any data moving forward.

 

Asynchronous Export Calls


Synchronous Find Calls

 

NOTE: For a limited time (up until late April 2019), you will still be able to query historical data (i.e. data from before the cut over to Branch) directly from TUNE. To access your historical actuals data stored in TUNE, you will need to change the &branch_redirect query parameter's value from 3 (hit Branch for data) to 0 (hit TUNE for data); &branch_redirect=0.

 

After that date, the TUNE infrastructure will be shut off and inaccessible.

 

Phase 3: TUNE Actuals API Inaccessible 

In April 2019, all TUNE infrastructure will be shut off and historical data will be permanently deleted. At this time, the TUNE Actuals API will no longer function, and custom requests to pull data cannot be honored.

 

Your Action Items

You can start accessing the . It will involve simply adding an additional query parameter - &branch_redirect - to your existing requests to the TUNE Actuals API.

  • Phase 1 - Query data via both the TUNE Actuals and Branch Aggregate APIs. Compare the data.  Ensure that data returned from the Branch Aggregate API works with your ETL jobs.

  • Phase 2 - Make requests to the Branch Aggregate API for current data following the instructions outlined above.

  • Phase 3 - Specify a timezone in every request. Starting in Phase 3, if you do not specify a timezone when making the request, we will use UTC. More information below.

 

Small differences

Different behavior when no timezone is specified

Branch timezone waterfall:

  • If the start_date has a timezone, this will be used

  • if response_timezone is specified, this will be used

  • If an organization-level (advertiser-level) timezone is specified, this will be used

  • UTC will be used


Unlimited results returned

Branch will not return unlimited results for the Aggregate API. Branch returns up to 5,000 results per datasource for the find (synchronous) endpoint, and up to 10,000 results per datasource for the export (asynchronous) endpoint. 


Here, datasource is defined by the Branch datasources. So if you make a request for ad_impressions and ad_clicks, you can get back up to 20,000 results from the export (asynchronous) endpoint.


Branch splits out event into four datasources: commerce, content, user lifecycle, and custom. So when requesting event, you can get back up to 40,000 results from the export endpoint.


Filtering on ad_clicks or installs

Branch does not allow filtering based on ad_clicks, installs, etc. So you cannot filter for e.g. “show ad_clicks where installs > 0”.


Time granularities

Branch supports aggregating by day, week, and month aggregations. Start and end dates can be specified down to the hour, but not down to the minute/second.


Pagination

Branch does not currently have pagination. For large data sets, use the asynchronous export endpoint.

 

Discontinued fields

Some fields seem to have very limited value to our customers and as such have been discontinued. Please work with your CSM or our Support team if you have questions about any custom use cases and whether the fields you regularly use will be supported.