imdb

package
v0.2.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 7, 2024 License: MIT Imports: 13 Imported by: 0

README

Imdb

The imdb package offers methods to browse imdb and get data about entities. Generated Docs

Table Of Content

Guide

Here's a short guide of the available methods and it's usage. All options are passed in the optional field of each function.

Setup

Let's start by importing the imdb package

import "github.com/Jisin0/filmigo/imdb"

Now let's create a new imdb client, all methods are called through this client.

client := imdb.NewClient()

Options

  • DisableCaching : Indicates wether data should not be cached.
  • CacheExpiration : Duration for which cache is valid. Defaults to 5 hours.

These functions use imdb's api and are superfast. You can search for titles. names or both.

Titles

You can search for titles i.e Movies and Shows using the SearchTitles method.

client.SearchTitles("inception")
Names

You can search for names using the SearchNames method.

client.SearchNames("keanu")
Both

You can search for titles and names using the SearchAll method.

client.SearchAll("mad")
GetMovie

Use this function to get a movie using it's imdb id. We'll use tt1375666 for this example.

client.GetMovie("tt1375666")
GetPerson

Use this function to get a person using their imdb id. We'll use nm0000206 for this example.

client.GetPerson("nm0000206")

Imdb offers an advanced search page that allows filtering people and titles based on a wide variety of parameters.

Titles

We'll search for all action movies in this examples.

First lets import the constants package.

import "github.com/Jisin0/filmigo/imdb/constants"

Now lets create our request options.

opts := imdb.AdvancedSearchTitleOpts{
    Types: []string{constants.TitleTypeMovie},
    Genres: []string{constants.TitleGenreAction},
}

Then make the request.

results, err := client.AdvancedSearchTitle(&opts)
if err!=nil{
    panic(err)
}
Names

We'll search for people who starred in inception using it's id.

Lets create our request options.

opts := imdb.AdvancedSearchNameOpts{
    Titles: []string{"tt1375666"},
}

Then make the request.

results, err := client.AdvancedSearchName(&opts)
if err!=nil{
    panic(err)
}

Documentation

Overview

The imdb package is a collection of methods to get data from imdb using it's official api or webscraping. The only publicly exposed imdb has is for searching hence every other method relies on webscraping. The AdvancedSearch methods do not use an api either.

Index

Constants

View Source 
const (
	ResultTypeTitle = "title" // result type of movies/shows
	ResultTypeName  = "name"  // result type for people
	ResultTypeOther = "other" // other result types (url path for promotions)
)

Variables

View Source 
var ErrNoResults error = errors.New("no search results were found")

Functions

This section is empty.

Types

type AdvSearchImage added in v0.2.0 

type AdvSearchImage struct {
	// Caption of the image.
	Caption string `json:"caption"`
	// Height of the image in pixels.
	Height int `json:"height"`
	// ID of the image (not sure where to use this)
	ID string `json:"id"`
	// URL of the image.
	URL string `json:"url"`
	// WIdth of the image in pixels.
	Width int `json:"width"`
}

Poster image of an AvancedSearch result.

type AdvancedSearchNameOpts 

type AdvancedSearchNameOpts struct {
	// Name: Filter by the name of the person.
	Name string `url:"name"`
	// BirthRange: A range of birth date inside which the person was born in the format yyyy-dd-mm.
	BirthRange types.SearchRange `url:"birth_date"`
	// Birthday: Birthday of the actor in the format MM-DD
	Birthday string `url:"birth_monthday"`
	// Awards: List of awards won by the person
	// see NameAwardXX values in the constants package for all possible values for ex. constants.NameAwardBestActorNominated
	Awards []string `url:"groups"`
	// Page topics: filter by topics on the imdb page of the person. Use ExtraParams for searching within a topic.
	PageTopics []string `url:"has"`
	// DeathRange: A range of death date inside which the person passed away in the format yyyy-dd-mm.
	DeathRange types.SearchRange `url:"birth_date"`
	// Genders: Return actors that ho by the given genders.
	// See NameGenderXX values for all possible values for ex: NameGenderMale.
	Genders []string `url:"gender"`
	// Titles: A list of imdb ids of titles for ex. tt15398776 to search for stars in oppenheimer.
	Titles []string `url:"roles"`
	// AdultNames: Set value to constants.StringInclude to include stars in adult titles.
	AdultNames string `url:"adult"`
	// Additional url parameters to be passed along with the request.
	ExtraParams map[string]any
}

Options for the AdvancedSearchName query see https://imdb.com/search/title to see the list and syntax for each option.

type AdvancedSearchNameResult added in v0.2.0 

type AdvancedSearchNameResult struct {
	// Title: Name of the person.
	Title string `json:"nameText"`
	// Bio or short decription of the person.
	Bio string `json:"bio"`
	// Data about a title the person is known for.
	KnownFor struct {
		// Indicates wether the title can have episodes.
		CanHaveEpisodes bool `json:"canHaveEpisodes"`
		// Original or full title of the movie or show.
		OriginalTitle string `json:"originalTitle"`
		// Imdb ID of the title.
		ID string `json:"titleId"`
		// Name of the title.
		Title string `json:"titleText"`
		// Range of years in which the title was released.
		YearRange struct {
			// Year in which the title was first released.
			ReleaseYear int `json:"year"`
			// Year in which a series ended or last broadcasted.
			EndYear int `json:"endYear"`
		} `json:"yearRange"`
	} `json:"knownFor"`
	// Imdb ID of the person.
	ID string `json:"nameId"`
	// Image: Profile image of a person.
	Image AdvSearchImage `json:"primaryImage"`
	// Professions: Roles taken by a person for ex: Director, Actress, Producer.
	Professions []string `json:"primaryProfessions"`
}

Single results item from an AdvancedSearchName results list.

func (*AdvancedSearchNameResult) FullPerson added in v0.2.0 

func (s *AdvancedSearchNameResult) FullPerson(client *ImdbClient) (*Person, error)

FullPerson returns the full data about a title scraped from it's imdb page.

- client : Client to make imdb requests through.

type AdvancedSearchTitleOpts 

type AdvancedSearchTitleOpts struct {
	// Search by the title name of a movie/show.
	TitleName string `url:"title"`
	// Type filter by the type of title see TitleTypeXX values in the constants package for all possible values for ex: constants.TitleTypeMovie.
	Types []string `url:"title_type"`
	// RelaseDate a range/period of time in which the title was released. Dates must be in the format yyyy-dd-mm.
	RelaseDate types.SearchRange `url:"release_date"`
	// Ratings range of minimum and maximum rating of titles returned. for ex. Start: 7, End: 9.5.
	Rating types.SearchRange `url:"user_rating"`
	// Votes range of votes on a title. for ex. Start: 10000, End: 500000.
	Votes types.SearchRange `url:"num_votes"`
	// Genres filter by the genre of the title see TitleGenreXX values in the constants package for all possible values for ex: constants.TitleGenreAction.
	Genres []string `url:"genres"`
	// Awards: find titles that have won or have been nominated for an award.
	// See TitleAwardXX values in the constants package for all possible values for ex: constants.TitleAwardOscarWinner.
	Awards []string `url:"groups"`
	// Topics on the imdb page of the title. Use additional params to search within a topic.
	Topics []string `url:"has"`
	// Companies: filter by companies what produced the title.
	Companies []string `url:"companies"`
	// InstantWatch: search by ability to watch online on an instantwatch platform.
	InstantWatches []string `url:"online_availability"`
	// Certificates: The watching certificates of a title. see TitleCertificateXX values in the constants package for all possible values for ex: constants.TitleCertificatePG.
	Certificates []string `url:"certificates"`
	// Color: The color info of the title. for ex. constants.TitleColorBlackAndWhite for black&white titles.
	Colors []string `url:"colors"`
	// Countries: country codes of the countries associated with the title. for ex. GB for United Kingdom.
	Countries []string `url:"country"`
	// Keywords: Filter by additional keywords.
	Keywords []string `url:"keywords"`
	// Languages. Language codes of language of the title. for ex. en for english.
	Languages []string `url:"languages"`
	// Popularity. Filter by a range of imdb popularity rank.
	Popularity types.SearchRange `url:"moviemeter"`
	// CastOrCrew. Lost of ids of actors or crew in the title. for ex nm0614165 for Cillian Murphy
	CastOrCrew []string `url:"role"`
	// Characters. List of names of characters in the movie.
	Characters []string `url:"characters"`
	// Runtime. Range of runtime of the movie in minutes.
	Runtime types.SearchRange `url:"runtime"`
	// SoundMixes: The sound mix of a title. see TitleSoundXX values in the constants package for all possible values for ex: constants.TitleSoundDolby.
	SoundMixes []string `url:"sound_mixes"`
	// AdultTitles: Set value to constants.StringInclude to include adult titles
	AdultTitles string `url:"adult"`
	// Additional url parameters to be passed along with the request.
	ExtraParams map[string]any
}

Options for the AdvancedSearchTitle query see https://imdb.com/search/title to see the list and syntax for each option.

type AdvancedSearchTitleResult 

type AdvancedSearchTitleResult struct {
	// Indicates wether the title can be rated on imdb.
	CanRate bool `json:"canRate"`
	// Parental certificate of the title: 15 indicates TV-MA, 12 indicates PG-13, 18 indicates TV-MA.
	Certificate string `json:"certificate"`
	// The year in which a TVShow ended. Only for Series and Mini-Series.
	EndYear int `json:"endYear"`
	// Genres of the title.
	Genres []string `json:"genres"`
	// Indicates wether the movie has onli watching option (highly inaccurate).
	HasWatchOption bool `json:"hasWatchOption"`
	// Full original Title of the movie/show.
	OriginalTitle string `json:"originalTitleText"`
	// Plot of the movie/show.
	Plot string `json:"plot"`
	// Image: Poster image of a title or profile image of a person.
	Image AdvSearchImage `json:"primaryImage"`
	// Rating data about the title.
	Rating struct {
		// Value of rating out of 10.
		Value float32 `json:"aggregateRating"`
		// Number of votes received for the title.
		Votes int64 `json:"voteCount"`
	} `json:"ratingSummary"`
	// Year in which the title was first released.
	ReleaseYear int `json:"releaseYear"`
	// Runtime of the title in minutes.
	Runtime int `json:"runtime"`
	// Imdb id of the title.
	ID string `json:"titleId"`
	// Title of the movie or show.
	Title string `json:"titleText"`
	// Data about the type of title.
	Type struct {
		// Indicates wether the title can have episodes.
		CanHaveEpisodes bool `json:"canHaveEpisodes"`
		// Id of the type. Possible values include movie, tvSeries, tvMiniSeries etc.
		ID string `json:"id"`
		// User-Friendly text about the type for ex: TV Series for tvSeries.
		Text string `json:"text"`
	} `json:"titleType"`
	// Video id of the trailer of the title.
	TrailerID string `json:"trailerId"`
}

Single result from the AdvancedSearchTitle result list.

func (*AdvancedSearchTitleResult) FullTitle 

func (s *AdvancedSearchTitleResult) FullTitle(client *ImdbClient) (*Movie, error)

FullTitle returns the full data about a title scraped from it's imdb page.

- client : Client to make imdb requests through.

type Image 

type Image struct {
	// Height of the image.
	Height int `json:"height"`
	// URL of the image.
	URL string `json:"imageURL"`
	// Width of the image.
	Width int `json:"width"`
}

type ImdbCache 

type ImdbCache struct {
	MovieCache  *cache.Cache
	PersonCache *cache.Cache
	SearchCache *cache.Cache // Only used for advanced search
}

func NewImdbCache 

func NewImdbCache(timeout time.Duration) *ImdbCache

Creates a new imdb cache system with given values.

- timeout (time.Duration) - Duration after which cached data must expire.

type ImdbClient 

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

ImdbClient type provides all imdb related operations. Use imdb.NewClient to create one.

func NewClient 

func NewClient(o ...ImdbClientOpts) *ImdbClient

NewClient returns a new client with given configs.

func (*ImdbClient) AdvancedSearchName 

func (*ImdbClient) AdvancedSearchName(opts *AdvancedSearchNameOpts) ([]*AdvancedSearchNameResult, error)

AdvancedSearchName uses the search page to search for names using many configuration options. Use SearchX methods for simple fast searches using the api.

opts - configure search options.

func (*ImdbClient) AdvancedSearchTitle 

func (*ImdbClient) AdvancedSearchTitle(opts *AdvancedSearchTitleOpts) ([]*AdvancedSearchTitleResult, error)

AdvancedSearchTitle uses the search page to search for titles using many configuration options. Use SearchX methods for simple fast searches using the api.

opts - configure search options.

func (*ImdbClient) GetMovie 

func (c *ImdbClient) GetMovie(id string) (*Movie, error)

Function to get the full details about a movie/show using it's id .

- id : Unique id used to identify each movie for ex: tt15398776.

Returns an error on failed requests or if the movie wasn't found.

func (*ImdbClient) GetPerson 

func (c *ImdbClient) GetPerson(id string) (*Person, error)

Function to get the full details about a person using their id .

- id : Unique id used to identify each person for ex: nm0614165.

Returns an error on failed requests or if the person wasn't found.

func (*ImdbClient) SearchAll 

func (c *ImdbClient) SearchAll(query string, configs ...*SearchConfigs) (*SearchResults, error)

Search for globally on imdb across titles and names. The first element in a global search is sometimes an advertisement these have a url path as id.

- query (string) - The query or keyword to search for. - configs (optional) - Additional request configs.

func (*ImdbClient) SearchNames 

func (c *ImdbClient) SearchNames(query string, configs ...*SearchConfigs) (*SearchResults, error)

Search for only people/names.

- query (string) - The query or keyword to search for. - configs (optional) - Additional request configs.

func (*ImdbClient) SearchTitles 

func (c *ImdbClient) SearchTitles(query string, configs ...*SearchConfigs) (*SearchResults, error)

Search for only movies/shows excluding people or other types.

- query (string) - The query or keyword to search for. - configs (optional) - Additional request configs.

func (*ImdbClient) SetCacheTimeout 

func (c *ImdbClient) SetCacheTimeout(t time.Duration)

Modify the cache duration of imdb data.

- timeout (time.Duration) - Duration after which cached data must expire.

func (*ImdbClient) SetDisableCaching 

func (c *ImdbClient) SetDisableCaching(b bool)

Set DisableCaching to true only if you need to. It's highly unrecommended as data provided by imdb is pretty persistent.

type ImdbClientOpts 

type ImdbClientOpts struct {
	// Set this to true to disable caching results.
	DisableCaching bool
	// This field is the duration for which cached data is considered valid.
	// Defaluts to 5 * time.Hour.
	CacheExpiration time.Duration
}

Options to configure the imdb client's behaviour.

type Movie 

type Movie struct {
	// Imdb id of the movie .
	ID string
	// Years of release of the movie, A range for shows over multiple years.
	ReleaseYear string
	MovieJSONContent
	MovieDetailsSection
}

func (*Movie) PrettyPrint 

func (t *Movie) PrettyPrint()

PrettyPrint prints out movie data in a neat interface.

type MovieDetailsSection added in v0.2.0 

type MovieDetailsSection struct {
	// A string with details about the release including date and country
	Releaseinfo string `xpath:"//li[@data-testid='title-details-releasedate']/div//a"`
	// Origin of release, commonly the country
	Origin string `xpath:"//li[@data-testid='title-details-origin']/div//a"`
	// Official sites related to the movie/show
	OfficialSites types.Links `xpath:"//li[@data-testid='details-officialsites']/div/ul"`
	// Languages in which the movie/show is available in
	Languages types.Links `xpath:"//li[@data-testid='title-details-languages']/div/ul"`
	// Any alternative name of the movie.
	Aka string `xpath:"//li[@data-testid='title-details-akas']//span"`
	// Locations at which the movie/show was filmed at
	Locations types.Links `xpath:"//li[@data-testid='title-details-filminglocations']/div/ul"`
	// Companies which produced the movie
	Companies types.Links `xpath:"//li[@data-testid='title-details-companies']/div/ul"`
}

Data scraped from the details section of a movie using xpath.

type MovieJSONContent added in v0.2.0 

type MovieJSONContent struct {
	// Type of the title possibble values are Movie, TVSeries etc.
	Type string `json:"@type"`
	// ID of the movie
	ID string
	// Link to the movie
	URL string `json:"url"`
	// Full title of the movie
	Title string `json:"name"`
	// Url of the full size poster image.
	PosterURL string `json:"image"`
	// Content rating class (currently undocumented).
	ContentRating string `json:"contentRating"`
	// Date the movie was released on in yyyy-mm-dd format.
	ReleaseDate string `json:"datePublished"`
	// Keywords associated with the movie in a comma separated list.
	Keywords string `json:"keywords"`
	// Ratings for the movie.
	Rating Rating `json:"aggregateRating"`
	// The directors of the movie
	Directors types.Links `json:"director"`
	// The writers of the movie
	Writers types.Links `json:"creator"`
	// The main stars of the movie
	Actors types.Links `json:"actor"`
	// Genres of the movie
	Genres []string `json:"genre"`
	// A short plot of the movie in a few lines
	Plot string `json:"description"`
	// Trailer video for the movie or show.
	Trailer VideoObject `json:"trailer,omitempty"`
	// Runtime of the move
	Runtime string `json:"duration"`
	// Tope review of the movie.
	Review Review `json:"review,omitempty"`
}

Data scraped from the json attached in the script tag.

type Person 

type Person struct {
	// Imdb id of the user for ex: nm0000129
	ID string
	// Links to movies/show the person is known for.
	KnownFor types.Links `xpath:"|linklist"`
	PersonJSONContent
	PersonDetailsSection
	PersonDYKSection
}

Type containing the full data about a person scraped from their imdb page.

type PersonDYKSection added in v0.2.0 

type PersonDYKSection struct {
	// A short trivia fact about the person.
	Trivia string `xpath:"/div[2]//li[@data-testid='name-dyk-trivia']/div"` // Trivia is always the first dyk hence the div[2]
	// A popular quote of the person. All quotes can be found at {link}/quotes.
	Quote string `xpath:"//li[@data-testid='name-dyk-quote']/div"`
	// A nickname of the person.
	Nickname string `xpath:"//li[@data-testid='name-dyk-nickname']/div"`
	// Any trademark features of the person.
	Trademark string `xpath:"//li[@data-testid='name-dyk-trademarks']/div"`
}

Data to be scraped from the Did You Know section of an actor.

type PersonDetailsSection added in v0.2.0 

type PersonDetailsSection struct {
	// Official sites of the person.
	OfficialSites types.Links `xpath:"/li[@data-testid='details-officialsites']/div|linklist"`
	// Height of the person.
	Height string `xpath:"/li[@data-testid='nm_pd_he']/div//span"`
	// Date of birth . for ex : April 30, 1981
	Birthday string `xpath:"/li[@data-testid='nm_pd_bl']/div/ul/li"`
	// Spouse of the person.
	Spouse types.Links `xpath:"/li[@data-testid='nm_pd_sp']/div|linklist"`
	// Other works - usually a short sentence about a different work of the person.
	OtherWorks string `xpath:"/li[@data-testid='nm_pd_wrk']/div"`
}

Data to be scraped from a persons Details section.

type PersonJSONContent added in v0.2.0 

type PersonJSONContent struct {
	// URL of the imdb page.
	URL string `json:"url"`
	// Name of the person.
	Name string `json:"name"`
	// URL of the main full-size poster image of the person.
	Image string `json:"image"`
	// Short description of the person.
	Description string `json:"description"`
	// A video about the person.
	Video VideoObject `json:"video"`
	// Headline for the person for ex: Cillian Murphy - Actor, Producer, Writer.
	Headline string `json:"headLine"`
	// Extra content about the person.
	MainEntity struct {
		// Job Titles of the person for ex: Actor, Producer, Director.
		JobTitles []string `json:"jobTitles"`
		// Date of birth of the person in yyyy-mm-dd format.
		BirthDate string `json:"birthDate"`
	} `json:"mainEntity"`
}

JSON data available for the person the page.

type Rating added in v0.2.0 

type Rating struct {
	// Number of votes. (absent for reviews)
	Votes int64 `json:"ratingCount"`
	// Worst rating received.
	Worst float32 `json:"worstRating"`
	// Best rating received.
	Best float32 `json:"bestRating"`
	// Actual value of the rating out of 10.
	Value float32 `json:"ratingValue"`
}

Rating data for a title or review.

type Review added in v0.2.0 

type Review struct {
	// Item that was reviewed.
	ItemReviewed ReviewItem `json:"itemReviewed"`
	// Author of the review.
	Author ReviewAuthor `json:"author"`
	// Date on which the review was created in the format yyyy-mm-dd
	Date string `json:"dateCreated"`
	// Language in which the review is written.
	Language string `json:"inLanguage"`
	// Body or content of the review.
	Body string `json:"reviewBody"`
	// Ratings for the review.
	Rating Rating `json:"reviewRating"`
}

Review of a movie or show.

type ReviewAuthor added in v0.2.0 

type ReviewAuthor struct {
	// Name of the person.
	Name string `json:"name"`
}

Author of a review.

type ReviewItem added in v0.2.0 

type ReviewItem struct {
	// Url of the item that was reviewed.
	URL string `json:"url"`
}

An item that was reviewed.

type SearchConfigs 

type SearchConfigs struct {
	// Set true for the api to return video details (trailers, previews etc.).
	// If enabled you will get a thumbnail of the video and the video id.
	IncludeVideos bool
}

Optional parameters to be passed to the search query.

type SearchResult 

type SearchResult struct {
	// An image commonly a movie poster or actor's picture.
	Image Image `json:"i"`
	// ID of the movie/show/person or the url path for ads.
	ID string `json:"id"`
	// Header or main text of a search result. A movie/show/person's name.
	Title string `json:"l"`
	// For movies or shows, A string of the type os title for ex: TV Series, Movie etc.
	Subtitle string `json:"q"`
	// The category of the movie/show. Empty for people.
	// Possible values : movie, tvSeries, tvMiniSeries
	Category string `json:"qid"`
	// A rank point.
	Rank int `json:"rank"`
	// The main stars of a movie/show, or a notable work in case of a person.
	Description string `json:"s"`
	// Year of release of a movie/show
	Year int `json:"y"`
	// A string indicating the years in which a tv series was released. for ex: 2016-2025
	Years string `json:"yr"`
	// A list of videos related to the title or person.
	Videos []Video `json:"v"`
}

Data obtained from searching using the api. Could be data on a movie/show/person or sometimes an ad when using SarchAll.

func (*SearchResult) FullPerson 

func (s *SearchResult) FullPerson(client *ImdbClient) (*Person, error)

Returns the full data about a person scraped from their imdb page.

- client : The imdb client to use for the request.

func (*SearchResult) FullTitle 

func (s *SearchResult) FullTitle(client *ImdbClient) (*Movie, error)

Returns the full data about a title scraped from it's imdb page.

- client : The imdb client to use for the request.

func (*SearchResult) GetType 

func (s *SearchResult) GetType() string

Returns the type of search result returned possible values are "title", "name" and "other".

func (*SearchResult) IsPerson 

func (s *SearchResult) IsPerson() bool

Checks wether result type is a person.

func (*SearchResult) IsTitle 

func (s *SearchResult) IsTitle() bool

Checks wether result type is a title i.e movies/shows.

type SearchResults 

type SearchResults struct {
	// List of results.
	Results []*SearchResult `json:"d"`
	// The query string.
	Query string `json:"q"`
	// Unknown. Could be some version code or used for pagination, every result has this field.
	V int `json:"v"`
}

Search Results returned from eith SearchTitles or SearchAll methods.

type Video 

type Video struct {
	Thumbnail Image  `json:"i"`
	ID        string `json:"id"`
	Title     string `json:"l"`
	Duration  string `json:"s"`
}

type VideoObject added in v0.2.0 

type VideoObject struct {
	// Name of the video.
	Name string `json:"name"`
	// Url to create embedded video players.
	EmbedURL string `json:"embedUrl"`
	// Image url of the thumbnail of the video.
	Thumbnail string `json:"thumbnailUrl"`
	// Short description of the video.
	Description string `json:"description"`
	// Duration of the video.
	Duration string `json:"duration"`
	// Url of the video .
	URL string `json:"url"`
	// Timestamp of the upload time of the video.
	// Use time.Parse(time.RFC3339Nano, UploadDate) to parse it.
	UploadDate string `json:"uploadDate"`
}

A video file about the entity.

Source Files

View all Source files

Directories

Path Synopsis
Constants used across the imdb package.
 Constants used across the imdb package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.