Add comprehensive API documentation with all endpoints and examples

README.md

@@ -1,6 +1,6 @@
 ---
-title: Pytrends Api
-emoji: 📈
+title: Pytrends API
+emoji: 📊
 colorFrom: purple
 colorTo: blue
 sdk: docker
@@ -8,4 +8,423 @@ pinned: false
 short_description: Self-hosted pytrends API for Google Trends data via HTTP
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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