Guide: Using Transistor with Databox (Custom API Integration)

Discover how to integrate Transistor's podcast hosting and analytics into Databox using the Metric Builder for Custom API Integrations. Get insights into visualizing podcast analytics data seamlessly and efficiently.

IN THIS ARTICLE

• Overview
• Specification
• Usage
  • How to connect Transistor to Databox
  • How to visualize data from Transistor
  • Examples
• Observations

Overview

Transistor provides podcast hosting and analytics for thousands of organizations, brands, and creatives around the world.

The Transistor integration lets you see analytics data from one or several podcasts in your Transistor account. To make this data work with Databox, you'll use the Metric Builder. Find out more about using the Metric Builder for Custom API Integrations here.

Specification

The table below shows how the integration is implemented and provides additional helpful resources and information.

Usage

How to connect Transistor to Databox

Go to Data Manager > + New connection. Type Transistor in the search bar and click on the Connect button. Next, click on the green Connect now button.

This will open the Activate Transistor window, where you will be prompted to enter your API Key to activate the connection. API keys can be viewed and reset in the Account Area of your Transistor Dashboard.

How to visualize data from Transistor

First you'll need to create Custom Metrics using the Metric Builder. To do that, reference the API documentation for specifics on what parameters should be used.

1. Navigate to Metrics > Custom Metrics to access the Metric Builder.
2. Click the green + New Custom Metric button and select your Transistor account in Data Source drop-down list.
3. Find the relevant endpoint in the API documentation that can be used to return the data you need. The base URL is already predefined, you only need to input the missing part of the chosen endpoint's URL.
4. Add any necessary parameters. Parameters sometimes are required to specify the podcast to pull data for, or indicate the number of records to return. They are defined as key-value pairs. For date parameters, click on the calendar icon to enable dynamic date options. Multiple parameters can be added by clicking on the + control.
5. Add any necessary headers. Databox will automatically add a header with the API key provided when connecting the Data Source. 
6. If the endpoint supports pagination, you should select the appropriate method using the Pagination method dropdown. This ensures more data will be pulled on every sync.
7. Once you have all necessary fields populated, click on the green Continue button. You will be directed to the Select value step.
8. In the Select value step, select a property in the response that includes the metric value you'd like to use for the metric. A metric value must always be numeric.
9. Once you have selected the value, click on the green Continue button.
10. The Segment by dimension step is optional. This step will be taken into account only when you are trying to create a dimensional metric.
    1. If you'd like to segment your metric by multiple dimensions, choose one to complete during this set up, then start over and select a different dimension until each dimensional metric is created.

    2. To skip this step, select None. 

11. The Select date step is optional as well. You can choose between:
    1. Use current time of storing data (Dynamic): select this option if you want to associate the values with the current time.
    2. Use a field from response (optional): select this option if there is a date associated with each value.
12. In the Preview & Customize step, you can see the JSONata expression that has been created based on the chosen options.
    

    1. Pro tip: You can customize the JSONata expression in the right-hand panel, if you need further customization. More information about JSONata can be found here

13. To continue, click on the Preview data button to apply the JSONata expression to the response received from the API. You should see a table with dates, values and dimensions (if selected).
14. After you have previewed your data and verified it is working as expected, click on the green Continue button to proceed to the last step of the metric setup.
15. In the Describe metric step, populate the following:
    1. Name your metric: a name for the metric.
    2. Data aggregation: this determines how the data is handled. It impacts the way data is grouped and displayed for longer Date Ranges. Learn more here.
    3. Favorable trend: this affects how comparison values (i.e. deltas) are calculated and displayed on our visualizations. Choose UP if higher values are more disabled, and DOWN otherwise.
16. Once you completed the Describe metric step, click the green Continue button to save the metric in your account.

Examples

Below is a compiled list of suggested metrics that you can create from this integration.

Downloads

data.attributes.downloads.{
    "value": downloads,
    "date": date
}

Downloads by Episode

data.attributes.episodes.downloads.{
  "value": downloads,
  "date": $join([$substring(date, -4), $substring(date, 0, 2), $substring(date, -7, 2)],"-"),
  "dimension": %.title
}

Episodes

data.{
    "value": 1,
    "date": attributes.published_at
}

Total Subscribers

data.{
    "value": 1
}

Observations

Here are a few points to keep in mind about this integration.

Historical Data: you will be limited to the data returned by the metrics over time. So, in order to visualize data for a specific period (e.g. Last Year), make sure to include that range whenever preparing the API request.

Pagination: the pagination limit is set to 100 pages. Make sure to increase the number of records per page by adding the appropriate parameter to the request, to maximize the amount of data to be synced.