PodcastIndex-SDK

Jump to: About | Download | How to use | Advanced | Roadmap | License

---

About

Unofficial Type-safe PodcastIndex SDK for Kotlin Multiplatform Supporting Android/Desktop/iOS platforms.

Podcast Index is a large, categorized, and free index of podcasts. It offers a REST API to access the index. This SDK is a wrapper around the API that offers idiomatic Kotlin API plus handling things like Authentication, retrying failed authenticated requests in odd scenarios, Logging, Serialization, and more for developers looking to build podcast experiences.

Download

Add the Maven Central repository if it is not already there:

repositories {
   mavenCentral()
}

In Kotlin Multiplatform projects, add the dependency:

commonMain {
    dependencies {
        // If you're using Ktor 2
        implementation("io.github.mr3y-the-programmer:podcastindex-sdk-ktor2:<latest-version>")
        // Or if you're using Ktor 3
        implementation("io.github.mr3y-the-programmer:podcastindex-sdk-ktor3:<latest-version>")
    }
}

Or in a single-platform project:

dependencies {
    // If you're using Ktor 2
    implementation("io.github.mr3y-the-programmer:podcastindex-sdk-ktor2:<latest-version>")
    // Or if you're using Ktor 3
    implementation("io.github.mr3y-the-programmer:podcastindex-sdk-ktor3:<latest-version>")
}

Compatibility:

• Java 8+.
• Kotlin 1.9+.
• Ktor 2 & 3.

How to use

1. Initialize client instance by calling PodcastIndexClient with your credentials:

val client = PodcastIndexClient(BuildConfig.API_KEY, BuildConfig.API_SECRET, userAgent = "MyPodcastApp/1.2")

That's it, now you're ready to start interacting with different SDK services, PodcastIndexClient function also takes an optional config lambda parameter which allows you to enable/disable some properties, See Advanced section for more details

Search Service

Search Podcasts by term: Click Here to See

// This method takes other optional parameters like limit, includeSimilar...etc that allow you to fine-tune the search result.
val result: MultiplePodcastsResult = client.search.forPodcastsByTerm(term = "android")

Search Podcasts by title: Click Here to See

// This method takes other optional parameters like limit, includeSimilar...etc that allow you to fine-tune the search result.
val result: MultiplePodcastsResult = client.search.forPodcastsByTitle(title = "Talking Kotlin")

Search Episodes by person: Click Here to See

val result: MultipleEpisodesResult = client.search.forEpisodesByPerson(name = "john doe")

Search Music Podcasts by term: Click Here to See

val result: MultiplePodcastsResult = client.search.forMusicPodcastsByTerm(term = "music")

Similarly, accessing other services/endpoints follows the same approach.

Advanced

• Enable logging to get better insights about outgoing requests which might be helpful for debugging (Default is false):

val client = PodcastIndexClient(...) {
    enableLogging = if (BuildConfig.DEBUG) true else false
}

Sensitive information like API_KEY & API_SECRET are masked and won't be printed out in logs so, you can enable this safely.

• Change the default tag used for logging (Default is "PodcastIndexSDK"):

val client = PodcastIndexClient(...) {
    loggingTag = "MyCustomTag"
}

• Specify the max number of retries when a request fails (Default is 3):

val client = PodcastIndexClient(...) {
    maxRetries = 5
}

• Enabling/Disabling request timeout (Default is true):

val client = PodcastIndexClient(...) {
    enableTimeout = false
}

• Specify the default timeout in milliseconds (Default is 10 seconds):

val client = PodcastIndexClient(...) {
    defaultTimeout = 5_000L // 5 seconds
}

• Customize or choose a different HTTP client which is useful if you use a certain HTTP client instance in your app with special configuration and you want to make the SDK reuse the same instance:

val client = PodcastIndexClient(...) {
    httpClient(Okhttp) {
        // Customize OkHttp client configuration
        engine {
            preconfigured = okHttpClientInstance
        }
    }
}

Support table

Some endpoints are still work-in-progress and not implemented yet (⌛)

	🔰 Status		🔰 Status
Search		Recent
Search Podcasts	✔️	Get Recent Episodes	✔️
Search Podcasts by Title	✔️	Get Recent Feeds	✔️
Search Episodes by Person	✔️	Get New Feeds	✔️
Search Music Podcasts	✔️	Get Soundbites	✔️
Podcast		Episodes
Get Podcast By Feed ID	✔️	Get Episodes By Feed ID	✔️
Get Podcast By Feed URL	✔️	Get Episodes By Feed URL	✔️
Get Podcast By GUID	✔️	Get Episode By GUID	✔️
Get Podcasts By TAG	⌛	Get Episode By ID	✔️
Get Podcast By iTunes ID	✔️	Get Episodes By iTunes ID	✔️
Get Podcasts By Medium	✔️	Get Live Episodes	✔️
Get Trending Podcasts	✔️	Get Random Episodes	✔️
Get Dead Podcasts	⌛	Get Episodes by Feed GUID	✔️
Apple Replacement		Value
Search on Apple iTunes	⌛	Get Value By Feed ID	✔️
Lookup on Apple iTunes	⌛	Get Value By Feed URL	✔️
Stats		Category
Get Current Stats	✔️	Get Categories	✔️
Hub		Add Service
Notify Changes By Feed Id	⌛	...	⌛
Notify Changes By Feed URL	⌛	...	⌛

License

Copyright 2024 MR3Y

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.