# SocialCrawl API: google_trends endpoints
# Base URL: https://www.socialcrawl.dev
# Auth: x-api-key header
# Full docs: https://www.socialcrawl.dev/docs/google_trends

## GET /v1/google_trends/explore
Get Google Trends interest over time
Credit cost: 5 (advanced)
Parameters:
- keywords (required): 1-5 comma-separated keywords (e.g. 'reverse audio,voice changer'). With multiple keywords the 0-100 values are normalised across the set for direct comparison. Each keyword must be 2 to 100 characters. More than 5 keywords, a 1-character keyword, or a keyword made only of punctuation is rejected with a free 400 before the request is billed.
- location (optional, string): Location as an ISO country code ('US', 'KR'), a full country name as Google Trends spells it ('United States', 'South Korea'), or a numeric location code ('2840'). Common spellings and ISO codes are normalised, so 'KR', 'Korea' and 'South Korea' all reach the same place. Google Trends does not publish every country, and a location it has no data for is rejected with a free 400 naming the accepted forms; a 404 means the keyword had no data there, not that the location is unsupported. Defaults to worldwide-leaning US.
- timeframe (optional, enum: past_hour | past_4_hours | past_day | past_7_days | past_30_days | past_90_days | past_12_months | past_5_years): Preset time window: past_hour, past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, or past_5_years. Defaults to past_12_months.
- category (optional, integer): Numeric Google Trends category code to scope the query (default 0 = all categories). A non-numeric value is rejected with a free 400 rather than silently returning an all-categories series.
curl -G "https://www.socialcrawl.dev/v1/google_trends/explore" \
  --data-urlencode "keywords=uv index" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/google_trends/rising
Get related + rising Google Trends queries
Credit cost: 5 (advanced)
Parameters:
- keyword (required): Single keyword to expand (e.g. 'uv index'). Google Trends returns the related-queries list for one keyword only, so a comma-separated value is rejected with a free 400 before the request is billed. The keyword must be 2 to 100 characters; use /v1/google_trends/explore for multi-keyword comparisons.
- location (optional, string): Location as an ISO country code ('US', 'KR'), a full country name as Google Trends spells it ('United States', 'South Korea'), or a numeric location code ('2840'). Common spellings and ISO codes are normalised, so 'KR', 'Korea' and 'South Korea' all reach the same place. Google Trends does not publish every country, and a location it has no data for is rejected with a free 400 naming the accepted forms; a 404 means the keyword had no data there, not that the location is unsupported. Defaults to worldwide-leaning US.
- timeframe (optional, enum: past_hour | past_4_hours | past_day | past_7_days | past_30_days | past_90_days | past_12_months | past_5_years): Preset time window: past_hour, past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, or past_5_years. Defaults to past_12_months.
- category (optional, integer): Numeric Google Trends category code to scope the related-query lists (default 0 = all categories). The same codes /v1/google_trends/explore accepts; 0 is every category. A non-numeric value is rejected with a free 400.
curl -G "https://www.socialcrawl.dev/v1/google_trends/rising" \
  --data-urlencode "keyword=uv index" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/google_trends/trending
Get Google Trends Trending Now for a location
Credit cost: 5 (advanced)
Parameters:
- location (required): Where to read trends. An ISO country code ('DE', 'US', 'KR'), its English name ('Germany'), or an ISO 3166-2 region inside it ('DE-BY', 'US-CA', 'GB-SCT'). Google covers 125 countries and has no worldwide list; a country it does not cover is rejected with a free 400.
- hours (optional, enum: 4 | 24 | 48 | 168): Only trends that started in the past 4, 24, 48 or 168 hours (7 days). Defaults to 24.
- category (optional, enum: autos_and_vehicles | beauty_and_fashion | business_and_finance | 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 | climate): Keep trends Google tagged with this category: 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, or travel_and_transportation. These are Trending Now's categories, not the numeric codes /v1/google_trends/explore takes. Defaults to every category.
- status (optional, enum: all | active): `active` keeps only trends that are still trending. Defaults to `all`, which also returns trends that have already ended inside the window.
- sort (optional, enum: relevance | search_volume | recency | title): relevance (Google's own order, the default), search_volume (largest first), recency (most recently started first), or title (A to Z).
- limit (optional, integer): How many trends to return after filtering and sorting, 1 to 500. Defaults to 100.
curl -G "https://www.socialcrawl.dev/v1/google_trends/trending" \
  --data-urlencode "location=DE" \
  -H "x-api-key: YOUR_API_KEY"