imdb

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: May 31, 2024 License: MIT Imports: 14 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 AdvacedSearchNameResult 

type AdvacedSearchNameResult struct {
	// Index number of the item.
	Index int
	// Title: Name of the movie/show or person.
	Title string
	// Image: Poster image of a title or profile image of a person.
	Image string
	// Professions: Roles taken by a person for ex: Director, Actress, Producer.
	Professions []string
	// Top title of a actor/actress. Only for people/names.
	TopTitle types.Link
	// Link: Link to the title or person's imdb page.
	Link string
	// Description: A description of the title or person.
	Description string
}

Single results item from an AdvancedSearchName results list.

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 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 {
	// Index number of the item.
	Index int
	// Title: Name of the movie/show or person.
	Title string
	// Image: Poster image of a title or profile image of a person.
	Image string
	// Link: Link to the title or person's imdb page.
	Link string
	// Metadata: Metadata for titles containing the year of release, duration and us certificate.
	Metadata []string
	// Rating: A string containing rating info for ex: 7.5 (35K).
	Rating string
	// Description: A description of the title or person.
	Description string
}

Single result from the AdvancedSearchTitle result list.

func (*AdvancedSearchTitleResult) FullPerson 

func (s *AdvancedSearchTitleResult) 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.

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   int    `json:"height"`
	ImageURL string `json:"imageURL"`
	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) ([]*AdvacedSearchNameResult, 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 {
	// ID of the movie
	ID string
	// Link to the movie
	Link string
	// Full title of the movie
	Title string `xpath:"//h1[@data-testid='hero__pageTitle']/span"`
	// Year of release of the movie
	Year string `xpath:"//h1[@data-testid='hero__pageTitle']/..//a[contains(@href, 'releaseinfo')]"`
	// Ratings of the movie in the format n/10
	Rating string `xpath:"//div[@data-testid='hero-rating-bar__aggregate-rating']//div[@data-testid='hero-rating-bar__aggregate-rating__score']"`
	// Rumber of votes the movie got
	Votes string `xpath:"//div[@data-testid='hero-rating-bar__aggregate-rating']/a/span/div/div[2]/div[3]"`
	// The directors of the movie
	Directors types.Links `xpath:"//div[@role='presentation']/ul//*[starts-with(text(), 'Director')]/../div"`
	// The writers of the movie
	Writers types.Links `xpath:"//div[@role='presentation']/ul//*[starts-with(text(), 'Writer')]/../div"`
	// The main stars of the movie
	Stars types.Links `xpath:"//div[@role='presentation']/ul//*[starts-with(text(), 'Star')]/../div"`
	// Genres of the movie
	Genres types.Links `xpath:"//div[@data-testid='genres']/div[2]"`
	// A short plot of the movie in a few lines
	Plot string `xpath:"/html/body//main//p[@data-testid='plot']//span[@data-testid='plot-xl']"`
	// A string with details about the release including date and country
	Releaseinfo string `` /* 136-byte string literal not displayed */
	// Origin of release, commonly the country
	Origin string `` /* 131-byte string literal not displayed */
	// Official sites related to the movie/show
	OfficialSites types.Links `` /* 132-byte string literal not displayed */
	// Languages in which the movie/show is available in
	Languages types.Links `` /* 134-byte string literal not displayed */
	// Any alternative name of the movie.
	Aka string `` /* 128-byte string literal not displayed */
	// Locations at which the movie/show was filmed at
	Locations types.Links `` /* 141-byte string literal not displayed */
	// Companies which produced the movie
	Companies types.Links `` /* 134-byte string literal not displayed */
	// Runtime of the move
	Runtime string `xpath:"//div[@data-testid='title-techspecs-section']/ul/li[@data-testid='title-techspec_runtime']/div"`
}

Full movie object, contains data about a movie/show only available after scraping it's data with imdb.GetMovie().

func (*Movie) PrettyPrint 

func (t *Movie) PrettyPrint()

PrettyPrint prints out movie data in a neat interface.

type Person 

type Person struct {
	// Imdb id of the user for ex: nm0000129
	ID string
	// URL to the person's imdb profile in the format imdb.com/name/{id}
	Link string
	// Full name of the person
	Name string `xpath:"//h1[@data-testid='hero__pageTitle']/span"`
	// List of roles performed by the person for ex: actor, producer, director etc.
	Roles []string `xpath:"//h1[@data-testid='hero__pageTitle']/../ul|textlist"`
	// Short bio of the person.
	Bio string `xpath:"//div[@data-testid='bio-content']//div[contains(@class, 'inner')]"`
	// Poster image of the person.
	Poster string `xpath:"//div[starts-with(@class, 'ipc-poster')]//img|attr_src"`
	// Links to movies/show the person is known for.
	KnownFor types.Links `` /* 130-byte string literal not displayed */

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

	// A short trivia fact about the person.
	Trivia string `xpath:"//section[@data-testid='DidYouKnow']/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:"//section[@data-testid='DidYouKnow']//li[@data-testid='name-dyk-quote']/div"`
	// A nickname of the person.
	Nickname string `xpath:"//section[@data-testid='DidYouKnow']//li[@data-testid='name-dyk-nickname']/div"`
	// Any trademark features of the person.
	Trademark string `xpath:"//section[@data-testid='DidYouKnow']//li[@data-testid='name-dyk-trademarks']/div"`
}

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

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"`
}

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.