README.md

---
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](https://github.com/GeneralMills/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:**
```json
{
  "status": "healthy"
}
```

---

### 2. Root Endpoint

**Endpoint:** `GET /`

Get information about available endpoints.

**Response:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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

```bash
# 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

```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

```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

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

### n8n

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

### Zapier

1. Use **Webhooks by Zapier** → **Catch Raw Hook**
2. Or use **HTTP** action with GET method
3. URL: `https://trymonolith-pytrends-api.hf.space/trending_searches?country=india`
4. 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:
```json
{
  "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](https://github.com/GeneralMills/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:
1. Check this documentation first
2. Review the API response errors
3. Verify your parameters are correct
4. Try with simpler keywords or timeframes