{"id":13586586,"url":"https://github.com/APirchner/gsvi","last_synced_at":"2025-04-07T18:34:06.683Z","repository":{"id":35584067,"uuid":"212489626","full_name":"APirchner/gsvi","owner":"APirchner","description":"Interface for Google Trends time series","archived":false,"fork":false,"pushed_at":"2022-12-08T07:59:48.000Z","size":227,"stargazers_count":12,"open_issues_count":3,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-04-29T23:09:49.141Z","etag":null,"topics":["google","search","trends","volume"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/APirchner.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-10-03T03:25:51.000Z","updated_at":"2023-10-24T17:14:56.000Z","dependencies_parsed_at":"2023-01-16T00:14:54.971Z","dependency_job_id":null,"html_url":"https://github.com/APirchner/gsvi","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/APirchner%2Fgsvi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/APirchner%2Fgsvi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/APirchner%2Fgsvi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/APirchner%2Fgsvi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/APirchner","download_url":"https://codeload.github.com/APirchner/gsvi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247707702,"owners_count":20982829,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["google","search","trends","volume"],"created_at":"2024-08-01T15:05:39.889Z","updated_at":"2025-04-07T18:34:06.393Z","avatar_url":"https://github.com/APirchner.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":".. image:: https://travis-ci.com/APirchner/gsvi.svg?branch=master\n    :target: https://travis-ci.com/APirchner/gsvi\n\n.. image:: https://img.shields.io/pypi/dm/gsvi\n   :target: https://pypi.python.org/pypi/gsvi\n\nGSVI - Google Search Volume Index\n*********************************\n\nA interface for the `Google Trends \u003chttps://trends.google.com/\u003e`_ time-series widget.\n\nMotivation\n==========\nThe Google Search Volume Index (GSVI) is a useful metric for the\nattention a certain topic (product, event etc.) receives.\nFetching data from Google Trends automatically can be a pain.\nThis package makes getting arbitrary-length time-series of monthly, daily and hourly data as easy as::\n\n    connection = GoogleConnection()\n    series = SVSeries.univariate(connection=connection,\n                                 query={'key': 'sp500', 'geo': 'US'},\n                                 start=start, end=end,\n                                 category=CategoryCodes.FINANCE,\n                                 granularity='DAY'\n                                 )\n    ts = series.get_data()\n\n\nIdea\n====\nGoogle Trends' quota limits are a big factor slowing down the collection of data.\nPacking requests tightly reduced the load on GT and pushes the limits\non data one can pull before getting kicked -\nthis package bundles up to queries into one request.\nAnother weird quirks of Google Trends are the data normalization and granularity.\nGT reports daily data for queries with an interval length between 1 and 269 days,\nhourly data between  3 and 7 days and\nmonthly data from 1890 days on (NOTE: this could change at any time!).\nFor each request, the volume within one request is normalized to have a maximal value of 100.\nSo the query for the daily/hourly search volume for keyword abc in some interval, is handled by *gsvi* as follows:\n\n  #. Bundle the query into requests of max. 5 269-day (7-day for hourly) fragments each and\n     get the SV from Google Trends. If this is sufficient to cover the whole interval, skip the next steps.\n  #. Look for the query holding the maximum (100) in each request.\n  #. Bundle the fragments holding the maxima into requests of 5 each and get the SV from Google Trends.\n  #. Repeat 2.-3. until only one interval holding the global maximum is left\n  #. Bundle the original query into requests of 4 269-day (7-day) fragments +\n     fragment with global maximum get the SV from Google Trends.\n \nThis procedure results in a continuous series that is normalized to\n\\[0, 100\\] over the global maximum by Google Trends itself.\nFor monthly data, one request per key is sufficient.\n\nThis idea naturally extends to multivariate series of up to n queries,\nlimited only by what GT allows you to pull.\n\n\nUsage\n=====\nFor example, we would like to get the daily search volume for 'food' in the\nU.S. from 2014-09-13 to 2019-06-13::\n\n    import datetime as dt\n    from gsvi.connection import GoogleConnection\n    from gsvi.timeseries import SVSeries\n\n    # series start and end\n    start = dt.datetime(year=2014, month=9, day=13)\n    end = dt.datetime(year=2019, month=6, day=13)\n\n    # make connection to Google Trends and inject connection into the request structure\n    connection = GoogleConnection()\n    series = SVSeries.univariate(connection=connection,\n                                 query={'key': 'food', 'geo': 'US'},\n                                 start=start, end=end, granularity='DAY'\n                                 )\n    ts = series.get_data()\n\nOr, what about the monthly volume of car brand searches in Germany from 2004 to June 2019::\n\n    import datetime as dt\n\n    from gsvi.connection import GoogleConnection\n    from gsvi.timeseries import SVSeries\n\n    # series start and end\n    start = dt.datetime(year=2014, month=9, day=13)\n    end = dt.datetime(year=2019, month=6, day=13)\n\n    # make connection to Google Trends and inject connection into the request structure\n    connection = GoogleConnection()\n    query_multi = [{'key': 'mercedes', 'geo': 'DE'},\n                  {'key': 'porsche', 'geo': 'DE'},\n                  {'key': 'bmw', 'geo': 'DE'},\n                  {'key': 'audi', 'geo': 'DE'},\n                  {'key': 'vw', 'geo': 'DE'},\n                  {'key': 'ford', 'geo': 'DE'},\n                  ]\n    start_multi = dt.datetime(year=2004, month=1, day=1)\n    end_multi = dt.datetime(year=2019, month=6, day=1)\n    series = SVSeries.multivariate(connection=connection,\n                                   queries=query_multi,\n                                   start=start, end=end,\n                                   granularity='MONTH'\n                                  )\n    ts = series.get_data()\n\n\n\nInstallation\n============\n\n::\n\n$ pip install gsvi\n\n\nCredits\n=======\n\n- The main idea for the normalization was taken from a paper by `Christopher Fink and Thomas Johann (2014) \u003chttps://papers.ssrn.com/sol3/papers.cfm?abstract_id=2139313\u003e`_\n- The connection-handling was inspired by the `pytrends package \u003chttps://github.com/GeneralMills/pytrends\u003e`_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAPirchner%2Fgsvi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAPirchner%2Fgsvi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAPirchner%2Fgsvi/lists"}