podcastindex

README

podcastindex

Go library for accessing the API of PodcastIndex. You will need to have an account for actually using the API.

When unsure how certain parameters work take a look the API documentation from PodcastIndex.

Example

This code will show you the latest episodes of a podcast you just searched:

package main

import (
    "fmt"
    "log"
    "time"

    "github.com/TheHippo/podcastindex"
)

func main() {
    fmt.Println("ok")

    c := podcastindex.NewClient("APIKEY", "APISECRET")
    podcasts, err := c.Search("Crime in sports")
    if err != nil {
        log.Fatal(err)
    }
    podcast := podcasts[0]
    episodes, err := c.EpisodesByFeedID(podcast.ID, 0, time.Time{})
    if err != nil {
        log.Fatal(err)
    }
    for _, episode := range episodes {
        fmt.Printf("%s: %s\n", podcast.Author, episode.Title)
        fmt.Printf("%s\n", episode.Duration)
    }
}

Status

There are only two things missing:

• Soundbites
• Publishing API, because I cannot test it

Documentation

Index

• Constants
• type Client
  • func NewClient(apiKey, apiSecret string) *Client
  • func NewClientWithConfig(apiKey, apiSecret string, config Config, client *http.Client) *Client
  • func (c *Client) EpisodeByID(id uint) (*Episode, error)
  • func (c *Client) EpisodesByFeedID(id uint, max uint, since time.Time) ([]*Episode, error)
  • func (c *Client) EpisodesByFeedURL(feedURL string, max uint, since time.Time) ([]*Episode, error)
  • func (c *Client) EpisodesByITunesID(id uint, max uint, since time.Time) ([]*Episode, error)
  • func (c *Client) NewPodcasts() ([]*NewPodcast, error)
  • func (c *Client) PodcastByFeedID(id uint) (*Podcast, error)
  • func (c *Client) PodcastByFeedURL(url string) (*Podcast, error)
  • func (c *Client) PodcastByITunesID(id uint) (*Podcast, error)
  • func (c *Client) RandomEpisodes(languages, categories, notCategories []string, max uint) ([]*Episode, error)
  • func (c *Client) RecentEpisodes(before uint, max uint, exclude string) ([]*Episode, error)
  • func (c *Client) RecentPodcasts(languages, categories, notCategories []string, max uint, since time.Time) ([]*RecentPodcast, error)
  • func (c *Client) Search(term string) ([]*Podcast, error)
  • func (c *Client) SearchC(term string, clean bool, max uint) ([]*Podcast, error)
• type Config
• type Duration
  • func (d Duration) MarshalJSON() ([]byte, error)
  • func (d Duration) String() string
  • func (d *Duration) UnmarshalJSON(s []byte) (err error)
• type Episode
• type NewPodcast
• type Podcast
• type RecentPodcast
• type Time
  • func (t Time) MarshalJSON() ([]byte, error)
  • func (t Time) String() string
  • func (t *Time) UnmarshalJSON(s []byte) (err error)

Constants

const (
	// UserAgent that will be sent to the podcastindex API
	UserAgent = "go-podcastindex-library"
	// BaseURL for the API
	BaseURL = "https://api.podcastindex.org/api/1.0/"
)

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client connects to the podcastindex API

func NewClient

func NewClient(apiKey, apiSecret string) *Client

NewClient creates an API client with the default configuration

func NewClientWithConfig

func NewClientWithConfig(apiKey, apiSecret string, config Config, client *http.Client) *Client

NewClientWithConfig creates an API client with an custom configuration

func (*Client) EpisodeByID

func (c *Client) EpisodeByID(id uint) (*Episode, error)

EpisodeByID return a single episode by its id

func (*Client) EpisodesByFeedID

func (c *Client) EpisodesByFeedID(id uint, max uint, since time.Time) ([]*Episode, error)

EpisodesByFeedID returns episodes for a podcast by its id

- max = number of episodes to return, if max is 0 the default number of episodes will be returned

- since = only return episodes since that time. Set time to zero to not filter by time

func (*Client) EpisodesByFeedURL

func (c *Client) EpisodesByFeedURL(feedURL string, max uint, since time.Time) ([]*Episode, error)

EpisodesByFeedURL returns episodes for a podcast by its feed URL

- max = number of episodes to return, if max is 0 the default number of episodes will be returned

- since = only return episodes since that time. Set time to zero to not filter by time

func (*Client) EpisodesByITunesID

func (c *Client) EpisodesByITunesID(id uint, max uint, since time.Time) ([]*Episode, error)

EpisodesByITunesID returns episodes for a podcast by its iTunes id

- max = number of episodes to return, if max is 0 the default number of episodes will be returned

- since = only return episodes since that time. Set time to zero to not filter by time

func (*Client) NewPodcasts

func (c *Client) NewPodcasts() ([]*NewPodcast, error)

NewPodcasts return up to 1000 podcasts that have been added to the database over the last week

func (*Client) PodcastByFeedID

func (c *Client) PodcastByFeedID(id uint) (*Podcast, error)

PodcastByFeedID returns general information about a podcast by its id

func (*Client) PodcastByFeedURL

func (c *Client) PodcastByFeedURL(url string) (*Podcast, error)

PodcastByFeedURL returns general information about a podcast by its feed URL

func (*Client) PodcastByITunesID

func (c *Client) PodcastByITunesID(id uint) (*Podcast, error)

PodcastByITunesID returns general information about a podcast by its ITune id

func (*Client) RandomEpisodes

func (c *Client) RandomEpisodes(languages, categories, notCategories []string, max uint) ([]*Episode, error)

RandomEpisodes returns a random episode

categories and notCategories can be combined

- languages = the languages the episodes should be in. "unknown" for when the language is not known. Leave empty if languages does not matter

- categories = name of the category or categories the episodes should be in. Leave empty if categories do not matter

- notCategories = name of the category or categories the episodes should not be in. Leave empty if categories do not matter

- max = number of episodes to return, if max is 0 the default number of episodes will be returned, the default is 1

func (*Client) RecentEpisodes

func (c *Client) RecentEpisodes(before uint, max uint, exclude string) ([]*Episode, error)

RecentEpisodes returns the last episodes across the entire database

- before = only return episodes that are older than the episode with this id. set to zero to ignore

- excludeString = exclude episodes with this string in title or url. Leave empty for no filter

- max = number of episodes to return, if max is 0 the default number of episodes will be returned, the default is 10

func (*Client) RecentPodcasts

func (c *Client) RecentPodcasts(languages, categories, notCategories []string, max uint, since time.Time) ([]*RecentPodcast, error)

RecentPodcasts returns the last updated podcasts

- languages = the languages the podcast should be in. "unknown" for when the language is not known. Leave empty if languages does not matter

- categories = name of the category or categories the podcast should be in. Leave empty if categories do not matter

- notCategories = name of the category or categories the podcast should not be in. Leave empty if categories do not matter

- max = number of podcasts to return, if max is 0 the default number of episodes will be returned, the default is 40

- since = only return episodes since that time. Set time to zero to not filter by time

func (*Client) Search

func (c *Client) Search(term string) ([]*Podcast, error)

Search for podcasts, authors or owners

func (*Client) SearchC

func (c *Client) SearchC(term string, clean bool, max uint) ([]*Podcast, error)

SearchC for searching with more options than Search

- clean for non explicit feeds according to itunes:explicit

- fullBody to return the more then 100 characters in the descriptions

- max for the number of results, when set to 0 it uses the API default

type Config

type Config struct {
	BaseURL   string
	UserAgent string
}

Config holds the configuration for the API client

var DefaultConfig *Config = &Config{
	BaseURL:   BaseURL,
	UserAgent: UserAgent,
}

DefaultConfig is used when NewClient is used to create an API client

type Duration

type Duration time.Duration

Duration is a crutch to get time.Duration parsed from the API results

func (Duration) MarshalJSON

func (d Duration) MarshalJSON() ([]byte, error)

MarshalJSON is used to convert the duration to JSON

func (Duration) String

func (d Duration) String() string

String returns d as a formated string

func (*Duration) UnmarshalJSON

func (d *Duration) UnmarshalJSON(s []byte) (err error)

UnmarshalJSON is used to convert the duration from JSON

type Episode

type Episode struct {
	ID              int      `json:"id"`
	Title           string   `json:"title"`
	Link            string   `json:"link"`
	Description     string   `json:"description"`
	GUID            string   `json:"guid"`
	DatePublished   Time     `json:"datePublished"`
	DateCrawled     Time     `json:"dateCrawled"`
	EnclosureURL    string   `json:"enclosureUrl"`
	EnclosureType   string   `json:"enclosureType"`
	EnclosureLength int      `json:"enclosureLength"`
	Duration        Duration `json:"duration"`
	Explicit        int      `json:"explicit"`
	Episode         int      `json:"episode"`
	EpisodeType     string   `json:"episodeType"`
	Season          int      `json:"season"`
	Image           string   `json:"image"`
	FeedItunesID    int      `json:"feedItunesId"`
	FeedImage       string   `json:"feedImage"`
	FeedID          int      `json:"feedId"`
	FeedLanguage    string   `json:"feedLanguage"`
	ChaptersURL     string   `json:"chaptersUrl"`
	TranscriptURL   string   `json:"transcriptUrl"`
}

Episode contains all information about a single podcast episode returned from the podcastindex API

type NewPodcast

type NewPodcast struct {
	ID          int    `json:"id"`
	URL         string `json:"url"`
	TimeAdded   Time   `json:"timeAdded"`
	Status      string `json:"status"`
	ContentHash string `json:"contentHash"`
	Language    string `json:"language"`
}

NewPodcast contains data for a newly added podcast

type Podcast

type Podcast struct {
	ID                     uint            `json:"id"`
	Title                  string          `json:"title"`
	URL                    string          `json:"url"`
	OriginalURL            string          `json:"originalUrl"`
	Link                   string          `json:"link"`
	Description            string          `json:"description"`
	Author                 string          `json:"author"`
	OwnerName              string          `json:"ownerName"`
	Image                  string          `json:"image"`
	Artwork                string          `json:"artwork"`
	LastUpdateTime         Time            `json:"lastUpdateTime"`
	LastCrawlTime          Time            `json:"lastCrawlTime"`
	LastParseTime          Time            `json:"lastParseTime"`
	LastGoodHTTPStatusTime Time            `json:"lastGoodHttpStatusTime"`
	LastHTTPStatus         int             `json:"lastHttpStatus"`
	ContentType            string          `json:"contentType"`
	ItunesID               int             `json:"itunesId"`
	Generator              string          `json:"generator"`
	Language               string          `json:"language"`
	Type                   int             `json:"type"`
	Dead                   int             `json:"dead"`
	CrawlErrors            int             `json:"crawlErrors"`
	ParseErrors            int             `json:"parseErrors"`
	Categories             map[uint]string `json:"categories"`
}

Podcast contains all informations about a podcast returned from the podcastindex API

type RecentPodcast

type RecentPodcast struct {
	ID                    int    `json:"id"`
	URL                   string `json:"url"`
	Title                 string `json:"title"`
	NewestItemPublishTime Time   `json:"newestItemPublishTime"`
	Description           string `json:"description"`
	Image                 string `json:"image"`
	ItunesID              int    `json:"itunesId"`
	Language              string `json:"language"`
}

RecentPodcast contains all information about an recently updated podcast

type Time

type Time time.Time

Time is a crutch to get the timestamp parsed correctly there is for obvious reasons no information on the timezone

func (Time) MarshalJSON

func (t Time) MarshalJSON() ([]byte, error)

MarshalJSON is used to convert the timestamp to JSON

func (Time) String

func (t Time) String() string

String returns t as a formatted string

func (*Time) UnmarshalJSON

func (t *Time) UnmarshalJSON(s []byte) (err error)

UnmarshalJSON is used to convert the timestamp from JSON