| Name | trendspy JSON |
| Version |
0.1.5
JSON |
| download |
| home_page | None |
| Summary | A Python library for accessing Google Trends data |
| upload_time | 2024-11-15 19:28:23 |
| maintainer | None |
| docs_url | None |
| author | SDil |
| requires_python | >=3.7 |
| license | MIT License Copyright (c) 2024 SDil Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
analytics
data-analysis
google-trends
trends
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
requests
pandas
numpy
python-dateutil
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# TrendsPy
Python library for accessing Google Trends data.
## Key Features
**Explore**
- Track popularity over time (`interest_over_time`)
- Analyze geographic distribution (`interest_by_region`)
- Compare interest across different timeframes and regions (multirange support)
- Get related queries and topics (`related_queries`, `related_topics`)
**Trending Now**
- Access current trending searches (`trending_now`, `trending_now_by_rss`)
- Get related news articles (`trending_now_news_by_ids`)
- Retrieve historical data for 500+ trending keywords with independent normalization (`trending_now_showcase_timeline`)
**Search Utilities**
- Find category IDs (`categories`)
- Search for location codes (`geo`)
**Flexible Time Formats**
- Custom intervals: `'now 123-H'`, `'today 45-d'`
- Date-based offsets: `'2024-02-01 10-d'`
- Standard ranges: `'2024-01-01 2024-12-31'`
## Installation
```bash
pip install trendspy
```
## Basic Usage
```python
from trendspy import Trends
tr = Trends()
df = tr.interest_over_time(['python', 'javascript'])
df.plot(title='Python vs JavaScript Interest Over Time',
figsize=(12, 6))
```
```python
# Analyze geographic distribution
geo_df = tr.interest_by_region('python')
```
```python
# Get related queries
related = tr.related_queries('python')
```
## Advanced Features
### Search Categories and Locations
```python
# Find technology-related categories
categories = tr.categories(find='technology')
# Output: [{'name': 'Computers & Electronics', 'id': '13'}, ...]
# Search for locations
locations = tr.geo(find='york')
# Output: [{'name': 'New York', 'id': 'US-NY'}, ...]
# Use in queries
df = tr.interest_over_time(
'python',
geo='US-NY', # Found location ID
cat='13' # Found category ID
)
```
### Real-time Trending Searches and News
```python
# Get current trending searches in the US
trends = tr.trending_now(geo='US')
# Get trending searches with news articles
trends_with_news = tr.trending_now_by_rss(geo='US')
print(trends_with_news[0]) # First trending topic
print(trends_with_news[0].news[0]) # Associated news article
# Get news articles for specific trending topics
news = tr.trending_now_news_by_ids(
trends[0].news_tokens, # News tokens from trending topic
max_news=3 # Number of articles to retrieve
)
for article in news:
print(f"Title: {article.title}")
print(f"Source: {article.source}")
print(f"URL: {article.url}\n")
```
### Independent Historical Data for Multiple Keywords
```python
from trendspy import BatchPeriod
# Unlike standard interest_over_time where data is normalized across all keywords,
# trending_now_showcase_timeline provides independent data for each keyword
# (up to 500+ keywords in a single request)
keywords = ['keyword1', 'keyword2', ..., 'keyword500']
# Get independent historical data
df_24h = tr.trending_now_showcase_timeline(
keywords,
timeframe=BatchPeriod.Past24H # 16-minute intervals
)
# Each keyword's data is normalized only to itself
df_24h.plot(
subplots=True,
layout=(5, 2),
figsize=(15, 20),
title="Independent Trend Lines"
)
# Available time windows:
# - Past4H: ~30 points (8-minute intervals)
# - Past24H: ~90 points (16-minute intervals)
# - Past48H: ~180 points (16-minute intervals)
# - Past7D: ~42 points (4-hour intervals)
```
### Geographic Analysis
```python
# Country-level data
country_df = tr.interest_by_region('python')
# State-level data for the US
state_df = tr.interest_by_region(
'python',
geo='US',
resolution='REGION'
)
# City-level data for California
city_df = tr.interest_by_region(
'python',
geo='US-CA',
resolution='CITY'
)
```
### Timeframe Formats
- Standard API timeframes: `'now 1-H'`, `'now 4-H'`, `'today 1-m'`, `'today 3-m'`, `'today 12-m'`
- Custom intervals:
- Short-term (< 8 days): `'now 123-H'`, `'now 72-H'`
- Long-term: `'today 45-d'`, `'today 90-d'`, `'today 18-m'`
- Date-based: `'2024-02-01 10-d'`, `'2024-03-15 3-m'`
- Date ranges: `'2024-01-01 2024-12-31'`
- Hourly precision: `'2024-03-25T12 2024-03-25T15'` (for periods < 8 days)
- All available data: `'all'`
### Multirange Interest Over Time
Compare search interest across different time periods and regions:
```python
# Compare different time periods
timeframes = [
'2024-01-25 12-d', # 12-day period
'2024-06-20 23-d' # 23-day period
]
geo = ['US', 'GB'] # Compare US and UK
df = tr.interest_over_time(
'python',
timeframe=timeframes,
geo=geo
)
```
Note: When using multiple timeframes, they must maintain consistent resolution and the maximum timeframe cannot be more than twice the length of the minimum timeframe.
### Proxy Support
TrendsPy supports the same proxy configuration as the `requests` library:
```python
# Initialize with proxy
tr = Trends(proxy="http://user:pass@10.10.1.10:3128")
# or
tr = Trends(proxy={
"http": "http://10.10.1.10:3128",
"https": "http://10.10.1.10:1080"
})
# Configure proxy after initialization
tr.set_proxy("http://10.10.1.10:3128")
```
## Documentation
For more examples and detailed API documentation, check out the Jupyter notebook in the repository: `basic_usage.ipynb`
## License
MIT License - see the [LICENSE](LICENSE) file for details.
## Disclaimer
This library is not affiliated with Google. Please ensure compliance with Google's terms of service when using this library.
Raw data
{
"_id": null,
"home_page": null,
"name": "trendspy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "analytics, data-analysis, google-trends, trends",
"author": "SDil",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/5d/7a/8d4273e9e2f8a481c4c823e86de0a99b45b5a7aeca0c5c8a1eb2e744e2fb/trendspy-0.1.5.tar.gz",
"platform": null,
"description": "# TrendsPy\n\nPython library for accessing Google Trends data.\n\n## Key Features\n\n**Explore**\n- Track popularity over time (`interest_over_time`)\n- Analyze geographic distribution (`interest_by_region`)\n- Compare interest across different timeframes and regions (multirange support)\n- Get related queries and topics (`related_queries`, `related_topics`)\n\n**Trending Now**\n- Access current trending searches (`trending_now`, `trending_now_by_rss`)\n- Get related news articles (`trending_now_news_by_ids`)\n- Retrieve historical data for 500+ trending keywords with independent normalization (`trending_now_showcase_timeline`)\n\n**Search Utilities**\n- Find category IDs (`categories`)\n- Search for location codes (`geo`)\n\n**Flexible Time Formats**\n- Custom intervals: `'now 123-H'`, `'today 45-d'`\n- Date-based offsets: `'2024-02-01 10-d'`\n- Standard ranges: `'2024-01-01 2024-12-31'`\n\n## Installation\n\n```bash\npip install trendspy\n```\n\n## Basic Usage\n\n```python\nfrom trendspy import Trends\ntr = Trends()\ndf = tr.interest_over_time(['python', 'javascript'])\ndf.plot(title='Python vs JavaScript Interest Over Time', \n figsize=(12, 6))\n```\n\n```python\n# Analyze geographic distribution\ngeo_df = tr.interest_by_region('python')\n```\n```python\n# Get related queries\nrelated = tr.related_queries('python')\n```\n\n## Advanced Features\n\n### Search Categories and Locations\n\n```python\n# Find technology-related categories\ncategories = tr.categories(find='technology')\n# Output: [{'name': 'Computers & Electronics', 'id': '13'}, ...]\n\n# Search for locations\nlocations = tr.geo(find='york')\n# Output: [{'name': 'New York', 'id': 'US-NY'}, ...]\n\n# Use in queries\ndf = tr.interest_over_time(\n 'python',\n geo='US-NY', # Found location ID\n cat='13' # Found category ID\n)\n```\n\n### Real-time Trending Searches and News\n\n```python\n# Get current trending searches in the US\ntrends = tr.trending_now(geo='US')\n\n# Get trending searches with news articles\ntrends_with_news = tr.trending_now_by_rss(geo='US')\nprint(trends_with_news[0]) # First trending topic\nprint(trends_with_news[0].news[0]) # Associated news article\n\n# Get news articles for specific trending topics\nnews = tr.trending_now_news_by_ids(\n trends[0].news_tokens, # News tokens from trending topic\n max_news=3 # Number of articles to retrieve\n)\nfor article in news:\n print(f\"Title: {article.title}\")\n print(f\"Source: {article.source}\")\n print(f\"URL: {article.url}\\n\")\n```\n\n### Independent Historical Data for Multiple Keywords\n\n```python\nfrom trendspy import BatchPeriod\n\n# Unlike standard interest_over_time where data is normalized across all keywords,\n# trending_now_showcase_timeline provides independent data for each keyword\n# (up to 500+ keywords in a single request)\n\nkeywords = ['keyword1', 'keyword2', ..., 'keyword500']\n\n# Get independent historical data\ndf_24h = tr.trending_now_showcase_timeline(\n keywords,\n timeframe=BatchPeriod.Past24H # 16-minute intervals\n)\n\n# Each keyword's data is normalized only to itself\ndf_24h.plot(\n subplots=True,\n layout=(5, 2),\n figsize=(15, 20),\n title=\"Independent Trend Lines\"\n)\n\n# Available time windows:\n# - Past4H: ~30 points (8-minute intervals)\n# - Past24H: ~90 points (16-minute intervals)\n# - Past48H: ~180 points (16-minute intervals)\n# - Past7D: ~42 points (4-hour intervals)\n```\n\n### Geographic Analysis\n\n```python\n# Country-level data\ncountry_df = tr.interest_by_region('python')\n\n# State-level data for the US\nstate_df = tr.interest_by_region(\n 'python',\n geo='US',\n resolution='REGION'\n)\n\n# City-level data for California\ncity_df = tr.interest_by_region(\n 'python',\n geo='US-CA',\n resolution='CITY'\n)\n```\n\n### Timeframe Formats\n\n- Standard API timeframes: `'now 1-H'`, `'now 4-H'`, `'today 1-m'`, `'today 3-m'`, `'today 12-m'`\n- Custom intervals:\n - Short-term (< 8 days): `'now 123-H'`, `'now 72-H'`\n - Long-term: `'today 45-d'`, `'today 90-d'`, `'today 18-m'`\n - Date-based: `'2024-02-01 10-d'`, `'2024-03-15 3-m'`\n- Date ranges: `'2024-01-01 2024-12-31'`\n- Hourly precision: `'2024-03-25T12 2024-03-25T15'` (for periods < 8 days)\n- All available data: `'all'`\n\n### Multirange Interest Over Time\n\nCompare search interest across different time periods and regions:\n\n```python\n# Compare different time periods\ntimeframes = [\n '2024-01-25 12-d', # 12-day period\n '2024-06-20 23-d' # 23-day period\n]\ngeo = ['US', 'GB'] # Compare US and UK\n\ndf = tr.interest_over_time(\n 'python',\n timeframe=timeframes,\n geo=geo\n)\n```\n\nNote: When using multiple timeframes, they must maintain consistent resolution and the maximum timeframe cannot be more than twice the length of the minimum timeframe.\n\n### Proxy Support\n\nTrendsPy supports the same proxy configuration as the `requests` library:\n\n```python\n# Initialize with proxy\ntr = Trends(proxy=\"http://user:pass@10.10.1.10:3128\")\n# or\ntr = Trends(proxy={\n \"http\": \"http://10.10.1.10:3128\",\n \"https\": \"http://10.10.1.10:1080\"\n})\n\n# Configure proxy after initialization\ntr.set_proxy(\"http://10.10.1.10:3128\")\n```\n\n## Documentation\n\nFor more examples and detailed API documentation, check out the Jupyter notebook in the repository: `basic_usage.ipynb`\n\n## License\n\nMIT License - see the [LICENSE](LICENSE) file for details.\n\n## Disclaimer\n\nThis library is not affiliated with Google. Please ensure compliance with Google's terms of service when using this library.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 SDil Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "A Python library for accessing Google Trends data",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://github.com/sdil87/trendspy",
"Issues": "https://github.com/sdil87/trendspy/issues",
"Repository": "https://github.com/sdil87/trendspy.git"
},
"split_keywords": [
"analytics",
" data-analysis",
" google-trends",
" trends"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "926c112a3a4e87a7ef0893a18912c3d978a515afbe7dffb4aaf5b052eda63e92",
"md5": "5c669710a1372b633b8391a7efad0062",
"sha256": "a2716ac00a724136c1eba7ffc24cdd87170cc00288dac62e3b487991f3737f88"
},
"downloads": -1,
"filename": "trendspy-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5c669710a1372b633b8391a7efad0062",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 25826,
"upload_time": "2024-11-15T19:28:21",
"upload_time_iso_8601": "2024-11-15T19:28:21.731474Z",
"url": "https://files.pythonhosted.org/packages/92/6c/112a3a4e87a7ef0893a18912c3d978a515afbe7dffb4aaf5b052eda63e92/trendspy-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5d7a8d4273e9e2f8a481c4c823e86de0a99b45b5a7aeca0c5c8a1eb2e744e2fb",
"md5": "216f07e2befbdad5c2d8a12ac7d14f89",
"sha256": "ca5a80db78e126f4c0a18ae7cdeb558bec7f33da71aff6b513e2db6e1fceb21f"
},
"downloads": -1,
"filename": "trendspy-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "216f07e2befbdad5c2d8a12ac7d14f89",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 239637,
"upload_time": "2024-11-15T19:28:23",
"upload_time_iso_8601": "2024-11-15T19:28:23.751408Z",
"url": "https://files.pythonhosted.org/packages/5d/7a/8d4273e9e2f8a481c4c823e86de0a99b45b5a7aeca0c5c8a1eb2e744e2fb/trendspy-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-15 19:28:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sdil87",
"github_project": "trendspy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.2.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.19.0"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
">=",
"2.8.0"
]
]
}
],
"lcname": "trendspy"
}
