NAV Navigation
shell ruby javascript

Chartable API

Welcome to the Chartable API. You can use our API to access data in your dashboard. We use deterministic URLs that use standard HTTP verbs and returns JSON-encoded data.

The Chartable API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

Chartable uses API access keys for authentication. This key must be passed as a bearer token in an HTTP Authorization header.

You can generate a token by signing in to Chartable, clicking the “Integrations” tab, then clicking the “Chartable API” option.

Chartable expects that the access key is included in all API requests to the server in a header that looks like the following:

Authorization: Bearer <your_access_key>

Podcasts

List Podcasts

require "net/http"

uri = URI("https://chartable.com/api/v1/podcasts")
params = {page: 1, page_size: 10}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/podcasts" \
  -H "Authorization: Bearer <your_access_key>" \
  -d page=1 \
  -d page_size=10
fetch("https://chartable.com/api/v1/podcasts?page=1&page_size=10", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response

{
  "metadata": {
    "total": 20,
    "page": 1,
    "page_size": 5,
    "pages": 4,
  },
  "data": [
    {
      "id": "68f7c96c-9ee2-47a1-8ccd-21efbb2ffe8a",
      "description":"Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      "feed_url": "https://feeds.simplecast.com/ZDSsrr9_",
      "image_url":"https://example.com/image.png",
      "language": "en-us",
      "slug":"chartable-radio",
      "summary": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      "title": "Chartable Radio",
      "website_url": "https://example.com"
    }
  ]
}

This endpoint lists all podcasts added to your team dashboard.

HTTP Request

GET https://chartable.com/api/v1/podcasts

Request Parameters

Parameter Type Default Description
page Integer 1 Which page of podcasts to return (if you have more than 10).
page_size Integer 10 How many podcasts to return. This cannot be larger than the default value.
sort_by String “created_at” The attribute used to sort the podcasts. Must be one of: created_at, name.
sort_desc Boolean true Set to false to sort in ascending order.

Response Details

Name Type Description
id String The unique ID for this podcast
description String The podcast’s description
feed_url String The RSS feed URL
image_url String The podcast’s logo
slug String The podcast’s slug
summary String The podcast’s summary
title String The podcast’s title
statistics Object The podcast’s statistics
statistics.downloads_30d Integer The number of times the podcast has been downloaded over the past 30 days.
statistics.downloads_30d_growth Float How much have the downloads grown over the past 30 days.

Podcast Charts

require "net/http"

uri = URI("https://chartable.com/api/v1/podcasts/:id/charts")
params = {limit: 5}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/podcasts/:id/charts" \
  -H "Authorization: Bearer <your_access_key>" \
  -d limit=5
fetch("https://chartable.com/api/v1/podcasts/:id/charts?limit=5", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response

{
  "history":[
    {
      "charts":[
        {
          "podcast_id": "4a0ffbf7-1e97-489c-92f2-003de1dd8ec0",
          "name": "Chartable : Podcasts : Global : All Podcasts : Reach",
          "url": "https://chartable.com/charts/chartable/podcast-global-all-podcasts-reach",
          "most_recent": true,
          "current_timestamp": "2022-02-01T12:00:00.000Z",
          "current_rank": 5,
          "first_timestamp": "2022-01-01T12:00:00.000Z",
          "first_rank": 100,
          "peak_timestamp": "2022-01-15T12:00:00.000Z",
          "peak_rank": 3,
          "delta":{
            "value": 10,
            "direction": "up"
          }
        }
      ]
    }
  ]
}

This endpoint returns historical chart positions for a single podcast.

HTTP Request

GET https://chartable.com/api/v1/podcasts/:id/charts

Request Parameters

Parameter Type Default Description
limit Integer NULL The number of positions to return for each chart. Omit to return all chart positions.

Response Details

Name Type Description
podcast_id String The podcast’s unqiue ID.
name String The chart’s name.
url String The url of the chart on chartable.com.
most_recent Boolean Is this the most recent chart?
current_rank Integer The podcast’s current position on the chart.
current_timestamp DateTime When the current rank was recorded.
first_rank Integer The podcast’s first position on the chart.
first_timestamp DateTime When the first rank was recorded.
peak_rank Integer The podcast’s top position on the chart.
peak_timestamp DateTime When the top rank was recorded.
delta Object The change from the previous chart.
delta.direction String Did this podcast move up, down, or stay the same?
delta.value Integer How far did the podcast move?

Podcast Consumption

require "net/http"

uri = URI("https://chartable.com/api/v1/consumption")
params = {scope: "podcasts", ids: "54d7842b-2096-4a35-9af9-6cb10c8e78df,5fa49415-3962-429e-86dc-73ee7c1c9d76"}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "http://localhost:5555/api/v1/consumption" \
  -H "Authorization: Bearer ch_eyJ0ZWFtX2lkIjoiRTE1OTQiLCJjcmVhdGVkX2F0IjoiMjAyMi0wMS0yMSAxNTowNzozOCBVVEMifQ.cxAUedxY0lYfAjnvjUC-QKbwCM_kXZ9CGta7rPXUmrM" \
  -d scope=podcasts \
  -d ids=54d7842b-2096-4a35-9af9-6cb10c8e78df,5fa49415-3962-429e-86dc-73ee7c1c9d76
fetch("https://chartable.com/api/v1/consumption?scope=podcasts&ids=54d7842b-2096-4a35-9af9-6cb10c8e78df,5fa49415-3962-429e-86dc-73ee7c1c9d76", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "metadata": {
    "54d7842b-2096-4a35-9af9-6cb10c8e78df": {
      "feed_url": "https://example.com/podcast.rss",
      "id": "54d7842b-2096-4a35-9af9-6cb10c8e78df",
      "image_url": "https://example.com/podcast.png",
      "slug": "my-podcast",
      "title": "My Podcast"
    },
    "5fa49415-3962-429e-86dc-73ee7c1c9d76": {
      "feed_url": "https://example.com/podcast2.rss",
      "id": "5fa49415-3962-429e-86dc-73ee7c1c9d76",
      "image_url": "https://example.com/podcast2.png",
      "slug": "my-podcast-2",
      "title": "My Podcast 2"
    }
  },
  "data": {
    "54d7842b-2096-4a35-9af9-6cb10c8e78df": [{
      "Spotify": [{
        "percentage": 0.0,
        "consumption": 0.98
      },{
        "percentage": 0.1,
        "consumption": 0.95
      }]
    },{
      "Apple": [{
        "percentage": 0.0,
        "consumption": 0.90
      },{
        "percentage": 0.1,
        "consumption": 0.85
      }]
    }],
    "5fa49415-3962-429e-86dc-73ee7c1c9d76": [{
      "Spotify": [{
        "percentage": 0.0,
        "consumption": 0.95
      },{
        "percentage": 0.1,
        "consumption": 0.90
      }]
    },{
      "Apple": [{
        "percentage": 0.0,
        "consumption": 0.93
      },{
        "percentage": 0.1,
        "consumption": 0.87
      }]
    }]
  }
}

This endpoint returns consumption data for up to 5 podcasts.

HTTP Request

GET https://chartable.com/api/v1/consumption

Request Parameters

Parameter Type Required Description
scope String “” The level of data to return. Must be one of: podcasts, episodes. This is required.
ids String “” Comma-delimited list of podcast IDs. This is required.

Response Structure

Name Type Description
metadata Object Information about each podcast.
data Object The consumption data organized by podcast and provider.
data.podcast Array Each row is a provider containing consumption data.
data.provider Array Each row is an object where percentage represents 1/100th of the duration of the podcast, and the consumption data for that timeframe.

Podcast Demographics

require "net/http"

uri = URI("https://chartable.com/api/v1/demographics")
params = {scope: "podcasts", ids: "54d7842b-2096-4a35-9af9-6cb10c8e78df,5fa49415-3962-429e-86dc-73ee7c1c9d76"}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "http://localhost:5555/api/v1/demographics" \
  -H "Authorization: Bearer ch_eyJ0ZWFtX2lkIjoiRTE1OTQiLCJjcmVhdGVkX2F0IjoiMjAyMi0wMS0yMSAxNTowNzozOCBVVEMifQ.cxAUedxY0lYfAjnvjUC-QKbwCM_kXZ9CGta7rPXUmrM" \
  -d scope=podcasts \
  -d ids=54d7842b-2096-4a35-9af9-6cb10c8e78df,5fa49415-3962-429e-86dc-73ee7c1c9d76
fetch("https://chartable.com/api/v1/demographics?scope=podcasts&ids=54d7842b-2096-4a35-9af9-6cb10c8e78df,5fa49415-3962-429e-86dc-73ee7c1c9d76", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "country_demographics": {
    "Trackable": [
      ["Country", "Podcast 1", "Podcast 2"],
      ["US", 1000, 500]
      ["GB", 900, 400]
    ],
    "Spotify": [
      ["Country", "Podcast 1", "Podcast 2"],
      ["US", 1000, 500]
      ["GB", 900, 400]
    ]
  },
  "gender_demographics": {
    "Spotify": [
      ["Gender", "Podcast 1", "Podcast 2"],
      ["Male", 1000, 500],
      ["Female", 900, 400],
      ["Not Binary", 800, 300]
      ["Not Specified", 700, 200]
    ]
  },
  "age_demographics": {
    "Spotify": [
      ["0-17", 10000],
      ["18-22", 9000],
      ["23-27", 8000],
      ["28-34", 7000],
      ["35-44", 6000],
      ["45-59", 5000],
      ["60-150", 4000],
      ["unknown", 3000]
    ]
  },
  "player_demographics": {
    "Trackable": [
      ["Player", "Podcast 1", "Podcast 2"],
      ["Apple Podcasts", 10000, 1000],
      ["Spotify", 9000, 900],
      ["Pocket Casts", 8000, 800],
      ["Overcast", 7000, 700],
      ["Stitcher", 6000, 600],
      ["PodcastAddict", 5000, 500],
      ["CastBox", 4000, 400],
      ["iHeartRadio", 3000, 300],
      ["iTunes", 2000, 200],
      ["TuneIn", 1000, 100]
    ]
  }
}

This endpoint returns demographics for up to 5 podcasts.

HTTP Request

GET https://chartable.com/api/v1/demoraphics

Request Parameters

Parameter Type Required Description
scope String “” The level of data to return. Must be one of: podcasts, episodes, team.
ids String “” Comma-delimited list of podcast IDs. This is required.

Response Structure

Name Type Description
country_demographics Array The number of downloads organized by country. See Country Codes for a list of values.
gender_demographics Array The number of downloads organized by gender.
age_demographics Array The number of downloads organized by age.
player_demographics Array The number of downloads organized by player.

Podcast Downloads

require "net/http"

uri = URI("https://chartable.com/api/v1/downloads")
params = {
  scope: "podcasts",
  ids: "f99e8b72-ddb6-4596-9165-57295917647d,371a7032-7e71-4bb1-9b5c-ad9bd1d11d33",
  start_date: "2022-01-01",
  end_date: "2022-01-03",
  aggregation: "daily"
}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/downloads" \
  -H "Authorization: Bearer <your_access_key>" \
  -d scope=podcasts
  -d ids=f99e8b72-ddb6-4596-9165-57295917647d,371a7032-7e71-4bb1-9b5c-ad9bd1d11d33 \
  -d start_date=2022-01-01 \
  -d end_date=2022-01-03 \
  -d aggregation=daily
fetch("https://chartable.com/api/v1/downloads?scope=podcasts&ids=f99e8b72-ddb6-4596-9165-57295917647d,371a7032-7e71-4bb1-9b5c-ad9bd1d11d33&start_date=2022-01-01&end_date=2022-01-03&aggregation=daily", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response

{
  "metadata": {
    "54d7842b-2096-4a35-9af9-6cb10c8e78df": {
      "feed_url": "https://example.com/podcast.rss",
      "id": "54d7842b-2096-4a35-9af9-6cb10c8e78df",
      "image_url": "https://example.com/podcast.png",
      "slug": "my-podcast",
      "title": "My Podcast"
    },
    "5fa49415-3962-429e-86dc-73ee7c1c9d76": {
      "feed_url": "https://example.com/podcast2.rss",
      "id": "5fa49415-3962-429e-86dc-73ee7c1c9d76",
      "image_url": "https://example.com/podcast2.png",
      "slug": "my-podcast-2",
      "title": "My Podcast 2"
    }
  },
  "data": [{
    "date": "2022-01-01",
    "54d7842b-2096-4a35-9af9-6cb10c8e78df": 1000,
    "5fa49415-3962-429e-86dc-73ee7c1c9d76": 2000
  },{
    "date": "2022-01-02",
    "54d7842b-2096-4a35-9af9-6cb10c8e78df": 500,
    "5fa49415-3962-429e-86dc-73ee7c1c9d76": 1500
  }]
}

This endpoint returns the number of total downloads for up to 5 podcasts.

HTTP Request

GET https://chartable.com/api/v1/downloads

Request Parameters

Parameter Type Default Description
scope String “” The level of data to return. Must be one of: podcasts, episodes.
ids String “” Comma-delimited list of podcast IDs. This is required.
start_date String NULL Return downloads after or on this date.
end_date String NULL Return downloads before or on this date.
aggregation String “daily” How should downloads be aggregated? Must be one of: daily, weekly, monthly.

Response Structure

Name Type Description
metadata Object Information about each podcast.
data Array The downloads organized by aggregated date.

Podcast Episodes

require "net/http"

uri = URI("https://chartable.com/api/v1/podcasts/:id/episodes")
params = {page: 1, page_size: 10}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/podcasts/:id/episodes" \
  -H "Authorization: Bearer <your_access_key>" \
  -d page=1 \
  -d page_size=10
fetch("https://chartable.com/api/v1/podcasts/:id/episodes?page=1&page_size=10", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "metadata": {
    "total": 100,
    "page": 1,
    "page_size": 20,
    "pages": 5
  },
  "data": [
    {
      "id": "fd4fd0c1-7569-49f4-b691-d5c916e4f8e4",
      "url": "https://example.com/episode.mp3",
      "title": "Lorem Ipsum",
      "slug": "lorem-ipsum",
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin at porta enim, ac placerat libero. Integer aliquet egestas turpis eu accumsan. Vestibulum finibus purus vitae est mattis iaculis.",
      "published_at": "2022-01-01T12:00:00.000Z",
      "is_active": true,
      "image_url": "https://example.com/image.png",
      "length_in_seconds": 900
    }
  ]
}

This endpoint lists episodes for a single podcast.

HTTP Request

GET https://chartable.com/api/v1/podcasts/:id/episodes

Request Parameters

Parameter Type Default Description
page Integer 1 Which page of SmartLinks to return (if you have more than 50).
page_size Integer 50 How many SmartLinks to return. This cannot be larger than the default value.
start_date DateTime NULL If set, only returns data for events that happened on or after this date.
end_date DateTime NULL If set, only returns data for events that happened on or before this date.
archived Boolean false Set to true to get archived SmartLinks.
sort_by String “created_at” The attribute used to sort the SmartLinks.
sort_desc Boolean true Set to false to sort in ascending order.

Response Structure

Name Type Description
id String The unique ID for this episode
title String The episode’s title
slug String The episode’s slug
description String The episode’s description
published_at DateTime The date and time this episode was published
is_active Boolean Is this episode currently available to download?
image_url String The image for this episode
length_in_seconds Integer The duration of the episode

Podcast Household Demographics

require "net/http"

uri = URI("https://chartable.com/api/v1/pocasts/:id/household_demographics")
params = {segment: "age"}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "http://localhost:5555/api/v1/pocasts/:id/household_demographics" \
  -H "Authorization: Bearer ch_eyJ0ZWFtX2lkIjoiRTE1OTQiLCJjcmVhdGVkX2F0IjoiMjAyMi0wMS0yMSAxNTowNzozOCBVVEMifQ.cxAUedxY0lYfAjnvjUC-QKbwCM_kXZ9CGta7rPXUmrM" \
  -d segment=age
fetch("https://chartable.com/api/v1/pocasts/:id/household_demographics?segment=age", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "metadata": {
    "measurement_date": "2022-01-01"
  },
  "data": [
    {
      "<segment>": "<description>",
      "reach_percentage": 6.86,
      "benchmark_reach_percentage": 8.26,
      "reach_percentage_against_benchmark": -1.4
    }
  ]
}

This endpoint returns household demographics for a single podcast.

HTTP Request

GET https://chartable.com/api/v1/pocasts/:id/household_demoraphics

Request Parameters

Parameter Type Required Description
segment String Yes Must be one of: age, gender, education, household_income.

Response Structure

Name Type Description
metadata Object Information about the response.
metadata.measurement_date Date The date the demographics were collected.
data Object Demographic information.
data.<segment> String A description of this segment
data.reach_percentage Float Reach
data.benchmark_reach_percentage Float Benchmark Reach
data.reach_percentage_against_benchmark Float Reach Against Benchmark

Podcast Plays

require "net/http"

uri = URI("https://chartable.com/api/v1/plays")
params = {
  scope: "podcasts",
  ids: "f99e8b72-ddb6-4596-9165-57295917647d,371a7032-7e71-4bb1-9b5c-ad9bd1d11d33",
  start_date: "2022-01-01",
  end_date: "2022-01-03",
  aggregation: "daily"
}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/plays" \
  -H "Authorization: Bearer <your_access_key>" \
  -d scope=podcasts
  -d ids=f99e8b72-ddb6-4596-9165-57295917647d,371a7032-7e71-4bb1-9b5c-ad9bd1d11d33 \
  -d start_date=2022-01-01 \
  -d end_date=2022-01-03 \
  -d aggregation=daily
fetch("https://chartable.com/api/v1/plays?scope=podcasts&ids=f99e8b72-ddb6-4596-9165-57295917647d,371a7032-7e71-4bb1-9b5c-ad9bd1d11d33&start_date=2022-01-01&end_date=2022-01-03&aggregation=daily", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response

{
  "metadata": {
    "f99e8b72-ddb6-4596-9165-57295917647d": {
      "feed_url": "https://example.com/podcast.rss",
      "id": "f99e8b72-ddb6-4596-9165-57295917647d",
      "image_url": "https://example.com/podcast.png",
      "slug": "my-podcast",
      "title": "My Podcast"
    },
    "371a7032-7e71-4bb1-9b5c-ad9bd1d11d33": {
      "feed_url": "https://example.com/podcast2.rss",
      "id": "371a7032-7e71-4bb1-9b5c-ad9bd1d11d33",
      "image_url": "https://example.com/podcast2.png",
      "slug": "my-podcast-2",
      "title": "My Podcast 2"
    }
  },
  "data": {
    "f99e8b72-ddb6-4596-9165-57295917647d": {
      "Spotify":[{
          "date":" 2021-01-01",
          "count": 500.0
        },{
          "date": "2022-01-02",
          "count": 400.0
        },{
          "date": "2022-01-03",
          "count": 300.0
        }
      ]
    },
    "371a7032-7e71-4bb1-9b5c-ad9bd1d11d33": {
      "Apple":[{
          "date":" 2021-01-01",
          "count": 300.0
        },{
          "date": "2022-01-02",
          "count": 200.0
        },{
          "date": "2022-01-03",
          "count": 100.0
        }
      ]
    }
  }
}

This endpoint returns the number of total plays for up to 5 podcasts.

HTTP Request

GET https://chartable.com/api/v1/plays

Request Parameters

Parameter Type Default Description
scope String “” The level of data to return. Must be one of: podcasts, episodes.
ids String “” Comma-delimited list of podcast IDs. This is required.
start_date String NULL Return plays after or on this date.
end_date String NULL Return plays before or on this date.
aggregation String “daily” How should plays be aggregated? Must be one of: daily, weekly, monthly.

Response Details

Type Type Description
metadata Object Information about each podcast.
data Object The number of plays organized by provider.
data.provider Array Each row is an object with the aggregated date and the number of plays during that time period.

Refresh Trackable Status

require "net/http"

uri = URI("https://chartable.com/api/v1/podcasts/:id/refresh_trackable_status")
params = {}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Put.new(uri)
response = http.send_request('PUT', uri.path, params, headers)
curl -X PUT "https://chartable.com/api/v1/podcasts/:id/refresh_trackable_status" \
  -H "Authorization: Bearer <your_access_key>"
fetch("https://chartable.com/api/v1/podcasts/:id/refresh_trackable_status", {
  method: "PUT",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response

{
  "trackable_enabled": true
}

This endpoint refreshes a podcast’s Trackable status for a single podcast.

HTTP Request

PUT https://chartable.com/api/v1/podcasts/:id/refresh_trackable_status

Response Details

Name Type Description
trackable_enabled Boolean Does the podcast have Trackable enabled?

Podcast Reviews

require "net/http"

uri = URI("https://chartable.com/api/v1/podcasts/:id/reviews")
params = {start_date:"2022-01-01", end_date: "2022-02-01"}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/podcasts/:id/reviews" \
  -H "Authorization: Bearer <your_access_key>" \
  -d start_date=2022-01-01 \
  -d end_date=2022-02-01
fetch("https://chartable.com/api/v1/podcasts/:id/reviews?start_date=2022-01-01&end_date=2022-02-01", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

[
  {
    "title": "My Review",
    "review": "This is my review.",
    "author_name": "Author Name",
    "posted_at": "2022-01-15T12:00:00.000Z",
    "provider": "Apple Podcasts",
    "rating": 5.0,
    "podcast_title": "Podcast Title"
  }
]

This endpoint lists all reviews for the podcast.

HTTP Request

GET https://chartable.com/api/v1/podcasts/:id/reviews

Request Parameters

Parameter Type Default Description
page Integer 1 Which page of reviews to return (if you have more than 20).
page_size Integer 20 How many reviews to return. This cannot be larger than the default value.
start_date DateTime NULL Returns reviews that were posted on or after this date.
end_date DateTime NULL Return reviews that were posted on or before this date.
provider String “” Return reviews only from this provider. See providers for a list of values.
country String “” Return reviews only form this country. See country codes for a list of values.

Response Structure

Name Type Description
title String The review’s title
review String The review
author_name String The author’s name
posted_at DateTime When the review was posted
provider String The platform the review was posted on
rating Float The numerical rating
podcast_title String The podcast’s title

Podcast Reviews History

require "net/http"

uri = URI("https://chartable.com/api/v1/podcasts/:id/reviews_history")
params = {start_date:"2022-01-01", end_date: "2022-02-01"}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/podcasts/:id/reviews_history" \
  -H "Authorization: Bearer <your_access_key>" \
  -d start_date=2022-01-01 \
  -d end_date=2022-02-01
fetch("https://chartable.com/api/v1/podcasts/:id/reviews_history?start_date=2022-01-01&end_date=2022-02-01", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

[
  ["2022-01-01T00:00:00Z", 10],
  ["2022-01-03T00:00:00Z", 15],
  ["2022-01-07T00:00:00Z", 20],
  ["2022-01-10T00:00:00Z", 25],
  ["2022-01-15T00:00:00Z", 20],
  ["2022-01-18T00:00:00Z", 15]
]

This endpoint lists the number of reviews posted each day.

HTTP Request

GET https://chartable.com/api/v1/podcasts/:id/reviews_history

Request Parameters

Parameter Type Default Description
start_date DateTime NULL Returns reviews that were posted on or after this date.
end_date DateTime NULL Return reviews that were posted on or before this date.
provider String “” Return reviews only from this provider. See providers for a list of values.
country String “” Return reviews only form this country. See country codes for a list of values.

Response Structure

Type Description
array An array of how many reviews were posted each day.
array[0] The date.
array[1] The number of reviews posted on that date.

Podcast Reviews Summary

require "net/http"

uri = URI("https://chartable.com/api/v1/podcasts/:id/reviews_summary")
params = {start_date:"2022-01-01", end_date: "2022-02-01"}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/podcasts/:id/reviews_summary" \
  -H "Authorization: Bearer <your_access_key>" \
  -d start_date=2022-01-01 \
  -d end_date=2022-02-01
fetch("https://chartable.com/api/v1/podcasts/:id/reviews_summary?start_date=2022-01-01&end_date=2022-02-01", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
   "monthly_growth": "50.0%",
   "ratings_count": 20000,
   "rating": 4.5,
   "total_filtered_reviews": 100,
   "total_reviews": 5000,
   "providers": [
      "Apple Podcasts",
      "Stitcher"
   ],
   "countries": [
      "Canada",
      "France",
      "Germany",
      "Great Britain",
      "United States of America"
   ]
}

This endpoint returns aggregated review metrics for the podcast.

HTTP Request

GET https://chartable.com/api/v1/podcasts/:id/reviews_summary

Request Parameters

Parameter Type Default Description
start_date DateTime NULL Returns reviews that were posted on or after this date.
end_date DateTime NULL Return reviews that were posted on or before this date.
provider String “” Return reviews only from this provider. See providers for a list of values.
country String “” Return reviews only form this country. See country codes for a list of values.

Response Structure

Name Type Description
monthly_growth String How many more reviews do you have this month compared to last month?
ratings_count Integer The number of ratings across all podcasts.
rating Float The average rating across all podcasts.
total_reviews Integer The number of reviews across all podcasts.
total_filtered_reviews Integer The number of reviews that match the request parameters across all podcasts.
providers Array All of the providers where reviews were posted. See providers for a list of values.
countries Array All of the countries where reviews were posted. See country codes for a list of values.

Episodes

Episode Consumption

require "net/http"

uri = URI("https://chartable.com/api/v1/consumption")
params = {scope: "episodes", ids: "54d7842b-2096-4a35-9af9-6cb10c8e78df,5fa49415-3962-429e-86dc-73ee7c1c9d76"}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "http://localhost:5555/api/v1/consumption" \
  -H "Authorization: Bearer ch_eyJ0ZWFtX2lkIjoiRTE1OTQiLCJjcmVhdGVkX2F0IjoiMjAyMi0wMS0yMSAxNTowNzozOCBVVEMifQ.cxAUedxY0lYfAjnvjUC-QKbwCM_kXZ9CGta7rPXUmrM" \
  -d scope=episodes \
  -d ids=54d7842b-2096-4a35-9af9-6cb10c8e78df,5fa49415-3962-429e-86dc-73ee7c1c9d76
fetch("https://chartable.com/api/v1/consumption?scope=episodes&ids=54d7842b-2096-4a35-9af9-6cb10c8e78df,5fa49415-3962-429e-86dc-73ee7c1c9d76", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "metadata": {
    "54d7842b-2096-4a35-9af9-6cb10c8e78df": {
      "id": "54d7842b-2096-4a35-9af9-6cb10c8e78df",
      "title": "Episode 1",
      "published_at": "2022-01-01T012:00:00.000Z"
    },
    "5fa49415-3962-429e-86dc-73ee7c1c9d76": {
      "id": "5fa49415-3962-429e-86dc-73ee7c1c9d76",
      "title": "Episode 2",
      "published_at": "2022-01-01T012:00:00.000Z"
    }
  },
  "data": {
    "54d7842b-2096-4a35-9af9-6cb10c8e78df": [{
      "Spotify": [{
        "percentage": 0.0,
        "consumption": 0.98
      },{
        "percentage": 0.1,
        "consumption": 0.95
      }]
    },{
      "Apple": [{
        "percentage": 0.0,
        "consumption": 0.90
      },{
        "percentage": 0.1,
        "consumption": 0.85
      }]
    }],
    "5fa49415-3962-429e-86dc-73ee7c1c9d76": [{
      "Spotify": [{
        "percentage": 0.0,
        "consumption": 0.95
      },{
        "percentage": 0.1,
        "consumption": 0.90
      }]
    },{
      "Apple": [{
        "percentage": 0.0,
        "consumption": 0.93
      },{
        "percentage": 0.1,
        "consumption": 0.87
      }]
    }]
  }
}

This endpoint returns consumption data for up to 5 episodes.

HTTP Request

GET https://chartable.com/api/v1/consumption

Request Parameters

Parameter Type Required Description
scope String “” The level of data to return. Must be one of: podcasts, episodes. This is required.
ids String “” Comma-delimited list of episode IDs. This is required.

Response Structure

Name Type Description
metadata Object Information about each episode.
data Object The consumption data organized by episode and provider.
data.episode Array Each row is a provider containing consumption data.
data.provider Array Each row is an object where percentage represents 1/100th of the duration of the podcast, and the consumption data for that timeframe.

Episode Demographics

require "net/http"

uri = URI("https://chartable.com/api/v1/demographics")
params = {scope: "episodes", ids: "54d7842b-2096-4a35-9af9-6cb10c8e78df,5fa49415-3962-429e-86dc-73ee7c1c9d76"}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "http://localhost:5555/api/v1/demographics" \
  -H "Authorization: Bearer ch_eyJ0ZWFtX2lkIjoiRTE1OTQiLCJjcmVhdGVkX2F0IjoiMjAyMi0wMS0yMSAxNTowNzozOCBVVEMifQ.cxAUedxY0lYfAjnvjUC-QKbwCM_kXZ9CGta7rPXUmrM" \
  -d scope=episodes \
  -d ids=54d7842b-2096-4a35-9af9-6cb10c8e78df,5fa49415-3962-429e-86dc-73ee7c1c9d76
fetch("https://chartable.com/api/v1/demographics?scope=episodes&ids=54d7842b-2096-4a35-9af9-6cb10c8e78df,5fa49415-3962-429e-86dc-73ee7c1c9d76", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "country_demographics": {
    "Trackable": [
      ["Country", "Episode 1", "Episode 2"],
      ["US", 1000, 500]
      ["GB", 900, 400]
    ],
    "Spotify": [
      ["Country", "Episode 1", "Episode 2"],
      ["US", 1000, 500]
      ["GB", 900, 400]
    ]
  },
  "gender_demographics": {
    "Spotify": [
      ["Gender", "Episode 1", "Episode 2"],
      ["Male", 1000, 500],
      ["Female", 900, 400],
      ["Not Binary", 800, 300]
      ["Not Specified", 700, 200]
    ]
  },
  "age_demographics": {
    "Spotify": [
      ["0-17", 10000],
      ["18-22", 9000],
      ["23-27", 8000],
      ["28-34", 7000],
      ["35-44", 6000],
      ["45-59", 5000],
      ["60-150", 4000],
      ["unknown", 3000]
    ]
  },
  "player_demographics": {
    "Trackable": [
      ["Player", "Episode 1", "Episode 2"],
      ["Apple Podcasts", 10000, 1000],
      ["Spotify", 9000, 900],
      ["Pocket Casts", 8000, 800],
      ["Overcast", 7000, 700],
      ["Stitcher", 6000, 600],
      ["PodcastAddict", 5000, 500],
      ["CastBox", 4000, 400],
      ["iHeartRadio", 3000, 300],
      ["iTunes", 2000, 200],
      ["TuneIn", 1000, 100]
    ]
  }
}

This endpoint returns demographics for up to 5 episodes.

HTTP Request

GET https://chartable.com/api/v1/demoraphics

Request Parameters

Parameter Type Required Description
scope String “” The level of data to return. Must be one of: podcasts, episodes, team.
ids String “” Comma-delimited list of episode IDs. This is required.

Response Structure

Name Type Description
country_demographics Array The number of downloads organized by country. See Country Codes for a list of values.
gender_demographics Array The number of downloads organized by gender.
age_demographics Array The number of downloads organized by age.
player_demographics Array The number of downloads organized by player.

Episode Downloads

require "net/http"

uri = URI("https://chartable.com/api/v1/downloads")
params = {
  scope: "episodes",
  ids: "54d7842b-2096-4a35-9af9-6cb10c8e78df,5fa49415-3962-429e-86dc-73ee7c1c9d76",
  start_date: "2022-01-01",
  end_date: "2022-01-03",
  aggregation: "daily"
}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/downloads" \
  -H "Authorization: Bearer <your_access_key>" \
  -d scope=episodes
  -d ids=54d7842b-2096-4a35-9af9-6cb10c8e78df,5fa49415-3962-429e-86dc-73ee7c1c9d76 \
  -d start_date=2022-01-01 \
  -d end_date=2022-01-03 \
  -d aggregation=daily
fetch("https://chartable.com/api/v1/downloads?scope=episodes&ids=54d7842b-2096-4a35-9af9-6cb10c8e78df,5fa49415-3962-429e-86dc-73ee7c1c9d76&start_date=2022-01-01&end_date=2022-01-03&aggregation=daily", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response

{
  "metadata": {
    "54d7842b-2096-4a35-9af9-6cb10c8e78df": {
      "id": "54d7842b-2096-4a35-9af9-6cb10c8e78df",
      "title": "Episode 1",
      "published_at": "2022-01-01T012:00:00.000Z"
    },
    "5fa49415-3962-429e-86dc-73ee7c1c9d76": {
      "id": "5fa49415-3962-429e-86dc-73ee7c1c9d76",
      "title": "Episode 2",
      "published_at": "2022-01-01T012:00:00.000Z"
    }
  },
  "data": [{
    "date": "2022-01-01",
    "54d7842b-2096-4a35-9af9-6cb10c8e78df": 1000,
    "Episode 2 ": 2000
  },{
    "date": "2022-01-02",
    "5fa49415-3962-429e-86dc-73ee7c1c9d76": 500,
    "Episode 2 ": 1500
  }]
}

This endpoint returns the number of total downloads for up to 5 episodes.

HTTP Request

GET https://chartable.com/api/v1/downloads

Request Parameters

Parameter Type Default Description
scope String “” The level of data to return. Must be one of: episodes, podcasts.
ids String “” Comma-delimited list of episode IDs. This is required.
start_date String NULL Return downloads after or on this date.
end_date String NULL Return downloads before or on this date.
aggregation String “daily” How should downloads be aggregated? Must be one of: daily, weekly, monthly.

Response Structure

Name Type Description
metadata Object Information about each episode.
data Array The downloads organized by aggregated date.

Episode Plays

require "net/http"

uri = URI("https://chartable.com/api/v1/plays")
params = {
  scope: "episodes",
  ids: "f99e8b72-ddb6-4596-9165-57295917647d,371a7032-7e71-4bb1-9b5c-ad9bd1d11d33",
  start_date: "2022-01-01",
  end_date: "2022-01-03",
  aggregation: "daily"
}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/plays" \
  -H "Authorization: Bearer <your_access_key>" \
  -d scope=episodes
  -d ids=f99e8b72-ddb6-4596-9165-57295917647d,371a7032-7e71-4bb1-9b5c-ad9bd1d11d33 \
  -d start_date=2022-01-01 \
  -d end_date=2022-01-03 \
  -d aggregation=daily
fetch("https://chartable.com/api/v1/plays?scope=episodes&ids=f99e8b72-ddb6-4596-9165-57295917647d,371a7032-7e71-4bb1-9b5c-ad9bd1d11d33&start_date=2022-01-01&end_date=2022-01-03&aggregation=daily", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response

{
  "metadata": {
    "f99e8b72-ddb6-4596-9165-57295917647d": {
      "id": "f99e8b72-ddb6-4596-9165-57295917647d",
      "title": "Episode 1",
      "published_at": "2022-01-01T012:00:00.000Z"
    },
    "371a7032-7e71-4bb1-9b5c-ad9bd1d11d33": {
      "id": "371a7032-7e71-4bb1-9b5c-ad9bd1d11d33",
      "title": "Episode 2",
      "published_at": "2022-01-02T012:00:00.000Z"
    }
  },
  "data": {
    "f99e8b72-ddb6-4596-9165-57295917647d": {
      "Spotify":[{
          "date":" 2021-01-01",
          "count": 500.0
        },{
          "date": "2022-01-02",
          "count": 400.0
        },{
          "date": "2022-01-03",
          "count": 300.0
        }
      ]
    },
    "371a7032-7e71-4bb1-9b5c-ad9bd1d11d33": {
      "Apple":[{
          "date":" 2021-01-01",
          "count": 300.0
        },{
          "date": "2022-01-02",
          "count": 200.0
        },{
          "date": "2022-01-03",
          "count": 100.0
        }
      ]
    }
  }
}

This endpoint returns the number of total plays for up to 5 episodes.

HTTP Request

GET https://chartable.com/api/v1/plays

Request Parameters

Parameter Type Default Description
scope String “” The level of data to return. Must be one of: podcasts, episodes.
ids String “” Comma-delimited list of episode IDs. This is required.
start_date String NULL Return plays after or on this date.
end_date String NULL Return plays before or on this date.
aggregation String “daily” How should plays be aggregated? Must be one of: daily, weekly, monthly.

Response Details

Type Type Description
metadata Object Information about each episode.
data Object The number of plays organized by provider.
data.provider Array Each row is an object with the aggregated date and the number of plays during that time period.

Remarketing Pixels

Create a Remarketing Pixel

require "net/http"

uri = URI("https://chartable.com/api/v1/remarketing_pixels")
params = {platform: "google_tag_manager", pixel: "my_pixel", default_for_platform: true}
headers = {
  "Authorization" => "Bearer <your_access_key>",
  "Content-Type" => "application/json",
  "Accept" => "application/json"
}

http = Net::HTTP.post(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X POST "https://chartable.com/api/v1/remarketing_pixels" \
  -H "Authorization: Bearer <your_access_key>" \
  -d platform=google_tag_manager \
  -d pixel=my_pixel \
  -d default_for_platform=true
fetch("https://chartable.com/api/v1/remarketing_pixels?platform=google_tag_manager&pixel=my_pixel&default_for_platform=true", {
  method: "POST",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "id": "a97f0ef9-5c33-4ccc-b71f-01c77847e7a1",
  "platform": "google_tag_manager",
  "pixel": "my_pixel",
  "default_for_platform": true
}

This endpoint creates a Remarketing Pixel.

HTTP Request

POST https://chartable.com/api/v1/remarketing_pixels

Query Parameters

Parameter Type Description
platform String Must be one of: facebook, google_tag_manager, tiktok.
pixel String The pixel’s value.
default_for_platform Boolean When true, this pixel will be automatically assigned to newly created SmartLinks.

Response Details

Name Type Description
id String The pixel’s unique ID.
platform String The pixel’s platform.
pixel String The pixel’s value.
default_for_platform Boolean If true, this pixel will automatically be assigned to new SmartLinks.

Delete a Remarketing Pixel

require "net/http"

uri = URI("https://chartable.com/api/v1/remarketing_pixels/:id")
headers = {
  "Authorization" => "Bearer <your_access_key>",
  "Content-Type" => "application/json",
   "Accept" => "application/json"
}

http = Net::HTTP.delete(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X DELETE "https://chartable.com/api/v1/remarketing_pixels/:id" \
  -H "Authorization: Bearer <your_access_key>"
fetch("https://chartable.com/api/v1/remarketing_pixels/:id", {
  method: "DELETE",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

Response Structure

{
  "id": "a97f0ef9-5c33-4ccc-b71f-01c77847e7a1",
  "deleted": true
}

This endpoint deletes a Remarketing Pixel.

HTTP Request

DELETE https://chartable.com/api/v1/remarketing_pixels/:id

Response Details

Name Type Description
id String The pixel’s unique ID
deleted Boolean Was the pixel deleted?

List Remarketing Pixels

require "net/http"

uri = URI("https://chartable.com/api/v1/remarketing_pixels")
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/remarketing_pixels" \
  -H "Authorization: Bearer <your_access_key>"
fetch("https://chartable.com/api/v1/remarketing_pixels", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

[
  {
    "id": "a97f0ef9-5c33-4ccc-b71f-01c77847e7a1",
    "platform": "facebook",
    "pixel": "my_pixel_1",
    "default_for_platform": true
  }
]

This endpoint lists all of your Remarketing Pixels.

HTTP Request

GET https://chartable.com/api/v1/remarketing_pixels

Response Details

Name Type Description
id String The pixel’s unique ID.
platform String The pixel’s platform.
pixel String The pixel’s value.
default_for_platform Boolean If true, this pixel will automatically be assigned to new SmartLinks.

Show a Remarketing Pixel

require "net/http"

uri = URI("https://chartable.com/api/v1/remarketing_pixels/:id")
headers = {
  "Authorization" => "Bearer <your_access_key>",
  "Content-Type" => "application/json",
  "Accept" => "application/json"
}

http = Net::HTTP.post(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/remarketing_pixels/:id" \
  -H "Authorization: Bearer <your_access_key>"
fetch("https://chartable.com/api/v1/remarketing_pixels/:id", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response

{
  "id": "a97f0ef9-5c33-4ccc-b71f-01c77847e7a1",
  "platform": "google_tag_manager",
  "pixel": "my_pixel",
  "default_for_platform": true
}

This endpoint shows a Remarketing Pixel.

HTTP Request

GET https://chartable.com/api/v1/remarketing_pixels/:id

Response Details

Name Type Description
id String The pixel’s unique ID.
platform String The pixel’s platform.
pixel String The pixel’s value.
default_for_platform Boolean If true, this pixel will automatically be assigned to new SmartLinks.

Update a Remarketing Pixel

require "net/http"

uri = URI("https://chartable.com/api/v1/remarketing_pixels/:id")
params = {platform: "google_tag_manager", pixel: "my_pixel", default_for_platform: true}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.patch(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X PATCH "https://chartable.com/api/v1/remarketing_pixels/:id" \
  -H "Authorization: Bearer <your_access_key>" \
  -d platform=google_tag_manager \ 
  -d pixel=my_pixel \ 
  -d default_for_platform=true
fetch("https://chartable.com/api/v1/remarketing_pixels/:id?platform=google_tag_manager&pixel=my_pixel&default_for_platform=true", {
  method: "PATCH",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "id": "a97f0ef9-5c33-4ccc-b71f-01c77847e7a1",
  "platform": "google_tag_manager",
  "pixel": "my_pixel",
  "default_for_platform": true
}

This endpoint updates a single Remarketing Pixel.

HTTP Request

PATCH https://chartable.com/api/v1/remarketing_pixels/:id

Query Parameters

Parameter Type Description
platform String Must be one of: facebook, google_tag_manager, tiktok.
pixel String The pixel’s value.
default_for_platform Boolean When true, this pixel will be automatically assigned to newly created SmartLinks.

Response Details

Name Type Description
id String The pixel’s unique ID.
platform String The pixel’s platform.
pixel String The pixel’s value.
default_for_platform Boolean If true, this pixel will automatically be assigned to new SmartLinks.

SmartLink Domains

require "net/http"

uri = URI("https://chartable.com/api/v1/smart_link_domains")
params = {name: "www.example.com"}
headers = {
  "Authorization" => "Bearer <your_access_key>",
  "Content-Type" => "application/json",
  "Accept" => "application/json"
}

http = Net::HTTP.post(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X POST "https://chartable.com/api/v1/smart_link_domains" \
  -H "Authorization: Bearer <your_access_key>" \
  -d name=www.example.com
fetch("https://chartable.com/api/v1/smart_link_domains?name=www.example.com", {
  method: "POST",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "id": "72777212-7c77-4888-b0d5-db534356ec96",
  "name": "www.example.com",
  "status": "Pending",
  "cname": "example-cname.com"
}

This endpoint creates a SmartLink Domain.

HTTP Request

POST https://chartable.com/api/v1/smart_link_domains

Query Parameters

Parameter Type Description
name String Your domain name

Response Details

Name Type Description
id String The domain’s unique ID.
name String The domain name.
status String Does the domain have a DNS cname record that points to the cname domain? This will always be “Pending” after creating a domain. Make a call to check_status to set this to “Active” after the DNS record has propagated.
cname String The cname for this domain.
require "net/http"

uri = URI("https://chartable.com/api/v1/smart_link_domains/:id")
headers = {
  "Authorization" => "Bearer <your_access_key>",
  "Content-Type" => "application/json",
   "Accept" => "application/json"
}

http = Net::HTTP.delete(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X DELETE "https://chartable.com/api/v1/smart_link_domains/:id" \
  -H "Authorization: Bearer <your_access_key>"
fetch("https://chartable.com/api/v1/smart_link_domains/:id", {
  method: "DELETE",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "id": "a97f0ef9-5c33-4ccc-b71f-01c77847e7a1",
  "deleted": true
}

This endpoint deletes a SmartLink Domain.

HTTP Request

DELETE https://chartable.com/api/v1/smart_link_domains/:id

Response Details

Name Type Description
id String The domain’s unique ID
deleted Boolean Was the domain deleted?
require "net/http"

uri = URI("https://chartable.com/api/v1/smart_link_domains")
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/smart_link_domains" \
  -H "Authorization: Bearer <your_access_key>"
fetch("https://chartable.com/api/v1/smart_link_domains", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

[
  {
    "id": "77553410-fa24-40c5-a93a-25959dbc4094",
    "name": "www.example1.com",
    "status": "Active",
    "cname": "example-cname1.com",
    "podcast": [
      "id": "6a5b2ef2-169a-4fa9-aa12-88b98e735227",
      "title": "My Podcast"
    ]
  }
]

This endpoint lists all of your SmartLink domains.

HTTP Request

GET https://chartable.com/api/v1/smart_link_pixels

Response Details

Name Type Description
id String The domain’s unique ID.
name String The domain name.
cname String The cname for this domain.
podcast Object The podcast associated with this domain.
id String The podcast’s unique ID
title String The podcast’s title
require "net/http"

uri = URI("https://chartable.com/api/v1/smart_link_domains/:id")
headers = {
  "Authorization" => "Bearer <your_access_key>",
  "Content-Type" => "application/json",
  "Accept" => "application/json"
}

http = Net::HTTP.post(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/smart_link_domains/:id" \
  -H "Authorization: Bearer <your_access_key>"
fetch("https://chartable.com/api/v1/smart_link_domains/:id", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "id": "77553410-fa24-40c5-a93a-25959dbc4094",
  "name": "www.example1.com",
  "status": "Active",
  "cname": "example-cname1.com",
  "podcast": [
    "id": "6a5b2ef2-169a-4fa9-aa12-88b98e735227",
    "title": "My Podcast"
  ]
}

This endpoint shows a SmartLink Domain.

HTTP Request

GET https://chartable.com/api/v1/smart_link_domains/:id

Response Details

Name Type Description
id String The domain’s unique ID.
name String The domain name.
cname String The cname for this domain.
status String Does the domain have a DNS cname record that points to the cname domain? If yes, then “Active” is returned. Otherwise “Pending” is returned.
podcast Object The podcast associated with this domain.
id String The podcast’s unique ID
title String The podcast’s title
require "net/http"

uri = URI("https://chartable.com/api/v1/smart_link_domains/:id")
params = {name: "updated.example.com"}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.patch(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X PATCH "https://chartable.com/api/v1/smart_link_domains/:id" \
  -H "Authorization: Bearer <your_access_key>" \
  -d name=updated.example.com
fetch("https://chartable.com/api/v1/smart_link_domains/:id?name=updated.example.com", {
  method: "PATCH",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "id": "77553410-fa24-40c5-a93a-25959dbc4094",
  "name": "www.example1.com",
  "status": "Active",
  "cname": "example-cname1.com",
  "podcast": [
    "id": "6a5b2ef2-169a-4fa9-aa12-88b98e735227",
    "title": "My Podcast"
  ]
}

This endpoint updates a single SmartLink Domain.

HTTP Request

PATCH https://chartable.com/api/v1/smart_link_domains/:id

Query Parameters

Parameter Type Description
name String Your domain name

Response Details

Name Type Description
id String The domain’s unique ID.
name String The domain name.
cname String The cname for this domain.
status String Does the domain have a DNS cname record that points to the cname domain? If yes, then “Active” is returned. Otherwise “Pending” is returned.
podcast Object The podcast associated with this domain.
id String The podcast’s unique ID
title String The podcast’s title
require "net/http"

uri = URI("https://chartable.com/api/v1/smart_link_domains/:id/check_status")
params = {podcast_id: "220de2b4-a96f-4a01-b1f2-9d83f9177421"}
headers = {
  "Authorization" => "Bearer <your_access_key>",
  "Content-Type" => "application/json",
  "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/smart_link_domains/:id/check_status" \
  -H "Authorization: Bearer <your_access_key>" \
  -d podcast_id=220de2b4-a96f-4a01-b1f2-9d83f9177421
fetch("https://chartable.com/api/v1/smart_link_domains/:id/check_status?podcast_id=220de2b4-a96f-4a01-b1f2-9d83f9177421, {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "id": "72777212-7c77-4888-b0d5-db534356ec96",
  "name": "www.example.com",
  "status": "Active",
  "cname": "example-cname.com"
}

This endpoint checks if the cname has been added to your domain. If so, the status is changed to Active and you can add a podcast.

HTTP Request

GET https://chartable.com/api/v1/smart_link_domains/:id/check_status

Response Details

Name Type Description
id String The domain’s unique ID.
name String The domain name.
status String Does the domain have a DNS cname record that points to the cname domain? If yes, then “Active” is returned. Otherwise “Pending” is returned.
cname String The cname for this domain.

Add a Podcast

require "net/http"

uri = URI("https://chartable.com/api/v1/smart_link_domains/:id/add_podcast")
params = {podcast_id: "220de2b4-a96f-4a01-b1f2-9d83f9177421"}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.post(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X PATCH "https://chartable.com/api/v1/smart_link_domains/:id/add_podcast" \
  -H "Authorization: Bearer <your_access_key>" \
  -d podcast_id=220de2b4-a96f-4a01-b1f2-9d83f9177421
fetch("https://chartable.com/api/v1/smart_link_domains/:id/add_podcast?podcast_id=220de2b4-a96f-4a01-b1f2-9d83f9177421, {
  method: "PATCH",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "id": "77553410-fa24-40c5-a93a-25959dbc4094",
  "name": "www.example1.com",
  "status": "Active",
  "cname": "example-cname1.com",
  "podcast": {
    "id": "220de2b4-a96f-4a01-b1f2-9d83f9177421",
    "title": "My Podcast"
  }
}

This endpoint associates a Podcast to a SmartLink Domain.

HTTP Request

PATCH https://chartable.com/api/v1/smart_link_domains/:id/add_podcast

Query Parameters

Parameter Type Description
podcast_id String The ID of the podcast to associate with this domain.

Response Details

Name Type Description
id String The domain’s unique ID.
name String The domain name.
cname String The cname for this domain.
podcast Object The podcast associated with this domain.
id String The podcast’s unique ID
title String The podcast’s title

Remove a Podcast

require "net/http"

uri = URI("https://chartable.com/api/v1/smart_link_domains/:id/remove_podcast")
params = {podcast_id: "220de2b4-a96f-4a01-b1f2-9d83f9177421"}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.post(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X PATCH "https://chartable.com/api/v1/smart_link_domains/:id/remove_podcast" \
  -H "Authorization: Bearer <your_access_key>" \
  -d podcast_id=220de2b4-a96f-4a01-b1f2-9d83f9177421
fetch("https://chartable.com/api/v1/smart_link_domains/:id/remove_podcast?podcast_id=220de2b4-a96f-4a01-b1f2-9d83f9177421, {
  method: "PATCH",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "id": "77553410-fa24-40c5-a93a-25959dbc4094",
  "podcast_id": "220de2b4-a96f-4a01-b1f2-9d83f9177421"
  "deleted": true
}

This endpoint disassociates a Podcast to a SmartLink Domain.

HTTP Request

PATCH https://chartable.com/api/v1/smart_link_domains/:id/remove_podcast

Query Parameters

Parameter Type Description
podcast_id String The ID of the podcast to disassociate from this domain.

Response Details

Name Type Description
id String The domain’s unique ID.
podcast_id String The podcast’s unique ID.
deleted Boolean Was the podcast removed from the domain?

SmartLinks

require "net/http"

uri = URI("https://chartable.com/api/v1/smart_links")
params = {name: "My SmartLink"}
headers = {
  "Authorization" => "Bearer <your_access_key>",
  "Content-Type" => "application/json",
  "Accept" => "application/json"
}

http = Net::HTTP.post(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X POST "https://chartable.com/api/v1/smart_links" \
  -H "Authorization: Bearer <your_access_key>" \
  -d name=My SmartLink
fetch("https://chartable.com/api/v1/smart_links?name=My+SmartLink", {
  method: "POST",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "id": "620a1fec-e23e-4c07-a404-c5af9d6a25ab",
  "name": "SmartLink 1",
  "url": "https://link.chtbl.com/d574Lw_M",
  "created_at": "2022-01-01T12:00:00.000Z",
  "archived": false,
  "episode": {
    "id": "80ec833f-922a-40f8-9ecd-22bc8f8389c4", 
    "title": "Example Episode",
    "short_title": "Example Episode",
    "published_at": "2022-01-01 12:00:00",
    "url": "https://example.com/podcast/episode.mp3"
  },
  "downloads_last_updated": "2022-01-01 12:00:00",
  "social_media_image_url": "https://example.com/image.png",
  "default_url": "https://example.com",
  "unique_downloads": 100,
  "unique_device_downloads": 75,
  "conversions": 0,
  "new_device_downloads": 50,
  "clicks": 100,
  "unique_clicks": 75,
  "show_podcast_player": true,
  "title": "Landing Page Title",
  "description": "<p>Landing Page Description</p>",
  "background_hex_color": "#FFFFFF",
  "show_episode_player": true,
  "source_ids": [],
  "domain": {
    "id": "3d290e75-e232-4fea-8f40-21ac38e5f0d5",
    "prefix": "https://example.com"
  },
  "platforms": {
    "spotify": "https://open.spotify.com/show/example",
    "google_podcasts": "https://podcasts.google.com?feed=example.com/feed.rss",
    "amazon_music": "https://music.amazon.com/example-podcast"
  },
  "players": {
    "all": ["itunes", "spotify", "radio_com", "google_podcasts", "overcast", "pocket_casts"]
  },
  "podcast": {
    "slug": "chartable-radio",
    "id": "593ed285-6e18-447c-8d61-44dbcbd907ba",
    "image_url": "https://example.com/image.jpg",
    "title": "My Podcast",
    "trackable_e_nabled": true
  },
  "remarketing_pixels": [
    {
      "id": "11b2f749-3a9f-4ef5-9fbe-ad04c1f0dbe6",
      "platform": "tiktok",
      "pixel": "C6001O479STF7B6J8NGG",
      "default_for_platform": true
    }
  ]
}

This endpoint creates a SmartLink.

HTTP Request

POST https://chartable.com/api/v1/smart_links

Query Parameters

Parameter Type Description
background_hex_color String The background color for the SmartLink’s landing page.
default_url String The redirect url when the SmartLink cannot find a conditional url
description String Text that appears on the SmartLink’s landing page.
episode_id String The id for the SmartLink’s episode.
name String The SmartLink’s name.
platforms Array The platforms to show on the SmartLink’s landing page.
players Array The players to show on the SmartLink’s landing page.
podcast_id String The id for the SmartLink’s podcast.
remarketing_pixels Array The IDs of remarketing pixels to attach to this SmartLink.
show_episode_player Boolean Should a player appear on the SmartLink’s landing page?
slug String The URL pathname. The slug cannot be changed if the SmartLink has clicks.
smart_link_domain_id String The id for the SmartLink’s domain.
social_media_image_url String The SmartLink’s social media image. Send an empty string to remove the image.
title String The text inside of the SmartLink’s landing page <title> tag.

Response Details

Name Type Description
id String The SmartLink’s unqiue ID.
name String The SmartLink’s name.
url String The SmartLink’s URL.
created_at DateTime When the SmartLink was created.
archived Boolean Is the SmartLink archived?
downloads_last_updated DateTime When was the SmartLink’s event data last updated?
social_media_image_url String The image people will see when you share this link on social media.
default_url String The URL users will be redirected to if we are unable to match a conditional redirect rule.
unqiue_downloads Integer The number of unique downloads.
unqiue_device_downloads Integer The number of unique device downloads.
conversions Integer The number of conversions.
new_device_downloads Integer The number of new device downloads.
clicks Integer The number of clicks.
unique_clicks Integer The number of unique clicks.
title String The landing page title.
description String The landing page description.
background_hex_color String The landing page background color.
show_episode_player Boolean Should the landing page have a player?
source_ids Array When the SmartLink URL contains an sid parameter, its value is stored here.
domain Object Information about the SmartLink Domain, if there is one.
domain.id String The SmartLink Domain’s unique ID.
domain.prefix String The SmartLink Domain’s secure domain name.
platforms Object The platforms that host the podcast or episode.
players Object The SmartLink’s players.
podcast Object Details about the podcast associated with this SmartLink.
podcast.display_image_url String The podcast’s cover art url.
podcast.id String The podcast’s unique ID.
podcast.slug String The podcast’s machine-friendly name.
podcast.title String The podcast’s title
podcast.trackable_enabled Boolean Does the podcast’s RSS feed have a valid Trackable prefix?
remarketing_pixels Array The Remarketing Pixels to fire when a user visits the SmartLink.
remarketing_pixels[i].id String The pixel’s unique ID.
remarketing_pixels[i].platform String The pixel’s platform.
remarketing_pixels[i].pixel String The pixel’s value.
remarketing_pixels[i].default_for_platform Boolean When true, this pixel is automatically added to new SmartLinks.
require "net/http"

uri = URI("https://chartable.com/api/v1/smart_links/:id/details?by=channels,players,episodes")
params = {page: "1", start_date: "2022-01-01", end_date: "2022-01-31"}
headers = {
  "Authorization" => "Bearer <your_access_key>",
  "Content-Type" => "application/json",
  "Accept" => "application/json"
}

http = Net::HTTP.new(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl "https://chartable.com/api/v1/smart_links/:id/details?by=channels,players,episodes" \
  -H "Authorization: Bearer <your_access_key>"
fetch("https://chartable.com/api/v1/smart_links/:id/details?by=channels,players,episodes", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "id": "98a31ee3-1bec-4271-b328-a6beb6bc1072",
  "channels": {
    "new_downloads": {
      "": [
        [
          "Referer Domain",
          "New Downloads"
        ],
        [
          "l.instagram.com",
          100
        ]
      ]
    },
    "unique_downloads": {
      "": [
        [
          "Referer Domain",
          "New Downloads"
        ],
        [
          "l.instagram.com",
          100
        ]
      ]
    }
  },
  "players": {
    "new_downloads": {
      "": [
        [
          "Player Name",
          "New Downloads"
        ],
        [
          "Apple Podcasts",
          100
        ]
      ]
    },
    "unique_downloads": {
      "": [
        [
          "Player Name",
          "New Downloads"
        ],
        [
          "Apple Podcasts",
          100
        ]
      ]
    }
  },
  "episodes": {
    "new_downloads": {
      "": [
        [
          "Episode Name",
          "New Downloads"
        ],
        [
          "My Episode",
          100
        ]
      ]
    },
    "unique_downloads": {
      "": [
        [
          "Episode Name",
          "New Downloads"
        ],
        [
          "My Episode",
          100
        ]
      ]
    }
  }
}

This endpoint shows the details a single SmartLink.

HTTP Request

GET https://chartable.com/api/v1/smart_links/:id/details

Query Parameters

Parameter Type Default Description
by Array NULL Valid details are: channels, players, and devices.
start_date DateTime NULL If set, only returns data for events that happened on or after this date.
end_date DateTime NULL If set, only returns data for events that happened on or before this date.

Response Details

Name Type Description
channels Array The number of new and unique downloads by channel.
players Array The number of new and unique downloads by player.
devices Array The number of new and unique downloads by devices.
require "net/http"

uri = URI("https://chartable.com/api/v1/smart_links")
params = {page: "1", start_date: "2022-01-01", end_date: "2022-01-31", archived: false}
headers = {
  "Authorization" => "Bearer <your_access_key>",
  "Content-Type" => "application/json",
  "Accept" => "application/json"
}

http = Net::HTTP.new(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl "https://chartable.com/api/v1/smart_links?page=1&start_date=2022-01-01&end_Date=2022-01-31&archived=false" \
  -H "Authorization: Bearer <your_access_key>"
const http = require("http");
const options = {
  host: "https://chartable.com",
  path: "/api/v1/smart_links?page=1&start_date=2022-01-01&end_Date=2022-01-31"
};

const data = { username: "example" };

fetch("https://chartable.com/api/v1/smart_links?page=1&start_date=2022-01-01&end_Date=2022-01-31&archived=false", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response

{
  "data": [
    {
      "clicks": 1000,
      "conversions": 0,
      "created_at": "2021-12-27T15:49:14.039Z",
      "id": "f1ba1c3b-ea41-4114-a763-8dab78f518dc",
      "name": "Chartable Radio - 12/27/2021",
      "podcast": {
        "display_image_url": "https://example.com/logo.png",
        "id": "dff92854-fa2c-4192-b58d-5a703538e688",
        "slug": "chartable-radio",
        "title": "Chartable Radio",
        "trackable_enabled": true
      },
      "smart_link_domain_id": "7448cf36-6762-4c7b-a66b-41cb385591a1",
      "unique_clicks": 0,
      "unique_downloads": 0,
      "url": "https://www.example.com/my-podcast"
    },{ 
      ...
    }
  ],
  "metadata": {
    "page": 1,
    "page_size": 20,
    "pages": 4,
    "total": 75
  }
}

This endpoint returns paginated SmartLinks from your dashboard.

HTTP Request

GET https://chartable.com/api/v1/smart_links

Request Parameters

Parameter Type Default Description
page Integer 1 Which page of SmartLinks to return (if you have more than 50).
page_size Integer 50 How many SmartLinks to return. This cannot be larger than the default value.
start_date DateTime NULL If set, only returns data for events that happened on or after this date.
end_date DateTime NULL If set, only returns data for events that happened on or before this date.
archived Boolean false Set to true to get archived SmartLinks.
sort_by String “created_at” The attribute used to sort the SmartLinks. Must be one of: created_at, name.
sort_desc Boolean true Set to false to sort in ascending order.

Response Details

Name Type Description
clicks Integer The number of clicks.
conversions Integer The number of conversions.
created_at DateTime When the SmartLink was created.
domain Object The SmartLink Domain associated with the SmartLink.
domain.id String The domain’s unique ID
domain.prefix String The domain’s secure hostname.
id String The unique ID for the SmartLink.
name String The SmartLink’s name.
podcast Object Details about the podcast associated with this SmartLink.
podcast.display_image_url String The podcast’s cover art url.
podcast.id String The podcast’s unique ID.
podcast.slug String The podcast’s machine-friendly name.
podcast.title String The podcast’s title
podcast.trackable_enabled Boolean Does the podcast’s RSS feed have a valid Trackable prefix?
unique_clicks Integer The number of unique clicks.
unique_downloads Integer The number of unique downloads.
url String The SmartLink’s url.
require "net/http"

uri = URI("https://chartable.com/api/v1/smart_links/search?query=My%20Link")
params = {page: "1", start_date: "2022-01-01", end_date: "2022-01-31", archived: false}
headers = {
  "Authorization" => "Bearer <your_access_key>",
  "Content-Type" => "application/json",
  "Accept" => "application/json"
}

http = Net::HTTP.new(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl "https://chartable.com/api/v1/smart_links/search?query=My%20Link" \
  -H "Authorization: Bearer <your_access_key>"
const http = require("http");
const options = {
  host: "https://chartable.com",
  path: "/api/v1/smart_links/search?page=1&start_date=2022-01-01&end_Date=2022-01-31"
};

fetch("https://chartable.com/api/v1/smart_links/search?query=My%20Link", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response

{
  "data": [
    {
      "id": "f69ad663-1e97-4ac3-9c10-4f702d983abb",
      "name": "My Link",
      "display_image_url": "https://example.com/logo.png",
    }
  ]
}

This endpoint returns SmartLinks whose name matches the search query.

HTTP Request

GET https://chartable.com/api/v1/smart_links/search

Request Parameters

Parameter Type Default Description
query String NULL The search query must be present and contain at least 3 characters.

Response Details

Name Type Description
id String The unique ID for the SmartLink.
name String The SmartLink’s name.
display_image_url String The cover art url for the podcast assigned to the SmartLink.
require "net/http"

uri = URI("https://chartable.com/api/v1/smart_links/:id")
params = {page: "1", start_date: "2022-01-01", end_date: "2022-01-31"}
headers = {
  "Authorization" => "Bearer <your_access_key>",
  "Content-Type" => "application/json",
  "Accept" => "application/json"
}

http = Net::HTTP.new(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl "https://chartable.com/api/v1/smart_links/:id?page=1&start_date=2022-01-01&end_Date=2022-01-31" \
  -H "Authorization: Bearer <your_access_key>"
fetch("https://chartable.com/api/v1/smart_links/:id?page=1&start_date=2022-01-01&end_Date=2022-01-31", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "id": "620a1fec-e23e-4c07-a404-c5af9d6a25ab",
  "name": "SmartLink 1",
  "url": "https://link.chtbl.com/d574Lw_M",
  "created_at": "2022-01-01T12:00:00.000Z",
  "archived": false,
  "episode": {
    "id": "80ec833f-922a-40f8-9ecd-22bc8f8389c4", 
    "title": "Example Episode",
    "short_title": "Example Episode",
    "published_at": "2022-01-01 12:00:00",
    "url": "https://example.com/podcast/episode.mp3"
  },
  "downloads_last_updated": "2022-01-01 12:00:00",
  "social_media_image_url": "https://example.com/image.png",
  "default_url": "https://example.com",
  "unique_downloads": 100,
  "unique_device_downloads": 75,
  "conversions": 0,
  "new_device_downloads": 50,
  "clicks": 100,
  "unique_clicks": 75,
  "show_podcast_player": true,
  "title": "Landing Page Title",
  "description": "<p>Landing Page Description</p>",
  "background_hex_color": "#FFFFFF",
  "show_episode_player": true,
  "source_ids": [],
  "domain": {
    "id": "3d290e75-e232-4fea-8f40-21ac38e5f0d5",
    "prefix": "https://example.com"
  },
  "platforms": {
    "spotify": "https://open.spotify.com/show/example",
    "google_podcasts": "https://podcasts.google.com?feed=example.com/feed.rss",
    "amazon_music": "https://music.amazon.com/example-podcast"
  },
  "players": {
    "all": ["itunes", "spotify", "radio_com", "google_podcasts", "overcast", "pocket_casts"]
  },
  "podcast": {
    "slug": "chartable-radio",
    "id": "593ed285-6e18-447c-8d61-44dbcbd907ba",
    "image_url": "https://example.com/image.jpg",
    "title": "My Podcast",
    "trackable_e_nabled": true
  },
  "remarketing_pixels": [
    {
      "id": "11b2f749-3a9f-4ef5-9fbe-ad04c1f0dbe6",
      "platform": "tiktok",
      "pixel": "C6001O479STF7B6J8NGG",
      "default_for_platform": true
    }
  ]
}

This endpoint shows a single SmartLink.

HTTP Request

GET https://chartable.com/api/v1/smart_links/:id

Query Parameters

Parameter Type Default Description
start_date DateTime NULL If set, only returns data for events that happened on or after this date.
end_date DateTime NULL If set, only returns data for events that happened on or before this date.

Response Details

Name Type Description
id String The SmartLink’s unqiue ID.
name String The SmartLink’s name.
url String The SmartLink’s URL.
created_at DateTime When the SmartLink was created.
archived Boolean Is the SmartLink archived?
downloads_last_updated DateTime When was the SmartLink’s event data last updated?
social_media_image_url String The image people will see when you share this link on social media.
default_url String The URL users will be redirected to if we are unable to match a conditional redirect rule.
unqiue_downloads Integer The number of unique downloads.
unqiue_device_downloads Integer The number of unique device downloads.
conversions Integer The number of conversions.
new_device_downloads Integer The number of new device downloads.
clicks Integer The number of clicks.
unique_clicks Integer The number of unique clicks.
title String The landing page title.
description String The landing page description.
background_hex_color String The landing page background color.
show_episode_player Boolean Should the landing page have a player?
source_ids Array When the SmartLink URL contains an sid parameter, its value is stored here.
domain Object Information about the SmartLink Domain, if there is one.
domain.id String The SmartLink Domain’s unique ID.
domain.prefix String The SmartLink Domain’s secure domain name.
platforms Object The platforms that host the podcast or episode.
players Object The SmartLink’s players.
podcast Object Details about the podcast associated with this SmartLink.
podcast.display_image_url String The podcast’s cover art url.
podcast.id String The podcast’s unique ID.
podcast.slug String The podcast’s machine-friendly name.
podcast.title String The podcast’s title
podcast.trackable_enabled Boolean Does the podcast’s RSS feed have a valid Trackable prefix?
remarketing_pixels Array The Remarketing Pixels to fire when a user visits the SmartLink.
remarketing_pixels[i].id String The pixel’s unique ID.
remarketing_pixels[i].platform String The pixel’s platform.
remarketing_pixels[i].pixel String The pixel’s value.
remarketing_pixels[i].default_for_platform Boolean When true, this pixel is automatically added to new SmartLinks.
require "net/http"

uri = URI("https://chartable.com/api/v1/smart_links/:id/timeseries?metrics=clicks,devices")
params = {page: "1", start_date: "2022-01-01", end_date: "2022-01-31"}
headers = {
  "Authorization" => "Bearer <your_access_key>",
  "Content-Type" => "application/json",
  "Accept" => "application/json"
}

http = Net::HTTP.new(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl "https://chartable.com/api/v1/smart_links/:id/timeseries?metrics=clicks,devices" \
  -H "Authorization: Bearer <your_access_key>"
fetch("https://chartable.com/api/v1/smart_links/:id/timeseries?metrics=clicks,devices", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "clicks": [
    ["Date", "Clicks", "Unique Clicks"],
    ["2022-01-01", 1, 1],
    ["2022-01-02", 2, 2]
  ],
  "devices": [
    ["Date", "Devices", "Unique Devices"],
    ["2022-01-01", 1, 1],
    ["2022-01-02", 2, 2]
  ]
}

This endpoint shows the timeseries data for a single SmartLink.

HTTP Request

GET https://chartable.com/api/v1/smart_links/:id/timeseries

Query Parameters

Parameter Type Default Description
metrics Array NULL Valid metrics are: clicks, devices.
start_date DateTime NULL If set, only returns data for events that happened on or after this date.
end_date DateTime NULL If set, only returns data for events that happened on or before this date.

Response Details

Name Type Description
clicks Array The click data organized by day.
devices Array The device data organized by day.
require "net/http"

uri = URI("https://chartable.com/api/v1/smart_links/:id")
params = {name: "Updated SmartLink Name"}
headers = {
  "Authorization" => "Bearer <your_access_key>",
  "Content-Type" => "application/json",
  "Accept" => "application/json"
}

http = Net::HTTP.patch(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X PATCH "https://chartable.com/api/v1/smart_links/:id" \
  -H "Authorization: Bearer <your_access_key>" \
  -d name=Updated SmartLink Name
fetch("https://chartable.com/api/v1/smart_links/:id?name=Updated+SmartLink+Name", {
  method: "PATCH",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "id": "620a1fec-e23e-4c07-a404-c5af9d6a25ab",
  "name": "SmartLink 1",
  "url": "https://link.chtbl.com/d574Lw_M",
  "created_at": "2022-01-01T12:00:00.000Z",
  "archived": false,
  "episode": {
    "id": "80ec833f-922a-40f8-9ecd-22bc8f8389c4", 
    "title": "Example Episode",
    "short_title": "Example Episode",
    "published_at": "2022-01-01 12:00:00",
    "url": "https://example.com/podcast/episode.mp3"
  },
  "downloads_last_updated": "2022-01-01 12:00:00",
  "social_media_image_url": "https://example.com/image.png",
  "default_url": "https://example.com",
  "unique_downloads": 100,
  "unique_device_downloads": 75,
  "conversions": 0,
  "new_device_downloads": 50,
  "clicks": 100,
  "unique_clicks": 75,
  "show_podcast_player": true,
  "title": "Landing Page Title",
  "description": "<p>Landing Page Description</p>",
  "background_hex_color": "#FFFFFF",
  "show_episode_player": true,
  "source_ids": [],
  "domain": {
    "id": "3d290e75-e232-4fea-8f40-21ac38e5f0d5",
    "prefix": "https://example.com"
  },
  "platforms": {
    "spotify": "https://open.spotify.com/show/example",
    "google_podcasts": "https://podcasts.google.com?feed=example.com/feed.rss",
    "amazon_music": "https://music.amazon.com/example-podcast"
  },
  "players": {
    "all": ["itunes", "spotify", "radio_com", "google_podcasts", "overcast", "pocket_casts"]
  },
  "podcast": {
    "slug": "chartable-radio",
    "id": "593ed285-6e18-447c-8d61-44dbcbd907ba",
    "image_url": "https://example.com/image.jpg",
    "title": "My Podcast",
    "trackable_e_nabled": true
  },
  "remarketing_pixels": [
    {
      "id": "11b2f749-3a9f-4ef5-9fbe-ad04c1f0dbe6",
      "platform": "tiktok",
      "pixel": "C6001O479STF7B6J8NGG",
      "default_for_platform": true
    }
  ]
}

This endpoint updates a SmartLink.

HTTP Request

PATCH https://chartable.com/api/v1/smart_links/:id

Query Parameters

Parameter Type Description
archived Boolean Set to true to archive a SmartLink, and false to unarchive it. Archived SmartLinks will not count against your plan limit.
background_hex_color String The background color for the SmartLink’s landing page.
default_url String The redirect url when the SmartLink cannot find a conditional url
description String Text that appears on the SmartLink’s landing page.
episode_id String The id for the SmartLink’s episode.
name String The SmartLink’s name.
platforms Array The platforms to show on the SmartLink’s landing page.
players Array The players to show on the SmartLink’s landing page.
podcast_id String The id for the SmartLink’s podcast.
remarketing_pixels Array The IDs of remarketing pixels to attach to this SmartLink.
show_episode_player Boolean Should a player appear on the SmartLink’s landing page?
slug String The URL pathname. The slug cannot be changed if the SmartLink has clicks.
smart_link_domain_id String The id for the SmartLink’s domain.
social_media_image_url String The SmartLink’s social media image. Send an empty string to remove the image.
title String The text inside of the SmartLink’s landing page <title> tag.

Response Details

Name Type Description
id String The SmartLink’s unqiue ID.
name String The SmartLink’s name.
url String The SmartLink’s URL.
created_at DateTime When the SmartLink was created.
archived Boolean Is the SmartLink archived?
downloads_last_updated DateTime When was the SmartLink’s event data last updated?
social_media_image_url String The image people will see when you share this link on social media.
default_url String The URL users will be redirected to if we are unable to match a conditional redirect rule.
unqiue_downloads Integer The number of unique downloads.
unqiue_device_downloads Integer The number of unique device downloads.
conversions Integer The number of conversions.
new_device_downloads Integer The number of new device downloads.
clicks Integer The number of clicks.
unique_clicks Integer The number of unique clicks.
title String The landing page title.
description String The landing page description.
background_hex_color String The landing page background color.
show_episode_player Boolean Should the landing page have a player?
source_ids Array When the SmartLink URL contains an sid parameter, its value is stored here.
domain Object Information about the SmartLink Domain, if there is one.
domain.id String The SmartLink Domain’s unique ID.
domain.prefix String The SmartLink Domain’s secure domain name.
platforms Object The platforms that host the podcast or episode.
players Object The SmartLink’s players.
podcast Object Details about the podcast associated with this SmartLink.
podcast.display_image_url String The podcast’s cover art url.
podcast.id String The podcast’s unique ID.
podcast.slug String The podcast’s machine-friendly name.
podcast.title String The podcast’s title
podcast.trackable_enabled Boolean Does the podcast’s RSS feed have a valid Trackable prefix?
remarketing_pixels Array The Remarketing Pixels to fire when a user visits the SmartLink.
remarketing_pixels[i].id String The pixel’s unique ID.
remarketing_pixels[i].platform String The pixel’s platform.
remarketing_pixels[i].pixel String The pixel’s value.
remarketing_pixels[i].default_for_platform Boolean When true, this pixel is automatically added to new SmartLinks.

Teams

Team Demographics

require "net/http"

uri = URI("https://chartable.com/api/v1/demographics")
params = {scope: "team"}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "http://localhost:5555/api/v1/demographics" \
  -H "Authorization: Bearer ch_eyJ0ZWFtX2lkIjoiRTE1OTQiLCJjcmVhdGVkX2F0IjoiMjAyMi0wMS0yMSAxNTowNzozOCBVVEMifQ.cxAUedxY0lYfAjnvjUC-QKbwCM_kXZ9CGta7rPXUmrM" \
  -d scope=team
fetch("https://chartable.com/api/v1/demographics?scope=team", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "country_demographics": {
    "Trackable": [
      ["Country"],
      ["US", 1000]
      ["GB", 900]
    ],
    "Spotify": [
      ["Country"],
      ["US", 1000]
      ["GB", 900]
    ]
  },
  "gender_demographics": {
    "Spotify": [
      ["Gender"],
      ["Male", 1000],
      ["Female", 900],
      ["Not Binary", 800]
      ["Not Specified", 700]
    ]
  },
  "age_demographics": {
    "Spotify": [
      ["0-17", 10000],
      ["18-22", 9000],
      ["23-27", 8000],
      ["28-34", 7000],
      ["35-44", 6000],
      ["45-59", 5000],
      ["60-150", 4000],
      ["unknown", 3000]
    ]
  },
  "player_demographics": {
    "Trackable": [
      ["Player"],
      ["Apple Podcasts", 10000],
      ["Spotify", 9000],
      ["Pocket Casts", 8000],
      ["Overcast", 7000],
      ["Stitcher", 6000],
      ["PodcastAddict", 5000],
      ["CastBox", 4000],
      ["iHeartRadio", 3000],
      ["iTunes", 2000],
      ["TuneIn", 1000]
    ]
  }
}

This endpoint returns team emographics, which covers all podcasts and episodes.

HTTP Request

GET https://chartable.com/api/v1/demoraphics

Request Parameters

Parameter Type Required Description
scope String “” The level of data to return. Must be one of: podcasts, episodes, team.

Response Structure

Name Type Description
country_demographics Array The number of downloads organized by country. See Country Codes for a list of values.
gender_demographics Array The number of downloads organized by gender.
age_demographics Array The number of downloads organized by age.
player_demographics Array The number of downloads organized by player.

Team Episodes

require "net/http"

uri = URI("https://chartable.com/api/v1/team/episodes")
params = {page: 1, page_size: 10}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/team/episodes" \
  -H "Authorization: Bearer <your_access_key>" \
  -d page=1 \
  -d page_size=10
fetch("https://chartable.com/api/v1/team/episodes?page=1&page_size=10", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "metadata": {
    "total": 100,
    "page": 1,
    "page_size": 20,
    "pages": 5
  },
  "data": [
    {
      "id": "fd4fd0c1-7569-49f4-b691-d5c916e4f8e4",
      "url": "https://example.com/episode.mp3",
      "title": "Lorem Ipsum",
      "slug": "lorem-ipsum",
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin at porta enim, ac placerat libero. Integer aliquet egestas turpis eu accumsan. Vestibulum finibus purus vitae est mattis iaculis.",
      "published_at": "2022-01-01T12:00:00.000Z",
      "is_active": true,
      "image_url": "https://example.com/image.png",
      "length_in_seconds": 900
    }
  ]
}

This endpoint lists all reviews across all podcasts.

HTTP Request

GET https://chartable.com/api/v1/team/episodes

Request Parameters

Parameter Type Default Description
page Integer 1 Which page of episodes to return (if you have more than 20).
page_size Integer 20 How many episodes to return. This cannot be larger than the default value.
start_date DateTime NULL If set, only returns data for events that happened on or after this date.
end_date DateTime NULL If set, only returns data for events that happened on or before this date.
sort_by String “created_at” The attribute used to sort the episodes. Must be one of: created_at, name.
sort_desc Boolean true Set to false to sort in ascending order.

Response Structure

Name Type Description
id String The unique ID for this episode
title String The episode’s title
slug String The episode’s slug
description String The episode’s description
published_at DateTime The date and time this episode was published
is_active Boolean Is this episode currently available to download?
image_url String The image for this episode
length_in_seconds Integer The duration of the episode

Team Household Demographics

require "net/http"

uri = URI("https://chartable.com/api/v1/team/household_demographics")
params = {segment: "age"}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "http://localhost:5555/api/v1/team/household_demographics" \
  -H "Authorization: Bearer ch_eyJ0ZWFtX2lkIjoiRTE1OTQiLCJjcmVhdGVkX2F0IjoiMjAyMi0wMS0yMSAxNTowNzozOCBVVEMifQ.cxAUedxY0lYfAjnvjUC-QKbwCM_kXZ9CGta7rPXUmrM" \
  -d segment=age
fetch("https://chartable.com/api/v1/team/household_demographics?segment=age", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "metadata": {
    "measurement_date": "2022-01-01"
  },
  "data": [
    {
      "<segment>": "<description>",
      "reach_percentage": 6.86,
      "benchmark_reach_percentage": 8.26,
      "reach_percentage_against_benchmark": -1.4
    }
  ]
}

This endpoint returns household demographics across all of a team’s podcasts.

HTTP Request

GET https://chartable.com/api/v1/team/household_demographics

Request Parameters

Parameter Type Required Description
segment String Yes Must be one of: age, gender, education, household_income.

Response Structure

Name Type Description
metadata Object Information about the response.
metadata.measurement_date Date The date the demographics were collected.
data Object Demographic information.
data.<segment> String A description of this segment
data.reach_percentage Float Reach
data.benchmark_reach_percentage Float Benchmark Reach
data.reach_percentage_against_benchmark Float Reach Against Benchmark

Team Reviews

require "net/http"

uri = URI("https://chartable.com/api/v1/team/reviews")
params = {start_date:"2022-01-01", end_date: "2022-02-01"}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/team/reviews" \
  -H "Authorization: Bearer <your_access_key>" \
  -d start_date=2022-01-01 \
  -d end_date=2022-02-01
fetch("https://chartable.com/api/v1/team/reviews?start_date=2022-01-01&end_date=2022-02-01", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

[
  {
    "title": "My Review",
    "review": "This is my review.",
    "author_name": "Author Name",
    "posted_at": "2022-01-15T12:00:00.000Z",
    "provider": "Apple Podcasts",
    "rating": 5.0,
    "podcast_title": "Podcast Title"
  }
]

This endpoint lists all reviews across all podcasts.

HTTP Request

GET https://chartable.com/api/v1/team/reviews

Request Parameters

Parameter Type Default Description
page Integer 1 Which page of reviews to return (if you have more than 20).
page_size Integer 20 How many reviews to return. This cannot be larger than the default value.
start_date DateTime NULL Returns reviews that were posted on or after this date.
end_date DateTime NULL Return reviews that were posted on or before this date.
provider String “” Return reviews only from this provider. See providers for a list of values.
country String “” Return reviews only form this country. See country codes for a list of values.

Response Structure

Name Type Description
title String The review’s title
review String The review
author_name String The author’s name
posted_at DateTime When the review was posted
provider String The platform the review was posted on
rating Float The numerical rating
podcast_title String The podcast’s title

Team Reviews History

require "net/http"

uri = URI("https://chartable.com/api/v1/team/reviews_history")
params = {start_date:"2022-01-01", end_date: "2022-02-01"}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/team/reviews_history" \
  -H "Authorization: Bearer <your_access_key>" \
  -d start_date=2022-01-01 \
  -d end_date=2022-02-01
fetch("https://chartable.com/api/v1/team/reviews_history?start_date=2022-01-01&end_date=2022-02-01", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

[
  ["2022-01-01T00:00:00Z", 10],
  ["2022-01-03T00:00:00Z", 15],
  ["2022-01-07T00:00:00Z", 20],
  ["2022-01-10T00:00:00Z", 25],
  ["2022-01-15T00:00:00Z", 20],
  ["2022-01-18T00:00:00Z", 15]
]

This endpoint lists the number of reviews posted each day.

HTTP Request

GET https://chartable.com/api/v1/team/reviews_history

Request Parameters

Parameter Type Default Description
start_date DateTime NULL Returns reviews that were posted on or after this date.
end_date DateTime NULL Return reviews that were posted on or before this date.
provider String “” Return reviews only from this provider. See providers for a list of values.
country String “” Return reviews only form this country. See country codes for a list of values.

Response Structure

Type Description
array An array of how many reviews were posted each day.
array[0] The date.
array[1] The number of reviews posted on that date.

Team Reviews Summary

require "net/http"

uri = URI("https://chartable.com/api/v1/team/reviews_summary")
params = {start_date:"2022-01-01", end_date: "2022-02-01"}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/team/reviews_summary" \
  -H "Authorization: Bearer <your_access_key>" \
  -d start_date=2022-01-01 \
  -d end_date=2022-02-01
fetch("https://chartable.com/api/v1/team/reviews_summary?start_date=2022-01-01&end_date=2022-02-01", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
   "monthly_growth": "50.0%",
   "ratings_count": 20000,
   "rating": 4.5,
   "total_filtered_reviews": 100,
   "total_reviews": 5000,
   "providers": [
      "Apple Podcasts",
      "Stitcher"
   ],
   "countries": [
      "Canada",
      "France",
      "Germany",
      "Great Britain",
      "United States of America"
   ]
}

This endpoint returns aggregated review metrics across all podcasts.

HTTP Request

GET https://chartable.com/api/v1/team/reviews_summary

Request Parameters

Parameter Type Default Description
start_date DateTime NULL Returns reviews that were posted on or after this date.
end_date DateTime NULL Return reviews that were posted on or before this date.
provider String “” Return reviews only from this provider. See providers for a list of values.
country String “” Return reviews only form this country. See country codes for a list of values.

Response Structure

Name Type Description
monthly_growth String How many more reviews do you have this month compared to last month?
ratings_count Integer The number of ratings across all podcasts.
rating Float The average rating across all podcasts.
total_reviews Integer The number of reviews across all podcasts.
total_filtered_reviews Integer The number of reviews that match the request parameters across all podcasts.
providers Array All of the providers where reviews were posted. See providers for a list of values.
countries Array All of the countries where reviews were posted. See country codes for a list of values.

Team Statistics

require "net/http"

uri = URI("https://chartable.com/api/v1/team/statistics")
params = {}
headers = {
    "Authorization" => "Bearer <your_access_key>",
    "Content-Type" => "application/json",
    "Accept" => "application/json"
}

http = Net::HTTP.get(uri.host, uri.port)
response = http.get(uri.path, params, headers)
curl -X GET "https://chartable.com/api/v1/team/statistics" \
  -H "Authorization: Bearer <your_access_key>"
fetch("https://chartable.com/api/v1/team/statistics", {
  method: "GET",
  headers: {"Authorization": "Bearer <your_access_key>"}
})
.then((response) => response.json())
.then((data) => console.log('Success:', data));

JSON Response Structure

{
  "reporting_window": 30,
  "rating": 4.5,
  "downloads": 1000,
  "downloads_growth": 50,
  "iab_listeners": 750,
  "iab_listeners_growth": 50,
  "youtube_views": 500,
  "youtube_views_growth ": 50,
  "reviews": 25,
  "reviews_growth": 50
}

This endpoint returns aggregated statistics for all of a team’s podcasts.

HTTP Request

GET https://chartable.com/api/v1/team/statistics

Response Structure

Name Type Description
reporting_window Integer The number of days the statistics cover.
rating Integer The average rating across all podcasts.
downloads Integer The total number of podcast downloads.
downloads_growth Integer How much the downloads have grown over the previous reporting window.
iab_listeners Integer The number of confirmed IAB downloads.
iab_listeners_growth Integer How much the IAB downloads have grown over the previous reporting window.
youtube_views Integer The number of YouTube views.
youtube_views_growth Integer How much the YouTube views have grown over the previous reporting window.
reviews Integer The total number of reviews.
reviews_growth Integer How much the number of reviews have grown over the previous reporting window.