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

## Overview

Captivate.fm is a podcast hosting platform designed to help creators manage and monetize their podcasts.

The Captivate integration allows you to visualize your podcast's analytics in your Databox account. The data is brought in as Custom Metrics, created using 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 | Current (as of November 2023) |
| API Scopes Required | N/A |
| Supported Methods | GET, POST |
| Supported Endpoints | /insights (Analytics) |
| Timezone | Podcast's timezone |
| Supported Pagination | N/A |
| Rate Limits | N/A |
| API Documentation | https://docs.captivate.fm/ |
| Status Page | https://status.captivate.fm/ |
| Change Log | https://help.captivate.fm/en/article/3045914-captivate-feature-releases-changelog |


## Usage

### How to connect Captivate to Databox

Go to **[Data Manager](https://app.databox.com/data-manager/available) > + New connection.** Type **Captivate** in the search bar and click on the **Connect**button. Next, click on the green **Connect now** button.

This will open the **Activate Captivate** window, where you will be prompted to enter your User ID and API Key to activate the connection. API keys can be found in the **API Key** section under **My Account** in your Captivate account.

Once your credentials are verified by our system, a new prompt will appear, allowing you to choose the podcast for which you wish to visualize analytics data.

### How to visualize data from Captivate

The integrations already comes with a number of prebuilt Custom Metrics, but it is possible to expand on that number by creating more metrics yourself. To do that, reference the [API documentation](https://docs.captivate.fm/) 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 the Captivate podcast 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 Date Range to pull data for, or include/ exclude data based on a criteria. 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 the request **body** in JSON format, if doing a POST request.
6. Add any necessary **headers**. Databox will automatically add a header with the Bearer token to authenticate the request.
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 list of suggested additional metrics that you can create from this integration.

**Downloads by Country**

Unfortunately the API only provides aggregated totals for the whole period, instead of granular (daily) breakdowns. Therefore, in order to obtain granular data that can be later on aggregated on our visualizations based on the Date Range selection, it is necessary to sync only one day of data at a time. For that, we set up the request as outlined below.

| 
| Endpoint | */range* |
| Body | `{     "start": "{{-1d}}",     "end": "{{0d}}",     "interval": "1d",     "timezone": "{timezone}",     "countryCode": null,     "types": ["byLocation"] }`   *{{-1d}}* and *{{0d}}*  are dynamic placeholders for yesterday's and today's date.  *{timezone}* is a placeholder for the timezone of the podcast and is populated by our system. |
| JSONata | `byLocation.byCountry.{     "value": total,     "date": $$.totalOverTime.timestamp,     "dimension": country }` |
| Metric Definition | *Data Aggregation > Data type  > SUM of All values*  ***disabled** Handling multiple values stored for identical Date/Time* |


**Downloads by Episode**

This metric is already available as a Custom Metric, however the API only provides the ID of the episode in the response. To see the episode name instead, you'll need to rename the IDs in the JSONata expression.

| 
| Endpoint | */range* |
| Body | `{     "start": "{{fdy}}",     "end": "{{0d}}",     "interval": "1d",     "timezone": "{timezone}",     "countryCode": null,     "types": ["byEpisode"] }`   *{{fdy}}* and *{{0d}}*  are dynamic placeholders for the first day of the year and today's date.  *{timezone}* is a placeholder for the timezone of the podcast and is populated by our system. |
| JSONata | `(   $episodes := [     {         "id_1": "name_1",         "id_2": "name_2"     }   ];    byEpisode.overTime.{     "value": total,     "date": timestamp,     "dimension": $lookup($episodes, %.episodeId) ? $lookup($episodes, %.episodeId) : %.episodeId   } )`   The $episodes variable holds the ids (id_1, id_2, ..) and names (name_1, name_2, ...) of the episodes. You can add as many episodes to the list as needed. |
| Metric Definition | *Data Aggregation > Data type  > SUM of All values*  ***disabled** Handling multiple values stored for identical Date/Time* |


## Observations

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

**Connection**: each connection can only pull data for a single podcast. If you would like to visualize data from multiple podcasts, repeat the connection process for each new podcast.

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