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

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.

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.

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

// 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")

// 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")

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

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

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

• 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
        }
    }
}

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

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.