Lastcast for developers

Learn about our API and how you can integrate your apps with Lastcast

Lastcast API Introduction

What you can do with the API

Lastcast helps people collect their podcast listening data. If you're developing a podcast client, you can integrate our API so that users can automatically have their listened episodes scrobbled when they listen to podcasts using your app. If you're a hacker and your favorite podcast client has no Lastcast support yet, you might find this API handy to write some sort of automation using instead.

The basic principle is very simple: You send so called "Scrobble Events" to the Lastcast API. We then match those events to the corresponding podcast episodes in our library and they show up as "listened" on the user's profile.

The API is available to everyone and can easily be integrated in scripts and native apps. We currently provide two sample implementations that can be used as inspiration. All of them are open source and hosted on Github.

  • Lastcast for Apple Podcasts (Native Mac app, SwiftUI)
  • Lastcast for Overcast (Python script)

If you are not sure the current API is sufficient for you, please don't hesitate to reach out: hello@lastcast.fm. We are more than happy to discuss the API, and provide additional features if needed. Right now it is a very early version of our public API, tailor-made to our own usage.

Authentication

The API token needed for using the API

Every user of Lastcast has an API token in their user settings that can be used to access the API. If you have problems with your API token or need to change it please contact us.

This token has to be sent in every API request in the header field "Lastcast-Api-Token", see the example curl request below.

Submit scrobbles

This API route is used to submit "scrobble events" to the Lastcast API

Important note about timestamps

Lastcast relies on having timestamps of when the episode was listened to. This is used to show it correctly on the website and determine weekly charts and listening heatmaps. A challenge with some podcast clients is that they don't offer historic timestamps (Overcast). In this case the best strategy is to submit your scrobbles as often as possible, for example by using a hourly cronjob.


Below you can find two examples of how to submit scrobble events to the API. Either by iTunes ID (preferred) or by episode URL. A single request can contain one or several events at once. You can also submit a scrobble event for the same episode multiple times with different percentages/timestamps, in case you have access to fine grained data like that. This is the structure of the POST request:

    1 curl -X "POST" "https://lastcast.fm/api/v1/scrobbles" \
    2      -H 'Content-Type: application/json' \
    3      -H 'Accept: application/json' \
    4      -H 'Lastcast-Api-Token: ApiKey-v1 changeme' \
      5      -d $'{
    6   "client": "Lastcast for Mac",
    7   "events": []
    8 }'

Match by iTunes ID

Ideally, you know the iTunes ID of the episode, as our data is mainly based on the Apple Podcast directory.
    1 {
    2   "client": "Lastcast for Mac",
    3   "events": [
    4     {
    5       "timestamp": "2018-12-10 14:41:17",
    6       "percentage": 50,
    7       "matching_hints": {
    8         "itunes": "1000478506748"
    9       }
   10     },
   11     {
   12       "timestamp": "2018-12-10 14:41:17",
   13       "percentage": 100,
   14       "matching_hints": {
   15         "itunes": "1000476814426"
   16       }
   17     },
   18     {
   19       "timestamp": "2018-12-10 14:41:17",
   20       "percentage": 10,
   21       "matching_hints": {
   22         "itunes": "1000477644574"
   23       }
   24     }
   25   ]
   26 }

Match by URL

If the iTunes ID of the episode is unknown, we can still try to match it by URL of the episode (the actual MP3/AAC/etc. – not the website URL).
    1 {
    2   "client": "Lastcast for Mac",
    3   "events": [
    4     {
    5       "timestamp": "2018-12-05 14:41:17",
    6       "percentage": 81,
    7       "matching_hints": {
    8         "episode_url": "https://traffic.libsyn.com/secure/shiftf1/106_mixdown.mp3?dest-id=493648"
    9       }
   10     },
   11     {
   12       "timestamp": "2018-12-10 14:41:17",
   13       "percentage": 100,
   14       "matching_hints": {
   15         "episode_url": "https://traffic.libsyn.com/secure/shiftf1/109_mixdown.mp3?desat-id=493648"
   16       }
   17     }
   18   ]
   19 }

Response

The API Response.

The expected status code is: 200. In the response you can see all episodes that were successfully scrobbled. Episodes that we could not find in our data will be listed in the "unmatched" array, and in case of errors those are listed in the "errors" array. Should you get an "unmatched" response even though the episode is available on Apple Podcasts, please try again in a couple of hours – we might just not have refreshed our data yet. If the issue persist, let us know! or let us know.

    1 {
    2   "success": [
    3     {
    4       "percentage": 81,
    5       "timestamp": "2018-12-10 14:30:17",
    6       "matching_hints": {
    7         "itunes": "1000476027689"
    8       }
    9     }
   10   ],
   11   "error": [],
   12   "unmatched": [
   13     {
   14       "percentage": 81,
   15       "timestamp": "2018-12-10 14:41:17",
   16       "matching_hints": {
   17         "itunes": "1000476087685"
   18       }
   19     },
   20     {
   21       "percentage": 81,
   22       "timestamp": "2018-12-10 14:41:17",
   23       "matching_hints": {
   24         "itunes": "1000476087689"
   25       }
   26     }
   27   ]
   28 }