# 🚀 TRENDING API - QUICK START GUIDE

## ✅ Status: LIVE AND WORKING

---

## 📡 Three Main Endpoints

### 1️⃣ Trending Topics (Hashtags)
```bash
GET /api/public/explore/trending/topics?limit=10
```
**Returns**: Top trending hashtags with post counts  
**Example**: `#debate`, `#hypocrisycheck`, `#trendwatch`

### 2️⃣ Trending Today (Posts)
```bash
GET /api/public/explore/trending/today?limit=10
```
**Returns**: Most engaged posts from today  
**Sorted by**: comments + bookmarks + views + quotes

### 3️⃣ All Trending (Combined)
```bash
GET /api/public/explore/trending/all?limit=10
```
**Returns**: Topics + Posts + Users in one response

---

## 💻 Quick Code Examples

### JavaScript Fetch
```javascript
// Get trending topics
fetch('/api/public/explore/trending/topics?limit=10')
  .then(r => r.json())
  .then(data => console.log(data.data))
```

### cURL
```bash
curl "http://localhost:8000/api/public/explore/trending/topics?limit=10"
```

### PHP
```php
$response = file_get_contents('http://localhost:8000/api/public/explore/trending/topics?limit=10');
$data = json_decode($response, true);
print_r($data['data']);
```

---

## 📊 Response Format

All endpoints return:
```json
{
  "status": "success",
  "code": 200,
  "data": [...],
  "count": 10
}
```

---

## 🔑 Parameters

| Param | Type | Range | Default |
|-------|------|-------|---------|
| limit | int | 1-50 | 10 |
| page | int | ≥1 | 1 |

---

## 📈 Data Points

- **Database**: 1,873 total posts
- **Today**: 62 posts created
- **Top hashtag**: #debate (64 posts)
- **Response time**: <500ms cached
- **Cache TTL**: 60-120 seconds

---

## 🔄 Refresh Cache

```bash
# Clear all cache
php artisan cache:clear

# Or in code
Cache::forget('trending_topics_24h_v1');
Cache::forget('trending_posts_24h_v1');
```

---

## ✨ Features

✅ Public access (no auth needed)  
✅ Real-time hashtag extraction  
✅ Engagement-based ranking  
✅ Automatic fallback (24h → 7d → 30d)  
✅ Sub-500ms response time  
✅ Rate limited to 60/min  
✅ Emoji and Unicode support  
✅ Error handling  

---

## 🐛 Common Issues & Fixes

| Issue | Fix |
|-------|-----|
| 401 Unauthorized | Use `/api/public/` prefix |
| Empty results | Check if posts exist in DB |
| 500 Error | Clear cache: `php artisan cache:clear` |
| Slow response | Wait for cache to populate |

---

## 📚 File Locations

- **Service**: `app/Services/Trending/TrendingService.php`
- **Controller**: `app/Http/Controllers/Api/Public/Explore/PublicExploreController.php`
- **Routes**: `routes/api/public.php`

---

## 🎯 What's Working

✅ Hashtag extraction from posts  
✅ Post engagement scoring  
✅ User ranking by followers  
✅ Caching for performance  
✅ Time-based windows  
✅ Public API endpoints  
✅ Error responses  
✅ Query validation  

---

## 📞 Deployment Commands

```bash
# Clear everything
php artisan route:clear
php artisan cache:clear

# Show routes
php artisan route:list | grep trending

# Run tests
php artisan test

# Start server
php artisan serve --port 8000
```

---

## 🚀 Next Steps

1. **Frontend Integration**: Use the 3 endpoints in your UI
2. **Caching**: Implement 60-120s client-side cache
3. **Updates**: Call endpoints every 2-5 minutes for fresh data
4. **Analytics**: Track which trending topics users click

---

## ✅ Go Live Checklist

- [x] All 3 endpoints working
- [x] Database connected
- [x] Caching functional
- [x] Error handling in place
- [x] Rate limiting enabled
- [x] Documentation complete
- [x] Tested and verified

**Status: READY TO DEPLOY** 🚀