Skip to content

Latest commit

 

History

History
712 lines (533 loc) · 24.4 KB

README.md

File metadata and controls

712 lines (533 loc) · 24.4 KB
Raw

podcast4j is an open source full implemented Java client for podcastindex.org

GitHub last commit GitHub issues GitHub pull requests GitHub tweet

About • Getting Started • Usages • Features • Support • Keep in Touch • License

About

The PodcastIndex exists to preserve, protect and extend the open, independent podcasting ecosystem and podcast4j is an API client of podcastindex. You're able to interract with PodcastIndex through podcast4j.

Getting Started

before getting started, you have to define dependency on your pom.xml file.

<dependencies>
    <dependency>
        <groupId>io.github.yusufyilmazfr</groupId>
        <artifactId>podcast4j</artifactId>
        <version>1.0.2</version>
    </dependency>
</dependencies>

Before use podcast4j, we have to create an PodcastIndex account and generate secret and auth key on podcastindex.org. You are able to create an account on podcastindex

After generating secret and auth key, you're able to create Podcast4jServiceFactory instance to accessing podcastindex API end-points.

import com.github.yusufyilmazfr.podcast4j.config.Config;
import com.github.yusufyilmazfr.podcast4j.factory.Podcast4jServiceFactory;

//..

Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);

There are several required fields such as secret and authKey but you're able to add another fields such as; userAgent and timeOut these fields are default values. It is up to developer who uses this client. If you want to use these fields, you can change these codes that are below.

import com.github.yusufyilmazfr.podcast4j.config.Config;
import com.github.yusufyilmazfr.podcast4j.factory.Podcast4jServiceFactory;

//..

Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .userAgent("SuperPodcastPlayer/1.8")
                      .timeOut(10000)
                      .build();

Podcast4jServiceFactory factory = Podcast4jServiceFactory.with(config);

We are using timeOut field in HTTP cals, default time out is 5 seconds.

Usages

This section is all about podcast4j client usages with provided services. Before getting started every service is generated from Podcast4jServiceFactory, so we have to create first Podcast4jServiceFactory then create another service that we need.Podcast4jServiceFactory provides us services. Example codes point this.

Search Service

Search Podcasts: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jSearchService searchService = serviceFactory.getSearchService();

SearchPodcastsByTermArg arg = SearchPodcastsByTermArg.builder()
                                                     .q(CODEFICTION_PODCAST_TITLE) // CODEFICTION_PODCAST_TITLE = "Codefiction Podcast";
                                                     .build();

List<Podcast> podcasts = searchService.searchPodcastsByTerm(arg);
Search Podcasts by Title: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jSearchService searchService = serviceFactory.getSearchService();

SearchPodcastsByTitleArg arg = SearchPodcastsByTitleArg.builder()
                                                       .q(CODEFICTION_PODCAST_TITLE) // CODEFICTION_PODCAST_TITLE = "Codefiction Podcast";
                                                       .similar(Boolean.TRUE)
                                                       .build();

List<Podcast> podcasts = searchService.searchPodcastsByTitle(arg);

Podcast Service

Get Podcast By Feed ID: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jPodcastService podcastService = serviceFactory.getPodcastService();

Podcast podcast = podcastService.getPodcastByFeedId(CODEFICTION_FEED_ID); // CODEFICTION_FEED_ID = 53723;
Get Podcast By Feed URL: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jPodcastService podcastService = serviceFactory.getPodcastService();

Podcast podcast = podcastService.getPodcastByFeedURL(CODEFICTION_FEED_URL); // CODEFICTION_FEED_URL = "https://feeds.simplecast.com/3Ro7Vrg6";
Get Podcast By GUID: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jPodcastService podcastService = serviceFactory.getPodcastService();

Podcast podcast = podcastService.getPodcastByGUID(CODEFICTION_GUID_ID); // CODEFICTION_GUID_ID = "d2e4c26d-0626-5d32-9634-987be192f841";
Get Podcast By iTunes ID: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jPodcastService podcastService = serviceFactory.getPodcastService();

Podcast podcast = podcastService.getPodcastByiTunesID(CODEFICTION_iTUNES_ID); // CODEFICTION_iTUNES_ID = 1172391831L;
Get Podcasts By Medium: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jPodcastService podcastService = serviceFactory.getPodcastService();

List<Podcast> podcasts = podcastService.getPodcastsByMedium(MediumType.MUSIC);
Get Trending Podcasts: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jPodcastService podcastService = serviceFactory.getPodcastService();

TrendPodcastsArg arg = TrendPodcastsArg.builder()
                                       .lang("en")
                                       .cat("News")
                                       .notCat("Entertainment")
                                       .max(5)
                                       .build();

List<TrendPodcast> trendPodcasts = podcastService.getTrendPodcasts(arg);
Get Dead Podcasts: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jPodcastService podcastService = serviceFactory.getPodcastService();

List<DeadPodcast> deadPodcasts = podcastService.getDeadPodcasts();

Episode Service

Get Episodes By Feed ID: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jEpisodeService episodeService = serviceFactory.getEpisodeService();

ByFeedIdArg arg = ByFeedIdArg.builder()
                             .id(CODEFICTION_FEED_ID) // CODEFICTION_FEED_ID = 53723;
                             .max(10)
                             .build();

List<Episode> episodes = episodeService.getEpisodesByFeedId(arg);
Get Episodes By Feed URL: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jEpisodeService episodeService = serviceFactory.getEpisodeService();

ByFeedURLArg arg = ByFeedURLArg.builder()
                               .url(CODEFICTION_FEED_URL) // CODEFICTION_FEED_URL = "https://feeds.simplecast.com/3Ro7Vrg6";
                               .max(10)
                               .build();

List<Episode> episodes = episodeService.getEpisodesByFeedURL(arg);
Get Episode By GUID: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jEpisodeService episodeService = serviceFactory.getEpisodeService();

ByGUIDArg arg = ByGUIDArg.builder()
                         .guid("PC2084")
                         .feedId(920666)
                         .build();

Episode episode = episodeService.getEpisodeByGUID(arg);
Get Episode By ID: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jEpisodeService episodeService = serviceFactory.getEpisodeService();

ByIdArg arg = ByIdArg.builder()
                     .id(CODEFICTION_EPISODE_ID) // CODEFICTION_EPISODE_ID = 2146512028L; // 513 - Fazla mesai yazılımcının kaderi mi?
                     .fulltext(Boolean.TRUE)
                     .build();

// Actual
Episode episode = episodeService.getEpisodeById(arg);
Get Episodes By iTunes ID: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jEpisodeService episodeService = serviceFactory.getEpisodeService();

ByiTunesArg arg = ByiTunesArg.builder()
                             .id(CODEFICTION_iTUNES_ID) // CODEFICTION_iTUNES_ID = 1172391831L;
                             .max(10)
                             .build();

List<Episode> episodes = episodeService.getEpisodesByiTunesId(arg);
Get Live Episodes: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jEpisodeService episodeService = serviceFactory.getEpisodeService();

List<Episode> episodes = episodeService.getLiveEpisodes(5);
Get Random Episodes: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jEpisodeService episodeService = serviceFactory.getEpisodeService();

RandomEpisodesArg arg = RandomEpisodesArg.builder()
                                         .lang("tr")
                                         .cat("Technology")
                                         .max(5)
                                         .build();

List<Episode> episodes = episodeService.getRandomEpisodes(arg);

Category Service

Get Categories: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jCategoryService categoryService = serviceFactory.getCategoryService();

List<Category> categories = categoryService.getAll();

or you're able to use like fluent version. ✨🫶

Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

List<Category> categories = Podcast4jServiceFactory.with(config)
                                                   .getCategoryService()
                                                   .getAll();

Recent Service

Get Recent Episodes: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jRecentService recentService = serviceFactory.getRecentService();

EpisodesArg arg = EpisodesArg.builder()
                             .max(5)
                             .excludeString("MP3")
                             .build();
 
List<Episode> episodes = recentService.getEpisodes(arg);
Get Recent Feeds: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jRecentService recentService = serviceFactory.getRecentService();

FeedsArg arg = FeedsArg.builder()
                       .max(1)
                       .lang("tr")
                       .cat("technology")
                       .build();

List<Feed> feeds = recentService.getFeeds(arg);
Get New Feeds Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jRecentService recentService = serviceFactory.getRecentService();

NewFeedsArg arg = NewFeedsArg.builder()
                             .max(1)
                             .build();

List<NewFeed> feeds = recentService.getNewFeeds(arg);
Get Soundbites: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jRecentService recentService = serviceFactory.getRecentService();

List<SoundBite> soundBites = recentService.getSoundBites(5);

Apple Replacement Service

Search on Apple iTunes: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jAppleReplacementService appleReplacementService  = serviceFactory.getAppleReplacementService();

List<AppleReplacementSearch> searches = appleReplacementService.search("batman");
Lookup on Apple iTunes: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jAppleReplacementService appleReplacementService  = serviceFactory.getAppleReplacementService();

List<AppleReplacementSearch> searches = appleReplacementService.lookup(CODEFICTION_iTUNES_ID, null); // CODEFICTION_iTUNES_ID = 1172391831L;

Value Service

Get Value By Feed ID: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jValueService valueService = serviceFactory.getValueService();

Value value = valueService.getValueByFeedId(PODCAST_INDEX_FEED_ID_FOR_VALUE); // PODCAST_INDEX_FEED_ID_FOR_VALUE = 920666;
Get Value By Feed URL: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jValueService valueService = serviceFactory.getValueService();

Value value = valueService.getValueByFeedURL(PODCAST_INDEX_FEED_URL_FOR_VALUE); // PODCAST_INDEX_FEED_URL_FOR_VALUE = "https://mp3s.nashownotes.com/pc20rss.xml";

Hub Service

Notify Changes By FEED Id: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jHubService hubService = serviceFactory.getHubService();

hubService.notifyByFeedId(CODEFICTION_FEED_ID); // CODEFICTION_FEED_ID = 53723;
Notify Changes By FEED URL: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jHubService hubService = serviceFactory.getHubService();

hubService.notifyByFeedURL(CODEFICTION_FEED_URL); // CODEFICTION_FEED_URL = "https://feeds.simplecast.com/3Ro7Vrg6";

Stats Service

Get PodcastIndex Stats: Click Here to See 
Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Podcast4jServiceFactory serviceFactory = Podcast4jServiceFactory.with(config);
Podcast4jStatsService statsService = serviceFactory.getStatsService();

Stats stats = statsService.get();

or you're able to use like fluent version. ✨🫶

Config config = Config.builder()
                      .secret("<SECRET_KEY>")
                      .authKey("<AUTH_KEY>")
                      .build();

Stats stats = Podcast4jServiceFactory.with(config)
                                     .getStatsService()
                                     .get();

Features

🔰 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 ✔️
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 ✔️ ... ⌛

Support

Keep in Touch

Reach out to me via the GitHub, LinkedIn or Twitter

License

yusufyilmazfr/podcast4j is licensed under the MIT License.