Guide: Using Captivate with Databox (Custom API Integration)

Leverage Captivate's API within Databox using the Metric Builder for Custom API Integrations, to gain insights into your podcast's audience engagement and performance metrics.

IN THIS ARTICLE


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.

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

You can also 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 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/articles/3045914-captivate-feature-releases-changelog

Usage

How to connect Captivate to Databox

Go to Data Manager > + 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 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 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

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