# Trending Topics API

A lightweight JSON endpoint that surfaces current Google Trends "trending now" data, pre-filtered to substantive topic categories (business, science, technology, politics, health, etc.) with sports, entertainment, and celebrity noise stripped out.

**Base URLs:**
```
https://marcomm.fiu.edu/contentplanning/googletrends/trending-json.php
```
```
https://marcomm.fiu.edu/contentplanning/googletrends/trending-table.php
```

## Request

`GET` request. No authentication, no request body — all options are query string parameters.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `geo` | string | `US` | Country code to pull trends for (e.g. `US`, `GB`). |
| `hours` | integer | `24` | Lookback window in hours. Range: 1–191. |
| `limit` | integer | `25` | Max number of trends to return. Range: 1–100. |
| `only` | string | *(see below)* | Comma-separated list of topic categories to include. Overrides the default allow-list. |

### Default topic allow-list

If `only` is not provided, results are filtered to these categories:

`Business and Finance`, `Climate`, `Health`, `Jobs and Education`, `Law and Government`, `Politics`, `Science`, `Technology`

### All available topic categories

`Autos and Vehicles`, `Beauty and Fashion`, `Business and Finance`, `Climate`, `Entertainment`, `Food and Drink`, `Games`, `Health`, `Hobbies and Leisure`, `Jobs and Education`, `Law and Government`, `Other`, `Pets and Animals`, `Politics`, `Science`, `Shopping`, `Sports`, `Technology`, `Travel and Transportation`

## Example requests

Default (US, last 24 hours, top 25, default topic filter):
```
GET https://marcomm.fiu.edu/contentplanning/googletrends/trending-json.php
```

Last 48 hours, top 10 results:
```
GET https://marcomm.fiu.edu/contentplanning/googletrends/trending-json.php?hours=48&limit=10
```

Only science and technology trends:
```
GET https://marcomm.fiu.edu/contentplanning/googletrends/trending-json.php?only=Science,Technology
```

## Response

`Content-Type: application/json`

```json
{
  "geo": "US",
  "hours": 24,
  "topics": ["Business and Finance", "Climate", "Health", "Jobs and Education", "Law and Government", "Politics", "Science", "Technology"],
  "generated_at": 1785267356,
  "trends": [
    {
      "keyword": "tmobile outage",
      "geo": "US",
      "volume": 1000000,
      "growth_pct": 1000,
      "started_at": 1785183000,
      "ended_at": null,
      "topic_ids": [18],
      "topic_names": ["Technology"],
      "related_keywords": ["tmobile outage", "t mobile outage", "is t mobile down", "..."],
      "news": []
    }
  ]
}
```

### Top-level fields

| Field | Type | Description |
|---|---|---|
| `geo` | string | Country code the results are for. |
| `hours` | integer | Lookback window used for this response. |
| `topics` | array of strings | Topic categories applied as the filter. |
| `generated_at` | integer | Unix timestamp when this data was generated (or served from cache). |
| `trends` | array | The trending items, sorted by `volume` descending. |

### Trend object fields

| Field | Type | Description |
|---|---|---|
| `keyword` | string | The trending search term. |
| `geo` | string | Geographic location for this specific trend. |
| `volume` | integer | Approximate search volume. |
| `growth_pct` | integer | Percentage growth in search volume. |
| `started_at` | integer or null | Unix timestamp when the trend started. |
| `ended_at` | integer or null | Unix timestamp when the trend ended, if finished. |
| `topic_ids` | array of integers | Google's internal topic/category IDs for this trend. |
| `topic_names` | array of strings | Human-readable names for `topic_ids`. |
| `related_keywords` | array of strings | Related search queries for this trend. |
| `news` | array | Related news articles, if any (usually empty unless explicitly requested). |

### Error response

On failure, the endpoint returns HTTP `502` with:

```json
{ "error": "description of what went wrong" }
```

## Notes for agent integration

- This is a simple `GET` request — no headers or auth are required to call it.
- Responses are cached server-side for 5 minutes per unique combination of `geo`/`hours`/`limit`/`only`, so repeated calls with the same parameters are fast and won't re-trigger a fresh Google Trends fetch every time.
- Data source is an unofficial Google Trends feed (the same one that powers the Trends "Trending now" page). It can occasionally change shape or become temporarily unavailable without notice — treat non-200 responses or malformed JSON as a transient failure and retry later rather than a hard error.
- Topic classification comes from Google's own tagging and is not perfectly precise — occasional mis-categorized items may appear.