Hyperaware Trends API

openapi: 3.2.0
info:
  contact:
    email: hello@hyperaware.live
    name: Hyperaware API Support
    url: https://hyperaware.live
  description: 'One POST endpoint for trend data: historical time series, point-to-point growth windows, and live trending feeds across Google, Google Images, Google News, Google Shopping, YouTube, Wikipedia, TikTok, Amazon, Pinterest, npm, PyPI, Steam, Google Play, App Store, GitHub, Google Trends, IMDb, Open Library, Polymarket, Reddit, Web, Spotify, Substack, X, Instagram, Bluesky, Hacker News. Scores use a 0-100 index with absolute volume where available. Pick the operation with the `mode` field in the JSON body. The same operations are also available as MCP tools at `https://api.hyperaware.live/mcp`. Free API key (100 requests/month): https://hyperaware.live/account'
  summary: Live trend data across search, social, commerce, news, and developer platforms
  termsOfService: https://hyperaware.live/terms
  title: Hyperaware Trends API
  version: 1.0.0
  x-logo:
    altText: Hyperaware API
    url: https://hyperaware.live/brand/hyperaware.live/logo.png
  x-mcp-server: https://api.hyperaware.live/mcp
servers:
- description: Production
  url: https://api.hyperaware.live
security:
- bearerAuth: []
tags:
- description: Trend data operations
  name: Trends
paths:
  /api:
    post:
      description: 'Run one tool, picked by the `mode` field: `get_time_series` (full history for one topic, 1 request per source (data type) in the call; ''all'' = every keyword source); `get_growth` (how fast something is rising, 1 request per source (data type) in the call, every window included; ''all'' = every keyword source); `get_top_trends` (what''s moving right now, 1 request per 10 rows per board: limit 100 (the default) = 10 requests per board); `get_context` (what people are saying, 1 request per source (data type) in the call; ''all'' = every context source); `get_reviews` (what customers say, 1 request per source (data type) in the call; ''all'' = every review source).'
      operationId: queryTrends
      requestBody:
        content:
          application/json:
            examples:
              get_context:
                summary: Get Context
                value:
                  keyword: nvidia
                  mode: get_context
                  source: News
              get_growth:
                summary: Get Growth
                value:
                  keyword: electric vehicles
                  mode: get_growth
                  percent_growth:
                  - 3M
                  - 12M
                  source: Google Search
              get_reviews:
                summary: Get Reviews
                value:
                  keyword: notion
                  mode: get_reviews
                  source: App Store
              get_time_series:
                summary: Get Time Series
                value:
                  keyword: electric vehicles
                  mode: get_time_series
                  source: Google Search
              get_top_trends:
                summary: Get Top Trends
                value:
                  limit: 10
                  mode: get_top_trends
                  type: Google Trends
            schema:
              discriminator:
                mapping:
                  get_context: '#/components/schemas/GetContextRequest'
                  get_growth: '#/components/schemas/GetGrowthRequest'
                  get_time_series: '#/components/schemas/GetTimeSeriesRequest'
                  get_top_trends: '#/components/schemas/GetTopTrendsRequest'
                propertyName: mode
              oneOf:
              - $ref: '#/components/schemas/GetTimeSeriesRequest'
              - $ref: '#/components/schemas/GetGrowthRequest'
              - $ref: '#/components/schemas/GetTopTrendsRequest'
              - $ref: '#/components/schemas/GetContextRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                get_context:
                  summary: Get Context
                  value:
                    body: '{"keyword": "nintendo switch 2", "window_days": 7, "count": 1, "sources": [{"source": "YouTube", "count": 1, "error": null, "items": [{"kind": "video", "title": "Switch 2 review", "url": "https://youtube.com/watch?v=…", "published": "2026-10-22T09:39:22Z", "engagement": {"views": 91542, "likes": 5997, "comments": 527}}]}]}'
                    statusCode: 200
                get_growth:
                  summary: Get Growth
                  value:
                    body: '{"search_term": "nike", "data_source": "google search", "results": [{"period": "12M", "growth": -12.31, "direction": "decrease", "recent_date": "2026-10-24", "baseline_date": "2025-10-25", "recent_value": 57, "baseline_value": 65, "volume_growth": -12.31}]}'
                    statusCode: 200
                get_time_series:
                  summary: Get Time Series
                  value:
                    body: '[{"date": "2026-10-17", "value": 47, "volume": 25853617, "keyword": "bitcoin", "source": "google search"}, {"date": "2026-10-24", "value": 52, "volume": 28012440, "keyword": "bitcoin", "source": "google search"}]'
                    statusCode: 200
                get_top_trends:
                  summary: Get Top Trends
                  value:
                    body: '{"type": "Google Trends", "as_of_ts": "2026-10-27T12:00:00Z", "count": 3, "data": [[1, "world series"], [2, "election polls"], [3, "halloween costumes"]]}'
                    statusCode: 200
              schema:
                $ref: '#/components/schemas/Envelope'
          description: 'HTTP 200 with the REST envelope. REST answers HTTP 200 with an envelope: `{"statusCode": 400, "body": "…"}`. Read `statusCode`, then parse `body`. A missing or wrong key is the exception: HTTP 401 (`missing_api_key`) or 403 (`invalid_api_key`), with the error object as the body. Errors carry an `error` code and a `message`. Over MCP, a failed call sets `isError` on the tool result.'
        '401':
          content:
            application/json:
              example:
                error: missing_api_key
                message: Missing API key. Send it in the Authorization header.
              schema:
                $ref: '#/components/schemas/Error'
          description: 'missing_api_key: No key was sent. Send it in the Authorization header as Bearer <key>. REST answers HTTP 401.'
        '403':
          content:
            application/json:
              example:
                error: invalid_api_key
                message: Invalid API key. Check the key in your account.
              schema:
                $ref: '#/components/schemas/Error'
          description: 'invalid_api_key: The key is mistyped or was regenerated. Get or copy your key on /account. REST answers HTTP 403.'
      security:
      - bearerAuth: []
      summary: Query trend data
      tags:
      - Trends
components:
  schemas:
    Error:
      description: 'The error object: the parsed envelope body when statusCode is not 2xx, or the response body itself on the HTTP 401 and 403 key errors.'
      properties:
        error:
          enum:
          - missing_parameter
          - invalid_source
          - invalid_mode
          - invalid_request
          - no_data
          - source_unavailable
          - growth_calculation_failed
          - internal_error
          - missing_api_key
          - invalid_api_key
          - monthly_limit_reached
          type: string
        message:
          type: string
        request_id:
          description: Present on internal_error; quote it when contacting support.
          type: string
      type: object
    TimeSeriesResponse:
      description: ~5 years of weekly data points, oldest to newest.
      items:
        $ref: '#/components/schemas/TimeSeriesPoint'
      type: array
    GetTimeSeriesRequest:
      properties:
        country:
          description: 'ISO 3166-1 alpha-2 country code (US, GB, JP). Boards, TikTok and review stores default to US; Google time series and growth default to worldwide. Only for: Google Search, Google Images, Google News, Google Shopping, YouTube, TikTok, Pinterest.'
          type: string
        keyword:
          description: 'What to look up. The string format is required by source. Google Search, Google Images, Google News, Google Shopping, YouTube, Wikipedia, TikTok, Amazon, Pinterest: any name or phrase, e.g. ''nike''. npm: Exact npmjs.com package name, case-sensitive. Right: ''react'', ''@babel/core''. Wrong: ''React'', ''React.js''. Python: Exact PyPI project name. Right: ''pandas'', ''requests''. Wrong: ''Pandas''. Steam: Game display name in plain English, not a Steam App ID. Right: ''Elden Ring'', ''CS2''. First Steam store search result wins, so use an unambiguous name. App Downloads: Android bundle ID only (the id= value on Google Play). Right: ''com.openai.chatgpt'', ''com.whatsapp''. Wrong: ''ChatGPT'', ''WhatsApp'', an iOS App Store ID, or a bundle ID that is not Android. Find it at play.google.com/store/apps/details?id=THIS_PART. App Rankings: Android bundle ID only (the id= value on Google Play). Right: ''com.openai.chatgpt'', ''com.whatsapp''. Wrong: ''ChatGPT'', ''WhatsApp'', an iOS App Store ID, or a bundle ID that is not Android. Find it at play.google.com/store/apps/details?id=THIS_PART.'
          type: string
        language:
          default: en
          description: 'Wikipedia language edition (en, de, ja, pt); defaults to en. Only for: Wikipedia.'
          type: string
        mode:
          const: get_time_series
          description: 'Canonical name (matches the MCP tool). Aliases: ''get_trends'', ''trends'', ''time_series'', ''lookup''.'
          type: string
        resolution:
          default: weekly
          description: '''weekly'' (about 5 years, default) or ''daily'' (last 90 days, fetched live). Only for: Google Search, Google Images, Google News, Google Shopping, YouTube.'
          enum:
          - weekly
          - daily
          type: string
        source:
          description: Exactly one source per request.
          enum:
          - Google Search
          - Google Images
          - Google News
          - Google Shopping
          - YouTube
          - Wikipedia
          - TikTok
          - Amazon
          - Pinterest
          - npm
          - Python
          - Steam
          - App Downloads
          - App Rankings
          type: string
      required:
      - mode
      - source
      - keyword
      type: object
    GrowthResponse:
      properties:
        data_source:
          type: string
        metadata:
          properties:
            all_successful:
              type: boolean
            calculations_completed:
              type: integer
            total_data_points:
              type: integer
          type: object
        results:
          items:
            $ref: '#/components/schemas/GrowthResult'
          type: array
        search_term:
          type: string
      type: object
    ContextResponse:
      description: Per source, the posts, videos, stories and markets about the keyword, best first.
      properties:
        keyword:
          description: The keyword you asked for.
          type: string
        sources:
          items:
            properties:
              error:
                description: Why a source returned nothing, when it failed.
                type:
                - string
                - 'null'
              items:
                description: 'Each item: kind, url, title, text, author, published, engagement (views, likes, comments, shares, score…), top_comments.'
                type: array
              source:
                description: The source.
                type: string
            type: object
          type: array
        window_days:
          description: How far back it looked.
          type: number
      type: object
    GrowthResult:
      properties:
        baseline_date:
          format: date
          type: string
        baseline_value:
          type: number
        baseline_volume:
          type:
          - number
          - 'null'
        direction:
          description: '''increase'' or ''decrease''.'
          type: string
        growth:
          description: Percentage change, e.g. -12.31.
          type: number
        period:
          type: string
        recent_date:
          format: date
          type: string
        recent_value:
          type: number
        recent_volume:
          type:
          - number
          - 'null'
        volume_available:
          type: boolean
        volume_growth:
          type:
          - number
          - 'null'
      type: object
    TopTrendsResponse:
      properties:
        as_of_ts:
          format: date-time
          type: string
        baseline_ts:
          description: Present only when sort is 'rank_change'.
          format: date-time
          type: string
        category:
          type: string
        count:
          type: integer
        data:
          items:
            oneOf:
            - description: '[rank, keyword] for sort=''rank''.'
              prefixItems:
              - description: Current rank.
                type: integer
              - description: Keyword or item name.
                type: string
              type: array
            - description: Mover row for sort='rank_change'.
              properties:
                category_path:
                  type: string
                keyword:
                  type: string
                prev_rank:
                  type: integer
                rank:
                  type: integer
                rank_change:
                  description: Positions climbed.
                  type: integer
              type: object
          type: array
        limit:
          type: integer
        note:
          description: Present when count is 0 to explain why and what to do next.
          type: string
        sort:
          type: string
        type:
          type: string
        window:
          type: string
      type: object
    GetGrowthRequest:
      properties:
        country:
          description: 'ISO 3166-1 alpha-2 country code (US, GB, JP). Boards, TikTok and review stores default to US; Google time series and growth default to worldwide. Only for: Google Search, Google Images, Google News, Google Shopping, YouTube, TikTok, Pinterest.'
          type: string
        keyword:
          description: 'What to look up. The string format is required by source. Google Search, Google Images, Google News, Google Shopping, YouTube, Wikipedia, TikTok, Amazon, Pinterest: any name or phrase, e.g. ''nike''. npm: Exact npmjs.com package name, case-sensitive. Right: ''react'', ''@babel/core''. Wrong: ''React'', ''React.js''. Python: Exact PyPI project name. Right: ''pandas'', ''requests''. Wrong: ''Pandas''. Steam: Game display name in plain English, not a Steam App ID. Right: ''Elden Ring'', ''CS2''. First Steam store search result wins, so use an unambiguous name. App Downloads: Android bundle ID only (the id= value on Google Play). Right: ''com.openai.chatgpt'', ''com.whatsapp''. Wrong: ''ChatGPT'', ''WhatsApp'', an iOS App Store ID, or a bundle ID that is not Android. Find it at play.google.com/store/apps/details?id=THIS_PART. App Rankings: Android bundle ID only (the id= value on Google Play). Right: ''com.openai.chatgpt'', ''com.whatsapp''. Wrong: ''ChatGPT'', ''WhatsApp'', an iOS App Store ID, or a bundle ID that is not Android. Find it at play.google.com/store/apps/details?id=THIS_PART.'
          type: string
        language:
          default: en
          description: 'Wikipedia language edition (en, de, ja, pt); defaults to en. Only for: Wikipedia.'
          type: string
        mode:
          const: get_growth
          description: 'Canonical name (matches the MCP tool). Alias: ''growth''.'
          type: string
        percent_growth:
          default:
          - 12M
          description: Growth windows. Each item is a window string or, on REST only, a custom date-range object. Every window is a two-date comparison. `window` is accepted as a REST alias.
          items:
            oneOf:
            - description: 'Any whole number plus a D, W, M, or Y suffix, up to 5 years (e.g. ''7D'', ''17D'', ''45D'', ''3M'', ''18M'', ''2Y''), or MTD, QTD, YTD. Common presets: 7D, 1W, 14D, 2W, 30D, 1M, 2M, 3M, 6M, 9M, 12M, 1Y, 18M, 24M, 2Y, 36M, 3Y, 48M, 4Y, 60M, 5Y, MTD, QTD, YTD.'
              type: string
            - description: Custom date range. REST only; MCP accepts the string windows.
              properties:
                baseline:
                  format: date
                  type: string
                name:
                  description: Optional label.
                  type: string
                recent:
                  format: date
                  type: string
              required:
              - recent
              - baseline
              type: object
          type: array
        resolution:
          default: weekly
          description: '''weekly'' (about 5 years, default) or ''daily'' (last 90 days, fetched live). Only for: Google Search, Google Images, Google News, Google Shopping, YouTube.'
          enum:
          - weekly
          - daily
          type: string
        source:
          description: One source, or comma-separated sources for get_growth (e.g. 'amazon, tiktok, youtube'). get_time_series takes exactly one.
          enum:
          - Google Search
          - Google Images
          - Google News
          - Google Shopping
          - YouTube
          - Wikipedia
          - TikTok
          - Amazon
          - Pinterest
          - npm
          - Python
          - Steam
          - App Downloads
          - App Rankings
          type: string
      required:
      - mode
      - source
      - keyword
      type: object
    TimeSeriesPoint:
      properties:
        date:
          format: date
          type: string
        keyword:
          type: string
        source:
          type: string
        value:
          description: Trend score on a 0-100 index.
          maximum: 100
          minimum: 0
          type: number
        volume:
          description: Absolute volume where available.
          type:
          - number
          - 'null'
      type: object
    GetContextRequest:
      description: 'What people are posting, reading and betting about a keyword right now: posts, videos, stories, comments and markets from each source, with engagement.'
      properties:
        days:
          description: Look back 1 to 30 days. Default 7.
          type: integer
        hashtag:
          description: 'true: the keyword is an exact hashtag; TikTok and Instagram return their top posts for it.'
          type: boolean
        keyword:
          description: Any name or phrase.
          type: string
        limit:
          description: Items per source, 1 to 20. Default 10.
          type: integer
        mode:
          const: get_context
          description: Canonical name (matches the MCP tool).
          type: string
        source:
          description: 'One source, several separated by commas, or ''all''. One of: News, YouTube, TikTok, Instagram, X, Reddit, Bluesky, Hacker News, Polymarket, GitHub.'
          type: string
      required:
      - mode
      - keyword
      - source
      type: object
    GetTopTrendsRequest:
      properties:
        category:
          description: 'Required when type is one of: Amazon Best Sellers by Category, Google Trends by Category, Pinterest Trending by Category, Top Websites, Substack by Category, TikTok Trending Hashtags by Category. Use the official category name (case-insensitive).'
          type: string
        country:
          description: 'ISO 3166-1 alpha-2 code (US, GB, JP); default US. Only for: Google Trends, Google Trends by Category, Pinterest Trending, Pinterest Trending by Category, TikTok Trending Hashtags, TikTok Trending Hashtags by Category, X (Twitter) Trending, YouTube Trending.'
          type: string
        limit:
          default: 25
          description: Max rows to return. Free plan boards return the top 10 only.
          maximum: 200
          minimum: 1
          type: integer
        mode:
          const: get_top_trends
          description: 'Canonical name (matches the MCP tool). Alias: ''top_trends''.'
          type: string
        offset:
          default: 0
          description: Rows to skip for pagination. Pinned to 0 on the Free plan; pagination is a paid feature.
          minimum: 0
          type: integer
        sort:
          default: rank
          description: '''rank'': current leaders. ''rank_change'': biggest climbers vs a prior snapshot (rows include prev_rank and rank_change).'
          enum:
          - rank
          - rank_change
          type: string
        type:
          description: One live feed. Required on both REST and MCP; omitting it returns a 400 missing_parameter error.
          enum:
          - Amazon Best Sellers Top Rated
          - Amazon Best Sellers by Category
          - App Store Top Free
          - App Store Top Paid
          - GitHub
          - Google News Top News
          - Google Play
          - Google Trends
          - Google Trends by Category
          - IMDb MOVIEmeter
          - Open Library Trending Books
          - Pinterest Trending
          - Pinterest Trending by Category
          - Polymarket Top Markets
          - Reddit Hot Posts
          - Reddit World News
          - Top Websites
          - Spotify Top Podcasts
          - Steam Most Played
          - Substack
          - Substack by Category
          - TikTok Trending Hashtags
          - TikTok Trending Hashtags by Category
          - TikTok Trending Searches
          - Wikipedia Trending
          - X (Twitter) Trending
          - YouTube Trending
          type: string
        window:
          default: 30d
          description: Lookback used only when sort is 'rank_change'. Short windows only have baselines on daily feeds.
          enum:
          - 1d
          - 3d
          - 7d
          - 14d
          - 30d
          type: string
      required:
      - mode
      - type
      type: object
    Envelope:
      description: 'REST answers HTTP 200 with an envelope: `{"statusCode": 400, "body": "…"}`. Read `statusCode`, then parse `body`. A missing or wrong key is the exception: HTTP 401 (`missing_api_key`) or 403 (`invalid_api_key`), with the error object as the body. Errors carry an `error` code and a `message`. Over MCP, a failed call sets `isError` on the tool result.'
      properties:
        body:
          contentMediaType: application/json
          contentSchema:
            oneOf:
            - $ref: '#/components/schemas/TimeSeriesResponse'
            - $ref: '#/components/schemas/GrowthResponse'
            - $ref: '#/components/schemas/TopTrendsResponse'
            - $ref: '#/components/schemas/ContextResponse'
            - $ref: '#/components/schemas/Error'
          description: 'JSON text: parse it a second time. On success it matches the tool''s response schema; any other statusCode means it parses to Error.'
          type: string
        statusCode:
          description: 'The real outcome: 200 on success, otherwise the error status.'
          type: integer
      required:
      - statusCode
      - body
      type: object
  securitySchemes:
    bearerAuth:
      description: API key (format `tmcp_live_...`). Get one free at https://hyperaware.live/account
      scheme: bearer
      type: http
externalDocs:
  description: API reference
  url: https://hyperaware.live/docs