Spaces:

trymonolith
/

pytrends-api

Sleeping

App Files Files Community

pytrends-api / README.md

trymonolith

Add comprehensive API documentation with all endpoints and examples

7130d2e verified 5 months ago

preview code

raw

history blame contribute delete

10.2 kB

metadata

title: Pytrends API
emoji: 📊
colorFrom: purple
colorTo: blue
sdk: docker
pinned: false
short_description: Self-hosted pytrends API for Google Trends data via HTTP

PyTrends HTTP API

A self-hosted REST API for Google Trends data powered by pytrends. Get trend data, regional interest, trending searches, and related queries programmatically via simple HTTP endpoints.

🚀 Features

✅ 5 REST Endpoints - Comprehensive Google Trends data access
✅ Multiple Keywords - Search for trends across multiple keywords simultaneously
✅ Geographic Filtering - Get data for specific countries or regions
✅ Time Range Selection - Choose from various timeframes
✅ JSON Responses - Easy integration with automation platforms
✅ Self-Hosted - Run on your own infrastructure
✅ Make.com & n8n Ready - Built for automation workflows
✅ Docker Deployed - Containerized on Hugging Face Spaces

📋 API Endpoints

1. Health Check

Endpoint: GET /health

Check if the API is running and healthy.

Response:

{
  "status": "healthy"
}

2. Root Endpoint

Endpoint: GET /

Get information about available endpoints.

Response:

{
  "message": "PyTrends API",
  "endpoints": {
    "/interest_over_time": "Get interest over time for keywords",
    "/interest_by_region": "Get interest by region for keywords",
    "/trending_searches": "Get trending searches for a country",
    "/related_queries": "Get related queries for keywords"
  }
}

3. Interest Over Time

Endpoint: GET /interest_over_time

Get search interest trends over time for specified keywords.

Parameters:

Parameter	Type	Required	Description
`kw`	string[]	Yes	Keywords to search (repeat parameter for multiple keywords)
`timeframe`	string	No	Time range for data (Default: "today 5-y"). Examples: "today 1-m", "today 3-m", "today 1-y", "2020-01-01 2020-12-31"
`geo`	string	No	Geographic location code (Empty = worldwide). Examples: "US", "IN", "GB", "DE"
`gprop`	string	No	Google property filter (Empty = all). Options: "images", "news", "youtube", "shopping"
`cat`	integer	No	Category ID (Default: 0 = all categories)

Example Request:

GET /interest_over_time?kw=bitcoin&kw=ethereum&timeframe=today%205-y&geo=US

Response:

{
  "data": [
    {
      "date": "2020-01-04 00:00:00",
      "bitcoin": 41,
      "ethereum": 33
    },
    {
      "date": "2020-01-11 00:00:00",
      "bitcoin": 42,
      "ethereum": 33
    }
  ],
  "keywords": ["bitcoin", "ethereum"],
  "timeframe": "today 5-y",
  "geo": "US"
}

4. Interest By Region

Endpoint: GET /interest_by_region

Get search interest distribution by geographic region.

Parameters:

Parameter	Type	Required	Description
`kw`	string[]	Yes	Keywords to search
`timeframe`	string	No	Time range (Default: "today 5-y")
`geo`	string	No	Geographic location (Empty = worldwide)
`gprop`	string	No	Google property filter
`resolution`	string	No	Resolution level (Default: "country"). Options: "country", "region", "metro", "city"

Example Request:

GET /interest_by_region?kw=python&resolution=country&timeframe=today%201-y

Response:

{
  "data": [
    {
      "geoName": "India",
      "python": 100
    },
    {
      "geoName": "Pakistan",
      "python": 54
    },
    {
      "geoName": "Philippines",
      "python": 47
    }
  ],
  "keywords": ["python"],
  "resolution": "country"
}

5. Trending Searches

Endpoint: GET /trending_searches

Get currently trending searches in a specific country.

Parameters:

Parameter	Type	Required	Description
`country`	string	No	Country code (Default: "united_states"). Examples: "united_states", "india", "united_kingdom", "canada"

Supported Countries:

united_states
india
united_kingdom
canada
australia
japan
germany
france
brazil
mexico
south_korea
and many more...

Example Request:

GET /trending_searches?country=india

Response:

{
  "trending": [
    "nykaa fashion",
    "maharashtra election results",
    "atal pension yojana",
    "deepika padukone",
    "india news"
  ],
  "country": "india"
}

6. Related Queries

Endpoint: GET /related_queries

Get related search queries and their frequency for specified keywords.

Parameters:

Parameter	Type	Required	Description
`kw`	string[]	Yes	Keywords to search
`timeframe`	string	No	Time range (Default: "today 5-y")
`geo`	string	No	Geographic location (Empty = worldwide)

Example Request:

GET /related_queries?kw=machine%20learning&timeframe=today%203-m

Response:

{
  "related_queries": {
    "machine learning": {
      "top": [
        {
          "query": "machine learning python",
          "value": 100
        },
        {
          "query": "machine learning course",
          "value": 75
        }
      ],
      "rising": [
        {
          "query": "machine learning for beginners",
          "value": 150
        },
        {
          "query": "machine learning with tensorflow",
          "value": 130
        }
      ]
    }
  },
  "keywords": ["machine learning"]
}

🔗 Base URL

https://trymonolith-pytrends-api.hf.space

🚀 Usage Examples

cURL

# Get interest over time
curl "https://trymonolith-pytrends-api.hf.space/interest_over_time?kw=python&kw=javascript&timeframe=today%201-y&geo=US"

# Get trending searches in India
curl "https://trymonolith-pytrends-api.hf.space/trending_searches?country=india"

# Get interest by region
curl "https://trymonolith-pytrends-api.hf.space/interest_by_region?kw=ai&resolution=country"

Python

import requests

base_url = "https://trymonolith-pytrends-api.hf.space"

# Get interest over time
response = requests.get(
    f"{base_url}/interest_over_time",
    params={
        "kw": ["bitcoin", "ethereum"],
        "timeframe": "today 5-y",
        "geo": "US"
    }
)
data = response.json()
print(data)

JavaScript

const baseUrl = "https://trymonolith-pytrends-api.hf.space";

// Get trending searches
fetch(`${baseUrl}/trending_searches?country=united_states`)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error("Error:", error));

🤖 Integration Guides

Make.com

Add HTTP > Make a request module to your workflow
Set Method: GET
Set URL: https://trymonolith-pytrends-api.hf.space/interest_over_time
Add Query parameters:
- kw: bitcoin (repeat for multiple keywords)
- timeframe: today 5-y
- geo: US
Enable Parse response to auto-map JSON fields
Use output in downstream modules (Google Sheets, email, etc.)

n8n

Add HTTP Request node
Set Method: GET
Set URL: https://trymonolith-pytrends-api.hf.space/interest_by_region
Go to Params tab and add:
- Key: kw, Value: python
- Key: resolution, Value: country
Click Execute to test
Connect to other nodes (e.g., Save to database, Send email)

Zapier

Use Webhooks by Zapier → Catch Raw Hook
Or use HTTP action with GET method
URL: https://trymonolith-pytrends-api.hf.space/trending_searches?country=india
Parse JSON response and use in your Zap

⏱️ Uptime & Spindown

Hardware: CPU Basic (Free tier)

Active Duration: Runs indefinitely as long as there are requests
Inactivity Timeout: 48 hours
Automatic Restart: Yes - Space restarts automatically when accessed after being paused
Startup Time: ~30-60 seconds after restart

Recommendation: For production use with guaranteed uptime, upgrade to paid CPU hardware ($0.03/hour ≈ $22/month).

📊 HTTP Status Codes

Code	Meaning	Description
200	OK	Request successful, data returned
400	Bad Request	Invalid parameters or missing required fields
500	Internal Server Error	Server error processing your request

🔧 Response Format

All endpoints return JSON responses. Successful responses include:

data - Array of results or object containing data
keywords - The keywords searched
Additional metadata fields depending on endpoint

Error responses follow this format:

{
  "error": "Descriptive error message"
}

🌍 Timeframe Options

today 1-m - Last 30 days
today 3-m - Last 90 days
today 1-y - Last year
today 5-y - Last 5 years (default)
2020-01-01 2020-12-31 - Custom date range (YYYY-MM-DD format)

🛡️ Rate Limiting

Currently, there are no rate limits implemented. However, pytrends may have requests throttled by Google at very high volumes.

🐛 Troubleshooting

API Returns Empty Data

Check that your keywords are spelled correctly
Try with a longer timeframe
Ensure the geographic location code is valid

"Space Paused" Error

The Space has been inactive for 48+ hours
Make a simple request to /health to restart it
Wait 30-60 seconds for startup

Related Queries Endpoint Returns Partial Data

Some keywords may not have related query data
The endpoint returns data for keywords that have it

📝 License

This project uses the pytrends library (MIT License).

🔗 Links

GitHub Repo: Available in HF Spaces
PyTrends Library: https://github.com/GeneralMills/pytrends
Hugging Face Spaces: https://huggingface.co/spaces

📞 Support

For issues or suggestions:

Check this documentation first
Review the API response errors
Verify your parameters are correct
Try with simpler keywords or timeframes