justwatch

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jun 4, 2024 License: MIT Imports: 9 Imported by: 1

README

Justwatch

The justwatch package offers methods to browse justwatch and get data about entities using it's graphql api. 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 justwatch package

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

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

client := justwatch.NewClient()

Options

  • Country : Country code for the source country deafults to US.
  • LangCode : Language code defaults to en.

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

client.SearchTitles("inception")

Options

  • Limit : Maximimum number of results to return defaults to 5.
  • NoTitlesWithoutURL : Indicates wether titles without url should not be returned.
  • Country : Use a country code for the specific request (uses client's country by default).
  • LangCode : Use a language code for the specific request (uses client's LangCode by default).
Get Title

You can fetch a title by it's id or it's url. Justwatch ids are only used internally unlike imdb that exclusively use this to identify titles.

By ID

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

client.GetTitle("tt1375666")

Options

  • EpisodeMaxLimit : Maximimum number of episodes to return for a show season defaluts to 20.
  • Country : Use a country code for the specific request (uses client's country by default).
  • LangCode : Use a language code for the specific request (uses client's LangCode by default).
By URL

Use this function to get a movie using it's justwatch link. We'll use https://www.justwatch.com/us/movie/inception for this example. The function also accepts just the url path i.e /us/movie/inception which is the norm.

client.GetTitleFromURL("https://www.justwatch.com/us/movie/inception")

Options

  • EpisodeMaxLimit : Maximimum number of episodes to return for a show season defaluts to 20.
  • Country : Use a country code for the specific request (uses client's country by default).
  • LangCode : Use a language code for the specific request (uses client's LangCode by default).
Get Title Offers

Use this function to get offers for a title using it's justwatch id. We'll use tm820952 for this example.

client.GetTitleOffers("tm820952")

Options

  • Country : Use a country code for the specific request (uses client's country by default).
  • LangCode : Use a language code for the specific request (uses client's LangCode by default).

Documentation

Overview

Package justwatch uses justwathch's graphql api used on their website and apps. This api is not to be confused with their official streaming/partners api. This package currently only covers a handful of the available graphql queries.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AvailableTo 

type AvailableTo struct {
	// Countdown integer.
	AvailableCountdown int `json:"availableCountDown,omitempty"`
	// Date upto which it's available in the format yyyy-mm-dd.
	AvalableToDate string `json:"availableToDate,omitempty"`
	// Package details with only shortname populated.
	Package *Package `json:"package,omitempty"`
}

Availability of the movie or show.

type Backdrop 

type Backdrop struct {
	// File path format to the backdrop image.
	BackdropURLFormat string `json:"backdropURL"`
}

Backdrop image data. Use the FullURL() method to get the full formatted url.

func (Backdrop) FullURL 

func (b Backdrop) FullURL() string

Get the full image url for the maximum size of the image.

type Clip 

type Clip struct {
	// URL to the video .
	URL string `json:"sourceURL,omitempty"`
	// Name of the clip.
	Name string `json:"name,omitempty"`
	// Provider of the clip probably YOUTUBE or DAILYMOTION.
	Provider string `json:"provider,omitempty"`
	// Exteranl id of the clip on their respective platforms.
	ExteranlID string `json:"externalID,omitempty"`
}

Video clip of the title.

type Credit 

type Credit struct {
	// role of the person in the title.
	Role string `json:"role,omitempty"`
	// Name of the person.
	Name string `json:"name,omitempty"`
	// Name of the character played by the person.
	CharacterName string `json:"characterName,omitempty"`
	// Justwatch ID of the person
	ID int `json:"personID,omitempty"`
}

Credit for a role in a title.

type Episode 

type Episode struct {
	// Justwatch id of the episode. for ex: tse7685834.
	ID string `json:"id,omitempty"`
	// Numeric value of the id.
	NumericID int `json:"objectID,omitempty"`
	// Content of the episode.
	Content struct {
		// Title of the episode.
		Title string `json:"episode,omitempty"`
		// Description of the episode.
		Description string `json:"shortDescription,omitempty"`
		// Season number.
		SeasonNumber int `json:"seasonNumber,omitempty"`
		// Number of the episode.
		EpisodeNumber int `json:"episodeNumber,omitempty"`
		// Indicates wether the episode is released.
		IsReleased bool `json:"isReleased,omitempty"`
	} `json:"content,omitempty"`
}

A single episode of a show.

type EpisodePreview 

type EpisodePreview struct {
	// Justwatch id of the season for ex: tss414472.
	ID string `json:"id,omitempty"`
	// Numeric id.
	NumericID int `json:"objectID,omitempty"`
	// Number of episodes in the season.
	TotalEpisodeCount int `json:"totalEpisodeCount,omitempty"`
	// Availability.
	AvailableTo []*AvailableTo `json:"availableTo,omitempty"`
	// Content of the episode, only few fields are populated.
	Content *TitleContent `json:"content,omitempty"`
}

Basic data about an episode that's included in the full result of a show or season.

type ExteranlIDs 

type ExteranlIDs struct {
	// Imdb id.
	ImdbID string `json:"imdbID,omitempty"`
	// Tmdb id.
	TmdbID string `json:"tmdbID,omitempty"`
}

External IDs for the movie on imdb, tmdb etc.

type Genre 

type Genre struct {
	// Shortcode for a genre returned from the api.
	// For ex: cmy for Comedy.
	ShortName string `json:"shortName"`
	// contains filtered or unexported fields
}

Raw genre from justwatch with only the shortname. Use FullName() to get the full name for ex: cmy -> Comedy

func (*Genre) FullName 

func (g *Genre) FullName() string

Returns the full name for for the shortcode returned from the api. For ex: shortcode cmy returns Comedy.

type Genres 

type Genres []Genre

Raw genres returned from api.

func (*Genres) ToList 

func (gs *Genres) ToList() []string

ToList returns a slice with the full name for each genre.

func (*Genres) ToShortList 

func (gs *Genres) ToShortList() []string

ToShortList returns a slice with the shortcodes of each genre.

func (*Genres) ToString 

func (gs *Genres) ToString(sep string) string

ToString generates a string with the full name sof genres separated with given separator.

type GetTitleOffersResult 

type GetTitleOffersResult struct {
	// Justwatch ID of the title.
	ID string `json:"id"`
	// Type name either Movie or Show.
	TypeName string `json:"__typename"`
	// Number of offers available for the title.
	OfferCount int `json:"offerCount"`
	// Full timestamp of the last time offers were updated.
	MaxOfferUpdateAt string `json:"maxOfferUpdatedAt"`
	// Flatrate offers for the title.
	Flatrate []*Offer `json:"flatrate"`
	// Offers to buy the movie/show.
	Buy []*Offer `json:"buy"`
	// Offers to rent the title for a period.
	Rent []*Offer `json:"rent"`
	// Offers to watch the title for free.
	Free []*Offer `json:"free"`
	// Fast-fiew offers.
	Fast []*Offer `json:"fast"`
}

Results from GetTitleOffers() query.

func (*GetTitleOffersResult) MergeOffers 

func (r *GetTitleOffersResult) MergeOffers() []*Offer

Returns a full list with the combined results of Flatrate, Buy, Rent, Free and Fast offers.

type GetTitleOptions 

type GetTitleOptions struct {
	// Country code of country of request. for ex: US.
	Country string
	// Lnaguage code for results. for ex: en.
	Language string
	// Maximum number of episodes to return.
	EpisodeMaxLimit int
}

Options for GetTitleURL() operation.

type Icon 

type Icon string

func (Icon) FullURL 

func (i Icon) FullURL() string

returns the direct url to the icon.

type Interactions 

type Interactions struct {
	// Dislikes number.
	Dislikes int `json:"dislikelistAdditions,omitempty"`
	// Likes number.
	Likes int `json:"likelistAdditions,omitempty"`
	// Number of votes (likes + dislikes).
	Votes int `json:"votesNumber,omitempty"`
}

Interactions with the title like likes and dislikes details.

type JustwatchClient 

type JustwatchClient struct {
	Country  string
	LangCode string
}

Justwatch client through which api queries are executed.

func NewClient 

func NewClient(opts ...*JustwatchClientOpts) *JustwatchClient

Creates a new justwatch client through which all api queries are executed.

func (*JustwatchClient) GetTitle 

func (c *JustwatchClient) GetTitle(id string, opts ...*GetTitleOptions) (*Title, error)

Get the full details of a title using it's justwatch id.

- id : The unique justwatch id of the entity.

func (*JustwatchClient) GetTitleFromURL 

func (c *JustwatchClient) GetTitleFromURL(path string, opts ...*GetTitleOptions) (*URLDetails, error)

Get the full details of a title using it's url path.

- path : URL path returned from a search result or the justwatch link

func (*JustwatchClient) GetTitleOffers 

func (c *JustwatchClient) GetTitleOffers(id string, opts ...*GetTitleOptions) (*GetTitleOffersResult, error)

Get the offers available for a url using it's Justwatch ID.

- id: Justwatch id of the title.

func (*JustwatchClient) SearchTitle 

func (c *JustwatchClient) SearchTitle(searchQuery string, opts ...*SearchOptions) (*SearchResults, error)

SearchTitle function searches for title with simillar title using justwatch's api.

- searchQuery: Keyword or query to search for. - opts: Additional options for the request.

type JustwatchClientOpts 

type JustwatchClientOpts struct {
	// Coutry code to use for requests defaults to US.
	Country string
	// Language code to use for requests defaults to en.
	LangCode string
}

Options for configuring default behaviour of the justwatch client.

type Offer 

type Offer struct {
	// Graphql id of the object.
	ID string `json:"id,omitempty"`
	// Direct web url to the offer package.
	URL string `json:"standardWebURL,omitempty"`
	// Type indicates the type of offer .
	Type string `json:"type,omitempty"`
	// Retail price of the provider. The string is a well formatted price tag with the currency of the request country.
	RetailPrice string `json:"retailPrice,omitempty"`
	// MonetizationType indicates how you pay for the movie/show. Values are BUY, FLATRATE, RENT or FREE.
	MonetizationType string `json:"monetizationType,omitempty"`
	// RetailPriceValue is the actual numeric value without the currency tag.
	RetailPriceValue float32 `json:"retailPriceValue,omitempty"`
	// Currency of the offer. for ex: USD, GBP, INR etc.
	Currency string `json:"currency,omitempty"`
	// PresentationType is the type of video quality either HD or SD.
	PresentationType string `json:"presentationType,omitempty"`
	// LastChangeRetailPriceValue is the numeric value of the price before the last change in it.
	LastChangeRetailPriceValue float32 `json:"lastChangeRetailPriceValue,omitempty"`
	// Details about the offer provider.
	Package *Package `json:"package,omitempty"`
	// Elements count in the results.
	ElemCount int `json:"elementCount,omitempty"`

	// Deeplink path from the justwatch site to the offer.
	Deeplink string `json:"deeplinkRoku,omitempty"`
}

Any streaming provider's offer for a movie or show.

type Package 

type Package struct {
	// Graphql id of the type
	ID string `json:"id,omitempty"`
	// ID of the package.
	PackageID int `json:"packageID,omitempty"`
	// Clear user friendly name of the package for ex: Apple TV.
	ClearName string `json:"clearName,omitempty"`
	// Technical name of the package for ex: itunes.
	TechnicalName string `json:"technicalName,omitempty"`
	// URL path to the icon of the package.
	Icon *Icon `json:"icon,omitempty"`
	// Shortname of the package.
	ShortName string `json:"shortName,omitempty"`
}

Basic details about an offer package.

type PopularityRank 

type PopularityRank struct {
	// Rank number.
	Rank int `json:"rank,omitempty"`
	// Trend indicates the stability of the rank.
	Trend string `json:"STABLE,omitempty"`
	// Trend difference.
	TrendDifference int `json:"trendDifference,omitempty"`
}

Popularity rank of a title.

type PosterURL 

type PosterURL string

Poster url format.

func (PosterURL) FullURL 

func (p PosterURL) FullURL() string

Get the full image url for the maximum size of the image.

func (PosterURL) ThumbURL 

func (p PosterURL) ThumbURL() string

Get the full image url for a thumbnail size of the image.

type PromotedBundle 

type PromotedBundle struct {
	// Direct URL to the bundle.
	URL string `json:"promotionURL,omitempty"`
}

Promoted bundle.

type Scoring 

type Scoring struct {
	// Imdb rating out of 10.
	ImdbRating float32 `json:"imdbScore,omitempty"`
	// Votes received on imdb
	ImdbVotes float32 `json:"imdbVotes,omitempty"`
	// Popularity rating on tmdb.
	TmdbPopularity float32 `json:"tmdbPopularity,omitempty"`
	// Rating on tmdb out of 10.
	TmdbRating float32 `json:"tmdbScore,omitempty"`
	// Rating percentage on justwatch for ex: 0.8778742982 indicates 87.8%
	JustwatchRating float32 `json:"jwRating,omitempty"`
}

Sores or ratings for the title on various platforms.

type SearchOptions 

type SearchOptions struct {
	// Maximum number of results to return.
	Limit int
	// Country code for the country on which results are based. for ex: GB for United Kingdom.
	Country string
	// Language code for results . for example en for English.
	Language string
	// Indicates wether titles without a url should not be returned.
	NoTitlesWithoutURL bool
}

Options for search query.

type SearchResults 

type SearchResults struct {
	// List of results.
	Results []struct {
		*TitlePreview `json:"node"`
	} `json:"edges"`
}

Results from a search operation.

type SeasonPreview 

type SeasonPreview struct {
	// Justwatch id of the season for ex: tss414472.
	ID string `json:"id,omitempty"`
	// Numeric id.
	NumericID int `json:"objectID,omitempty"`
	// Type will be SHOW_SEASON.
	Type string `json:"objectType,omitempty"`
	// Number of episodes in the season.
	TotalEpisodeCount int `json:"totalEpisodeCount,omitempty"`
	// Availability.
	AvailableTo []*AvailableTo `json:"availableTo,omitempty"`
	// Content of the season, only few fields are populated.
	Content *TitleContent `json:"content,omitempty"`
}

Basic data about a season that's included in the full result of a show.

type StreamingChartInfo 

type StreamingChartInfo struct {
	// Rank on the streaming chart.
	Rank int `json:"rank,omitempty"`
	// Trend indicates the stability of the rank either STABLE, UP or DOWN.
	Trend string `json:"trend,omitempty"`
	// Net difference in the trend.
	TrendDifference int `json:"trendDifference,omitempty"`
	// Full timestamp of the last time the rank was updated.
	UpadtedAt string `json:"updatedAt,omitempty"`
	// Maximum rank the title has ever achieved.
	TopRank int `json:"topRank,omitempty"`
	// Days for which the title was in the top 3.
	DaysInTop3 int `json:"daysInTop3,omitempty"`
	// Days for which the title was in the top 10.
	DaysInTop10 int `json:"daysInTop10,omitempty"`
	// Days for which the title was in the top 100.
	DaysInTop100 int `json:"daysInTop100,omitempty"`
	// Days for which the title was in the top 1000.
	DaysInTop1000 int `json:"daysInTop1000,omitempty"`
}

Info about a title on a streaming chart.

type Title 

type Title struct {
	// Justwatch id of the title. for ex: ts20233.
	ID string `json:"id,omitempty"`
	// Type of title either MOVIE, SHOW, SHOW_SEASON or SHOW_EPISODE.
	Type string `json:"objectType,omitempty"`
	// Numeric id of the title for ex: ts20233 becomes 202333.
	NumericID int `json:"objectID,omitempty"`
	// Data or content about the title.
	Content *TitleContent `json:"content,omitempty"`
	// Total number of available offers.
	OfferCount int `json:"offerCount,omitempty"`
	// Total number of unique offers.
	UniqueOfferCount int `json:"uniqueOfferCount,omitempty"`
	// All available offers for a title.
	Offers []*Offer `json:"offers,omitempty"`
	// WatchNowOffer is a direct view offer.
	WatchNowOffer *Offer `json:"watchNowOffer,omitempty"`
	// Promoted Bundles.
	PromotedBundles []*PromotedBundle `json:"promotedBundles,omitempty"`
	// Availability of offers.
	AvailableTo []*AvailableTo `json:"availableTo,omitempty"`
	// Offers for the title on appleTV/Itunes.
	AppleOffers []*Offer `json:"appleOffers,omitempty"`
	// Offers for the title on plexplayer.
	PlexPlayerOffers []*Offer `json:"plexPlayerOffers,omitempty"`
	// Full timestamp of when offers were updated.
	MaxOfferUpdateAt string `json:"maxOfferUpdatedAt,omitempty"`
	// Number of offers availbe on disney.
	DisneyOffersCount int `json:"disneyOffersCount,omitempty"`
	// Number of offers availbe on hotstar.
	StarOffersCount int `json:"starOffersCount,omitempty"`
	// Popularity rank of the title.
	PopularityRank *PopularityRank `json:"popularityRank,omitempty"`
	// Streaming charts and trends of the movie.
	StreamingCharts struct {
		Edges []*StreamingChartInfo `json:"edges,omitempty"`
	} `json:"streamingCharts,omitempty"`
	// Total number of seasons only for shows.
	TotalSeasonCount int `json:"totalSeasonCount,omitempty"`
	// Total Episode count only retirned for show seasons.
	TotalEpisodeCount int `json:"totalEpisodeCount,omitempty"`
	// Details about the show only present for season type.
	Show struct {
		// Justwatch id of the show.
		ID string `json:"id,omitempty"`
		// Numeric value of the id.
		NumericID int `json:"objectID,omitempty"`
		// Type of the object in this case always SHOW.
		Type string `json:"objectType,omitempty"`
		// Content of the show.
		Content struct {
			Title string `json:"title,omitempty"`
		} `json:"content,omitempty"`
	} `json:"show,omitempty"`
	// Seasons of a show only returned for type SHOW.
	Seasons []*SeasonPreview `json:"seasons,omitempty"`
	// Recent episode of a show only returned for SHOW or SHOW_SEASON types.
	RecentEpisodes []*EpisodePreview `json:"recentEpisodes,omitempty"`
}

Data about any title on justwatch.

func (*Title) PrettyPrint 

func (t *Title) PrettyPrint()

PrettyPrint prints out movie data in a neat interface.

type TitleContent 

type TitleContent struct {
	// Name of the title.
	Title string `json:"title,omitempty"`
	// Original name of the title.
	OriginalTitle string `json:"originalTitle,omitempty"`
	// URL path of the title.
	URLPath string `json:"fullPath,omitempty"`
	// A short description of the title .
	Description string `json:"shortDescription,omitempty"`
	// Year in which the title was released.
	ReleaseYear int `json:"originalReleaseYear,omitempty"`
	// Date on which the title was first released in the format yyyy-mm-dd
	ReleaseDate string `json:"originalReleaseDate,omitempty"`
	// Genres of the title like comedy, romance etc.
	Genres *Genres `json:"genres,omitempty"`
	// Unformatted poster url path.
	Poster *PosterURL `json:"posterURL,omitempty"`
	// Formatted poster url path.
	FullPoster *PosterURL `json:"fullPosterURL,omitempty"`
	// Runtime or duration of the title in minutes.
	Runtime int `json:"runtime,omitempty"`
	// Age certification for ex: TV-MA.
	AgeCertification string `json:"ageCertification,omitempty"`
	// Scores and ratings for the title on different platforms
	Scores *Scoring `json:"scoring,omitempty"`
	// IsReleased indicates wether the title is released in theaters or online.
	IsReleased bool `json:"isReleased,omitempty"`
	// Credits to people in the title.
	Credits []*Credit `json:"credits,omitempty"`
	// Interactions details like likes and dislikes.
	Interactions *Interactions `json:"interactions,omitempty"`
	// Season number for shows and episodes.
	SeasonNumer int `json:"seasonNumber,omitempty"`
	// Episode number only for show episodes.
	EpisodeNumber int `json:"episodeNumber,omitempty"`
	// Backdrop or banner images for the title.
	Backdrops []*Backdrop `json:"backdrops,omitempty"`
	// Full backdrops returns the fully formatted url path of backdrops.
	FullBackdrops []*Backdrop `json:"fullBackdrops,omitempty"`
	// Video clips of the title, usually only yt links are provided in this field.
	Clips []*Clip `json:"clips,omitempty"`
	// Clips from videobuster.com.
	VideobusterClips []*Clip `json:"videobusterClips,omitempty"`
	// Clips from dailmotion.com . Justwatch gives priority to these on their own website.
	DailymotionClips []*Clip `json:"dailymotionClips,omitempty"`
	// External ids of the title on imdb and tmdb.
	ExteranlIDs *ExteranlIDs `json:"externalIDs,omitempty"`
	// Countries in which the movie was produced.
	ProductionCountries []string `json:"productionCountries,omitempty"`
}

Data about the actual content of the title like it's genres, poster, runtime etc.

type TitlePreview 

type TitlePreview struct {
	*TitlePreviewContent `json:"content"`
	// Justwatch id of the movie/show.
	ID string `json:"id"`
	// Type of title either MOVIE, SHOW or SHOW_EPISODE
	Type     string `json:"objectType"`
	ObjectID int    `json:"objectId"`
}

Preview object with basic info about a movie/show from search results.

func (*TitlePreview) FullTitle 

func (t *TitlePreview) FullTitle(client *JustwatchClient) (*Title, error)

FullTitle fetches the full data about the title from the api by it's JW ID.

- client : Justwatch client to make the query through.

type TitlePreviewContent 

type TitlePreviewContent struct {
	// Indicates wether the title is released.
	IsReleased bool `json:"isReleased"`
	// Year of release of the movie/show.
	OriginalReleaseYear int `json:"originalReleaseYear"`
	// URL path of the movie/show.
	Path string `json:"fullPath"`
	// Title of the movie/show.
	Title string `json:"title"`
	// Original title of the movie/show.
	OriginalTitle string `json:"originalTitle"`
	// A short description of the movie/show.
	ShortDescription string `json:"shortDescription"`
	// URL template for poster images.
	// Use the FullURL() or ThumbURL() methods to get full urls.
	Poster PosterURL `json:"posterUrl"`
	// Raw genres types obtained from juswatch.
	// Use ToString()      to concatenate the full genre names into a string.
	// Use ToSlice()       to output the full genre names into a slice.
	// Use ToShortSlice()  to output the shortnames of genres to a slice.
	// Use ToShortString() to concatenate the short genre names into a string.
	Genres *Genres `json:"genres"`
	// Backdrop/Banner images for the title.
	Backdrops []Backdrop `json:"backdrops"`
}

type URLDetails 

type URLDetails struct {
	// graphql object id.
	ID string `json:"id,omitempty"`
	// Meta description is a short sentence with the available streaming provider names and a greeting.
	MetaDescripting string `json:"metaDescription,omitempty"`
	// Meta keyword about the title concatanated with commas.
	MetaKeywords string `json:"metaKeywords,omitempty"`
	// Meta title.
	MetaTitle string `json:"metaTitle,omitempty"`
	// Primary heading.
	Heading1 string `json:"heading1,omitempty"`
	// Secondary heading.
	Heading2 string `json:"heading2,omitempty"`
	// Raw html content with description and heading.
	HTMLContent string `json:"htmlContent,omitempty"`
	// Full data on the entity.
	Data *Title `json:"node,omitempty"`
}

Full details of a url obtained from using GetTitleFromURL()

Source Files

View all Source files

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.