# Guide: Using Transistor with Databox (Custom API Integration)

## 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](/master-overview-custom-api-integrations).

## 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](https://app.databox.com/data-manager/available) > + 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](https://dashboard.transistor.fm/account) 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](https://developers.transistor.fm/#intro) for specifics on what parameters should be used.

1. Navigate to **Metrics > [Custom Metrics](https://app.databox.com/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](https://docs.jsonata.org/overview)
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](https://developers.databox.com/metric-definition/#aggregation-functions).
  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.