1. Help Center
  2. Custom API Integrations

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

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.

If you'd like us to help you get set up with Transistor in Databox, please fill out this request form or book a call with one of our product experts: 

- If you are a paying customer, book a call here

- Other Databox users, book a call here

To access Custom API Integrations, you need to be on the Professional or higher plans. If you're interested in trying them out, you can request a trial by following these steps.

Specification

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

Status Beta
Authorization Type Basic
Account Permissions Required Any
API Versions Supported Any (v1 as of November 2023)
API Scopes Required N/A
Supported Methods GET
Supported Endpoints All
Timezone UTC
Supported Pagination Page
Rate Limits N/A
API Documentation https://developers.transistor.fm/#intro
Status Page https://status.transistor.fm/
Change Log https://transistor.fm/changelog/

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

Endpoint

/v1/analytics/:id

Replace :id with the ID of the podcast you want to report on. You can find this information in the /v1/shows endpoint.

Parameters start_date = 1 year ago
end_date = Today
JSONata
data.attributes.downloads.{
  "value": downloads,
  "date": date
}
Metric Definition

Data Aggregation > Data type  > SUM of All values

disabled Handling multiple values stored for identical Date/Time

Downloads by Episode

Endpoint

/v1/analytics/:id/episodes

Replace :id with the ID of the podcast you want to report on. You can find this information in the /v1/shows endpoint.

Parameters

start_date = 30 days ago
end_date = Today

Please note that this endpoint can return a lot of data. To prevent timeout errors, limit the Date Range to no more than a few months.

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

Data Aggregation > Data type  > SUM of All values

disabled Handling multiple values stored for identical Date/Time

Episodes

Endpoint

/v1/episodes

Parameters

show_id = the ID of the podcast you want to report on.

You can find this information in the /v1/shows endpoint.

pagination[per] = 100

Pagination method

Page

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

Data Aggregation > Data type  > SUM of All values

Total Subscribers

Endpoint

/v1/subscribers

This metric should not be set up for very popular podcasts (10k+ subscribers)

Parameters

show_id = the ID of the podcast you want to report on.

You can find this information in the /v1/shows endpoint.

pagination[per] = 100

Pagination method

Page

JSONata
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.