gogtrends

package module
v1.7.0 Latest Latest
Warning

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

 Go to latest Published: May 10, 2021 License: MIT Imports: 12 Imported by: 6

README

Mentioned in Awesome Go Go Doc Coverage Status Go Report Card License

gogtrends is API wrapper which allows to get reports from Google Trends.

All contributions, updates and issues are warmly welcome.

Installation

go get -u github.com/groovili/gogtrends

Debug

To see request-response details use gogtrends.Debug(true)

Usage

Daily and Realtime trends used as it is. For both methods user interface language are required. For Realtime trends category is required param, list of available categories - TrendsCategories.

Please notice that Realtime trends are available only for limited list of locations.

For InterestOverTime, InterestByLocation and Related - widget and user interface language are required.

To get widget you should call Explore methods first, it will return constant list of available widgets, every widget corresponds to methods above.

Widget includes request params and unique token for every method.

Also Explore method supports single and multiple items for comparision. Please take a look at ExploreRequest input. It supports search by multiple categories and locations which you can get as tree structure by ExploreCategories and ExploreLocations.

Please notice, when you call Explore method for keywords comparison, two first widgets would be for all of compared items, next widgets would be for each of individual items.

Available methods

  • Daily(ctx context.Context, hl, loc string) ([]*TrendingSearch, error) - daily trends descending ordered by days and articles corresponding to it.

  • Realtime(ctx context.Context, hl, loc, cat string) ([]*TrendingStory, error) - represents realtime trends with included articles and sources.

  • Search(ctx context.Context, word, hl string) ([]*KeywordTopic, error) - Words/Topics related (5 results max) with your search.

  • Explore(ctx context.Context, r *ExploreRequest, hl string) ([]*ExploreWidget, error) - widgets with tokens. Every widget is related to specific method (InterestOverTime, InterestByLocation, Related) and contains required token and request information.

  • InterestOverTime(ctx context.Context, w *ExploreWidget, hl string) ([]*Timeline, error) - interest over time, dots for chart.

  • InterestByLocation(ctx context.Context, w *ExploreWidget, hl string) ([]*GeoMap, error) - interest by location, list for map with geo codes and interest values.

  • Related(ctx context.Context, w *ExploreWidget, hl string) ([]*RankedKeyword, error) - related topics or queries, supports two types of widgets.

  • TrendsCategories() map[string]string - available categories for Realtime trends.

  • ExploreCategories(ctx context.Context) (*ExploreCatTree, error) - tree of categories for explore and comparison. Called once, then returned from cache.

  • ExploreLocations(ctx context.Context) (*ExploreLocTree, error) - tree of locations for explore and comparison. Called once, then returned from cache.

Parameters

  • hl - string, user interface language

  • loc - string, uppercase location (geo) country code, example "US" - United States

  • cat - string, lowercase category for real time trends, example "all" - all categories

  • exploreReq - ExploreRequest struct, represents search or comparison items.

  • widget - ExploreWidget struct, specific for every method, can be received by Explore method.

Examples

Working detailed examples for all methods and cases can be found in example folder. Short version below.

// Daily trends
ctx := context.Background()
dailySearches, err := gogtrends.Daily(ctx, "EN", "US")

// Get available trends categories and realtime trends
cats := gogtrends.TrendsCategories()
realtime, err := gogtrends.Realtime(ctx, "EN", "US", "all")

// Explore available widgets for keywords and get all available stats for it
explore, err := gogtrends.Explore(ctx, 
	    &gogtrends.ExploreRequest{
            ComparisonItems: []*gogtrends.ComparisonItem{
                {
                    Keyword: "Go",
                    Geo:     "US",
                    Time:    "today 12-m",
                },
            },
            Category: 31, // Programming category
            Property: "",
        }, "EN")

// Interest over time
overTime, err := gogtrends.InterestOverTime(ctx, explore[0], "EN")

// Interest by location
byLoc, err := gogtrends.InterestByLocation(ctx, explore[1], "EN")

// Related topics for keyword
relT, err := gogtrends.Related(ctx, explore[2], "EN")

// Related queries for keyword
relQ, err := gogtrends.Related(ctx, explore[3], "EN")

// Compare keywords interest
compare, err := gogtrends.Explore(ctx, 
	    &gogtrends.ExploreRequest{
            ComparisonItems: []*gogtrends.ComparisonItem{
                {
                    Keyword: "Go",
                    Geo:     "US",
                    Time:    "today 12-m",
                },
                {
                    Keyword: "Python",
                    Geo:     "US",
                    Time:    "today 12-m",
                },
                {
                    Keyword: "PHP",
                    Geo:     "US",
                    Time:    "today 12-m",
                },                               
            },
            Category: 31, // Programming category
            Property: "",
        }, "EN")
Licence

Package is distributed under MIT Licence.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalidCategory - user input is not in trendsCategories list (binding to available options in Google Trends)
	ErrInvalidCategory = errors.New("invalid category param")
	// ErrRequestFailed - response status != 200
	ErrRequestFailed = errors.New("failed to perform http request")
	// ErrInvalidWidgetType - provided widget is invalid or is used for another method
	ErrInvalidWidgetType = errors.New("invalid widget type")
)

Functions

func Debug 

func Debug(debug bool)

Debug allows to see request-response details.

func TrendsCategories 

func TrendsCategories() map[string]string

TrendsCategories return list of available categories for Realtime method as [param]description map.

Types

type ComparisonItem 

type ComparisonItem struct {
	Keyword string `json:"keyword" bson:"keyword"`
	Geo     string `json:"geo,omitempty" bson:"geo"`
	Time    string `json:"time" bson:"time"`
}

ComparisonItem it's concrete search keyword with Geo (can be found with ExploreLocations method) locality and Time period

type ExploreCatTree 

type ExploreCatTree struct {
	Name     string            `json:"name" bson:"name"`
	ID       int               `json:"id" bson:"id"`
	Children []*ExploreCatTree `json:"children" bson:"children"`
}

ExploreCatTree - available categories list tree

func ExploreCategories 

func ExploreCategories(ctx context.Context) (*ExploreCatTree, error)

ExploreCategories gets available categories for explore and comparison and caches it in client.

type ExploreLocTree 

type ExploreLocTree struct {
	Name     string            `json:"name" bson:"name"`
	ID       string            `json:"id" bson:"id"`
	Children []*ExploreLocTree `json:"children" bson:"children"`
}

ExploreLocTree - available locations list tree

func ExploreLocations 

func ExploreLocations(ctx context.Context) (*ExploreLocTree, error)

ExploreLocations gets available locations for explore and comparison and caches it in client.

type ExploreRequest 

type ExploreRequest struct {
	ComparisonItems []*ComparisonItem `json:"comparisonItem" bson:"comparison_items"`
	Category        int               `json:"category" bson:"category"`
	Property        string            `json:"property" bson:"property"`
}

ExploreRequest it's an input which can contain multiple items (keywords) to discover category can be found in ExploreCategories output

type ExploreResponse added in v1.6.0 

type ExploreResponse []*ExploreWidget

func Explore 

func Explore(ctx context.Context, r *ExploreRequest, hl string) (ExploreResponse, error)

Explore list of widgets with tokens. Every widget is related to specific method (`InterestOverTime`, `InterestOverLoc`, `RelatedSearches`, `Suggestions`) and contains required token and request information.

func (ExploreResponse) GetWidgetsByOrder added in v1.6.0 

func (e ExploreResponse) GetWidgetsByOrder(i int) ExploreResponse

func (ExploreResponse) GetWidgetsByType added in v1.6.0 

func (e ExploreResponse) GetWidgetsByType(t WidgetType) ExploreResponse

func (ExploreResponse) Len added in v1.6.0 

func (e ExploreResponse) Len() int

func (ExploreResponse) Less added in v1.6.0 

func (e ExploreResponse) Less(i, j int) bool

func (ExploreResponse) Sort added in v1.6.0 

func (e ExploreResponse) Sort()

func (ExploreResponse) Swap added in v1.6.0 

func (e ExploreResponse) Swap(i, j int)

type ExploreWidget 

type ExploreWidget struct {
	Token   string          `json:"token" bson:"token"`
	Type    string          `json:"type" bson:"type"`
	Title   string          `json:"title" bson:"title"`
	ID      string          `json:"id" bson:"id"`
	Request *WidgetResponse `json:"request" bson:"request"`
}

ExploreWidget - output of Explore method, required for InterestOverTime, InterestByLocation and Related methods. Globally it's a structure related to Google Trends UI and contains mostly system info

type GeoMap 

type GeoMap struct {
	GeoCode        string   `json:"geoCode" bson:"geo_code"`
	GeoName        string   `json:"geoName" bson:"geo_name"`
	Value          []int    `json:"value" bson:"value"`
	FormattedValue []string `json:"formattedValue" bson:"formatted_value"`
	MaxValueIndex  int      `json:"maxValueIndex" bson:"max_value_index"`
	HasData        []bool   `json:"hasData" bson:"has_data"`
}

GeoMap - it's representation of interest by location. Mostly used for maps

func InterestByLocation 

func InterestByLocation(ctx context.Context, w *ExploreWidget, hl string) ([]*GeoMap, error)

InterestByLocation as list of `GeoMap`, with geo codes and interest values.

type KeywordRestriction 

type KeywordRestriction struct {
	Type  string `json:"type" bson:"type"`
	Value string `json:"value" bson:"value"`
}

KeywordRestriction - specific keyword limitation. Part of KeywordsRestriction

type KeywordTopic 

type KeywordTopic struct {
	Mid   string `json:"mid" bson:"mid"`
	Title string `json:"title" bson:"title"`
	Type  string `json:"type" bson:"type"`
}

KeywordTopic - is a part of RankedKeyword 

func Search(ctx context.Context, word, hl string) ([]*KeywordTopic, error)

Related topics or queries, list of `RankedKeyword`, supports two types of widgets.

type KeywordsRestriction 

type KeywordsRestriction struct {
	Keyword []*KeywordRestriction `json:"keyword" bson:"keyword"`
}

KeywordsRestriction - system info for keywords limitations, not used. part of WidgetResponse

type RankedKeyword 

type RankedKeyword struct {
	Query          string       `json:"query,omitempty" bson:"query"`
	Topic          KeywordTopic `json:"topic,omitempty" bson:"topic"`
	Value          int          `json:"value" bson:"value"`
	FormattedValue string       `json:"formattedValue" bson:"formatted_value"`
	HasData        bool         `json:"hasData" bson:"has_data"`
	Link           string       `json:"link" bson:"link"`
}

RankedKeyword - it's representation of related to search items 

func Related(ctx context.Context, w *ExploreWidget, hl string) ([]*RankedKeyword, error)

Related topics or queries, list of `RankedKeyword`, supports two types of widgets.

type RequestOptions 

type RequestOptions struct {
	Property string `json:"property" bson:"property"`
	Backend  string `json:"backend" bson:"backend"`
	Category int    `json:"category" bson:"category"`
}

RequestOptions - part of WidgetResponse

type SearchArticle 

type SearchArticle struct {
	Title   string       `json:"title" bson:"title"`
	TimeAgo string       `json:"timeAgo" bson:"time_ago"`
	Source  string       `json:"source" bson:"source"`
	Image   *SearchImage `json:"image" bson:"image"`
	URL     string       `json:"url" bson:"url"`
	Snippet string       `json:"snippet" bson:"snippet"`
}

SearchArticle is a news relative to trending search

type SearchImage 

type SearchImage struct {
	NewsURL  string `json:"newsUrl" bson:"news_url"`
	Source   string `json:"source" bson:"source"`
	ImageURL string `json:"imageUrl" bson:"image_url"`
}

SearchImage is a picture of trending search

type SearchTitle 

type SearchTitle struct {
	Query string `json:"query" bson:"query"`
}

SearchTitle is a user query string for daily trending search

type Timeline 

type Timeline struct {
	Time              string   `json:"time" bson:"time"`
	FormattedTime     string   `json:"formattedTime" bson:"formatted_time"`
	FormattedAxisTime string   `json:"formattedAxisTime" bson:"formatted_axis_time"`
	Value             []int    `json:"value" bson:"value"`
	HasData           []bool   `json:"hasData" bson:"has_data"`
	FormattedValue    []string `json:"formattedValue" bson:"formatted_value"`
}

Timeline - it's representation of interest to trend trough period timeline. Mostly used for charts

func InterestOverTime 

func InterestOverTime(ctx context.Context, w *ExploreWidget, hl string) ([]*Timeline, error)

InterestOverTime as list of `Timeline` dots for chart.

type TrendingArticle 

type TrendingArticle struct {
	Title   string `json:"articleTitle" bson:"title"`
	URL     string `json:"url" bson:"url"`
	Source  string `json:"source" bson:"source"`
	Time    string `json:"time" bson:"time"`
	Snippet string `json:"snippet" bson:"snippet"`
}

TrendingArticle is an article relative to trending story

type TrendingSearch 

type TrendingSearch struct {
	Title            *SearchTitle     `json:"title" bson:"title"`
	FormattedTraffic string           `json:"formattedTraffic" bson:"formatted_traffic"`
	Image            *SearchImage     `json:"image" bson:"image"`
	Articles         []*SearchArticle `json:"articles" bson:"articles"`
}

TrendingSearch is a representation trending search in period of 24 hours

func Daily 

func Daily(ctx context.Context, hl, loc string) ([]*TrendingSearch, error)

Daily gets daily trends descending ordered by days and articles corresponding to it.

type TrendingStory 

type TrendingStory struct {
	Title    string             `json:"title" bson:"title"`
	Image    *SearchImage       `json:"image" bson:"image"`
	Articles []*TrendingArticle `json:"articles" bson:"articles"`
}

TrendingStory is a representation of realtime trend

func Realtime 

func Realtime(ctx context.Context, hl, loc, cat string) ([]*TrendingStory, error)

Realtime represents realtime trends with included articles and sources.

type WidgetComparisonItem 

type WidgetComparisonItem struct {
	Geo                            map[string]string   `json:"geo,omitempty" bson:"geo"`
	Time                           string              `json:"time,omitempty" bson:"time"`
	ComplexKeywordsRestriction     KeywordsRestriction `json:"complexKeywordsRestriction,omitempty" bson:"complex_keywords_restriction"`
	OriginalTimeRangeForExploreURL string              `json:"originalTimeRangeForExploreUrl,omitempty" bson:"original_time_range_for_explore_url"`
}

WidgetComparisonItem - system info for comparison item part of WidgetResponse

type WidgetResponse 

type WidgetResponse struct {
	Geo                interface{}             `json:"geo,omitempty" bson:"geo"`
	Time               string                  `json:"time,omitempty" bson:"time"`
	Resolution         string                  `json:"resolution,omitempty" bson:"resolution"`
	Locale             string                  `json:"locale,omitempty" bson:"locale"`
	Restriction        WidgetComparisonItem    `json:"restriction" bson:"restriction"`
	CompItem           []*WidgetComparisonItem `json:"comparisonItem" bson:"comparison_item"`
	RequestOpt         RequestOptions          `json:"requestOptions" bson:"request_option"`
	KeywordType        string                  `json:"keywordType" bson:"keyword_type"`
	Metric             []string                `json:"metric" bson:"metric"`
	Language           string                  `json:"language" bson:"language"`
	TrendinessSettings map[string]string       `json:"trendinessSettings" bson:"trendiness_settings"`
	DataMode           string                  `json:"dataMode,omitempty" bson:"data_mode"`
	UserCountryCode    string                  `json:"userCountryCode,omitempty" bson:"user_country_code"`
}

WidgetResponse - system info for every available trends search mode

type WidgetType added in v1.6.0 

type WidgetType string
const (
	IntOverTimeWidgetID WidgetType = "TIMESERIES"
	IntOverRegionID     WidgetType = "GEO_MAP"
	RelatedQueriesID    WidgetType = "RELATED_QUERIES"
	RelatedTopicsID     WidgetType = "RELATED_TOPICS"
)

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.