{"openapi":"3.1.0","info":{"title":"Rising Trends API","version":"1.0.0","description":"Read-only access to Rising Trends data for Pro subscribers. Authenticate with a Bearer token issued from your dashboard.","contact":{"name":"Rising Trends","url":"https://risingtrends.co"}},"servers":[{"url":"https://www.risingtrends.co/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"rt_live_*"}},"schemas":{"Trend":{"type":"object","required":["id","slug","name","categories","is_brand","is_ecom","search_volume","growth_pct"],"properties":{"id":{"type":"string","example":"rt_trend_12345"},"slug":{"type":"string","example":"magnesium-glycinate"},"name":{"type":["string","null"],"example":"magnesium glycinate"},"definition":{"type":["string","null"]},"categories":{"type":"array","items":{"type":"string"},"example":["Supplements","Health"]},"is_brand":{"type":"boolean"},"is_ecom":{"type":"boolean"},"search_volume":{"type":"object","properties":{"latest":{"type":["number","null"],"example":165000},"history":{"type":"object","additionalProperties":{"type":"number"},"description":"Map of YYYY-MM → monthly search volume.","example":{"2024-01":90000,"2024-02":110000}}}},"growth_pct":{"type":"object","properties":{"3m":{"type":["number","null"]},"6m":{"type":["number","null"]},"1y":{"type":["number","null"]},"2y":{"type":["number","null"]},"5y":{"type":["number","null"]}}},"dashboard_url":{"type":["string","null"]}}},"TrendList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Trend"}},"next_cursor":{"type":["string","null"],"description":"Pagination token for the next page. Pass it back as the `cursor` query param to fetch more results. `null` when there are no more pages."}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"docs_url":{"type":"string"}}}}}}},"paths":{"/health":{"get":{"summary":"Health check","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/trends":{"get":{"summary":"Search trends","description":"**What it does**\n\nReturns a paginated list of trends matching your filters. Narrow results by category, brand vs keyword, product vs service, minimum search volume, and minimum growth over a specific timeframe. Sort by growth, search volume, or date added.\n\n**How to use it**\n\nCombine filters to find trends matching specific criteria. The most powerful pattern: set a `timeframe`, sort by `growth`, then add `category` and `min_search_volume` to scope and reduce noise. Walk the full result set using `next_cursor` from each response.\n\nExample — find ecom keywords (not brands) that grew 100%+ in the past year with at least 1,000 monthly searches:\n\n```\nGET /trends?is_ecom=true&is_brand=false&min_growth_pct=100&timeframe=1y&min_search_volume=1000&sort=growth\n```\n\n**What people build with it**\n\n- **Rising-keyword finder for SEO** — schedule a weekly query in your category to surface long-tail keywords before they're saturated.\n- **Product opportunity scanner for ecom** — combine `is_ecom=true&is_brand=false&min_growth_pct=100` to surface generic physical products primed for private label or dropshipping.\n- **Newsletter / content automation** — pull the top 20 rising trends in your beat each Monday and feed them into your CMS as draft topics.","parameters":[{"name":"is_brand","in":"query","schema":{"type":"boolean"},"description":"Filter to brand trends (true) or non-brand (false)."},{"name":"is_ecom","in":"query","schema":{"type":"boolean"},"description":"Filter to physical product trends."},{"name":"category","in":"query","schema":{"type":"string","enum":["Accessories","Activities & Hobbies","Agriculture","Alcohol","Alternative Medicine","Art & Design","Artificial Intelligence","Autos & Vehicles","Banking","Beauty Tools","Beverages","Books & Literature","Clothing","Construction","Consumer Electronics","Cooking & Recipes","Crypto","Cybersecurity","Education","Energy","Entrepreneurship","Family & Relationships","Fitness","Food","Footwear","Gambling","Gaming","Gardening","Haircare","Health Conditions","Home Appliances","Home Improvement","Human Resources","Insurance","Interior Design","Internet of Things (IoT)","Investing","Jewelry","Legal","Logistics & Supply Chain","Luxury","Makeup & Cosmetics","Management","Manufacturing","Marketing","Mental Health","Mining","Movies & Television","Music","Nutrition","Personal Finance","Pets","Pharmacy","Real Estate","Retail","Science","Skincare","Sleep","Social Issues","Software","Sports","Sustainability","Taxation","Travel","VR & AR","Vitamins & Supplements","Workplace"]},"description":"Single category match (case-sensitive). One of the values listed below."},{"name":"min_search_volume","in":"query","schema":{"type":"integer","minimum":0},"description":"Filter trends whose latest monthly search volume ≥ value."},{"name":"timeframe","in":"query","schema":{"type":"string","enum":["3m","6m","1y","2y","5y"],"default":"5y"},"description":"Growth window. Used by `sort=growth` and `min_growth_pct`."},{"name":"min_growth_pct","in":"query","schema":{"type":"number"},"description":"Filter trends whose growth in the selected `timeframe` ≥ value."},{"name":"sort","in":"query","schema":{"type":"string","enum":["growth","search_volume","date_added"],"default":"search_volume"}},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination token. To get the next page of results, take the `next_cursor` value from the previous response and pass it here. Treat the value as a black box — don't try to construct or modify it."}],"responses":{"200":{"description":"List of trends","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrendList"}}}},"400":{"description":"invalid_parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"subscription_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or monthly_quota_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/trends/{slug}":{"get":{"summary":"Get trend details","description":"**What it does**\n\nReturns the full profile of a single trend: definition, all categories, complete monthly search volume history (going back to when the trend first appeared), growth percentages across timeframes (3m, 6m, 1y, 2y, 5y), brand and product flags, and a dashboard link.\n\n**How to use it**\n\nPass the trend's `slug`, which you'll typically get from a `Search trends` response or from a dashboard URL like `/dashboard/trend/magnesium-glycinate`. Use this endpoint whenever you need the full search volume time series — for charting, forecasting, or pulling out specific data points.\n\nExample:\n\n```\nGET /trends/magnesium-glycinate\n```\n\n**What people build with it**\n\n- **Pitch / thesis validators** — verify a startup or product claim like \"this market is exploding\" against real growth numbers, in seconds.\n- **Trend trajectory charts** — feed the monthly history into a charting library (Chart.js, Recharts) to visualize the curve — early growth, peak, decline.\n- **Campaign launch timing** — plot the search volume curve to pick the right month to release a product, push content, or send a press pitch.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"magnesium-glycinate"}],"responses":{"200":{"description":"The trend","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Trend"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"subscription_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or monthly_quota_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}