{
  "openapi": "3.1.0",
  "info": {
    "title": "Swellmeter Trending API API",
    "version": "1.0.0",
    "summary": "Google Trends trending-now API: live trending searches for 30 countries (rank, approximate traffic, start time, news links), the full day list per country with first/last seen and peak traffic, 30 days of history, topics trending in several countries at once, and a topic search over the history. REST + MCP server.",
    "description": "Paid API keys from $19/month (Watcher: 6,000 calls a month); free tier 50 calls a day per IP with no key. Buy: https://swellmeter-api.cybermax-tools.workers.dev/buy/watcher?s=lead · all plans: https://swellmeter-api.cybermax-tools.workers.dev/docs#pricing\n\nPricing: free tier 50 calls/day per IP, no key. Paid API keys: Watcher $19/month = 6,000 calls/month; Desk $49/month = 25,000 calls/month; Platform $99/month = 75,000 calls/month; Pay as you go $5 = 1,500 calls (one-time pack); Watcher yearly $190/year = 6,000 calls/month; Desk yearly $490/year = 25,000 calls/month; Platform yearly $990/year = 75,000 calls/month. Get a key: https://swellmeter-api.cybermax-tools.workers.dev/docs#pricing\n\nWhat people are searching for right now in 30 countries, plus what Google's own feed forgets: every topic that trended today or on any of the last 30 days, when it first appeared, its peak traffic, which countries share it, and the news behind it. For newsrooms, content teams, marketers and AI agents. 50 free calls a day, no key; plans from $5 (one-time pack) or $19/month.\n\nFree tier: Up to 5 countries per call; 10 calls a minute per IP on the free tier. Free tier: 50 calls a day per IP, no key. Paid keys from $5 (one-time pack) or $19/month (see Get an API key). Each API call counts once, whatever the number of rows. /api/countries is free. Failed calls are not counted. Source: Google's public \"Trending now\" RSS feed, which lists the 10 newest trending searches per country. We read each country about every 15 minutes and keep what scrolls off: the day list and 30 days of history (history starts 1 Oct 2026). Traffic is Google's own rounded lower bound (e.g. \"2000+\"). Not affiliated with Google. Keyword interest-over-time is not in this API (see the Apify tool). No key needed. Remote MCP server: https://swellmeter-api.cybermax-tools.workers.dev/mcp",
    "contact": {
      "name": "CyberMax",
      "url": "https://cybermax-tools-cybermax.static.hf.space/"
    },
    "license": {
      "name": "Proprietary (free tier + paid API keys)",
      "identifier": "LicenseRef-CyberMax"
    },
    "x-pricing": {
      "api": "Swellmeter Trending API",
      "currency": "USD",
      "free": {
        "price": 0,
        "callsPerDayPerIp": 50,
        "perMinutePerIp": 10,
        "key": "none needed"
      },
      "plans": [
        {
          "id": "watcher",
          "name": "Watcher",
          "price": 19,
          "billing": "per month",
          "calls": 6000,
          "per": "calendar month (UTC)",
          "perMinute": 30,
          "buy": "https://swellmeter-api.cybermax-tools.workers.dev/buy/watcher?s=openapi"
        },
        {
          "id": "desk",
          "name": "Desk",
          "price": 49,
          "billing": "per month",
          "calls": 25000,
          "per": "calendar month (UTC)",
          "perMinute": 60,
          "buy": "https://swellmeter-api.cybermax-tools.workers.dev/buy/desk?s=openapi"
        },
        {
          "id": "platform",
          "name": "Platform",
          "price": 99,
          "billing": "per month",
          "calls": 75000,
          "per": "calendar month (UTC)",
          "perMinute": 120,
          "buy": "https://swellmeter-api.cybermax-tools.workers.dev/buy/platform?s=openapi"
        },
        {
          "id": "payg",
          "name": "Pay as you go",
          "price": 5,
          "billing": "one-time",
          "calls": 1500,
          "per": "until used",
          "perMinute": 30,
          "buy": "https://swellmeter-api.cybermax-tools.workers.dev/buy/payg?s=openapi"
        },
        {
          "id": "watcher-yearly",
          "name": "Watcher yearly",
          "price": 190,
          "billing": "per year",
          "calls": 6000,
          "per": "calendar month (UTC)",
          "perMinute": 30,
          "buy": "https://swellmeter-api.cybermax-tools.workers.dev/buy/watcher-yearly?s=openapi"
        },
        {
          "id": "desk-yearly",
          "name": "Desk yearly",
          "price": 490,
          "billing": "per year",
          "calls": 25000,
          "per": "calendar month (UTC)",
          "perMinute": 60,
          "buy": "https://swellmeter-api.cybermax-tools.workers.dev/buy/desk-yearly?s=openapi"
        },
        {
          "id": "platform-yearly",
          "name": "Platform yearly",
          "price": 990,
          "billing": "per year",
          "calls": 75000,
          "per": "calendar month (UTC)",
          "perMinute": 120,
          "buy": "https://swellmeter-api.cybermax-tools.workers.dev/buy/platform-yearly?s=openapi"
        }
      ],
      "unit": "calls",
      "howToUse": {
        "header": "x-api-key: YOUR_KEY",
        "alt": [
          "Authorization: Bearer YOUR_KEY",
          "?key=YOUR_KEY"
        ],
        "mcp": "send the key as Authorization: Bearer YOUR_KEY",
        "usage": "https://swellmeter-api.cybermax-tools.workers.dev/key"
      },
      "manageKey": "https://swellmeter-api.cybermax-tools.workers.dev/manage",
      "payments": "Stripe Checkout: card, Apple Pay, Google Pay, Link; sales tax/VAT handled by Stripe. Cancel any time at https://swellmeter-api.cybermax-tools.workers.dev/manage."
    }
  },
  "servers": [
    {
      "url": "https://swellmeter-api.cybermax-tools.workers.dev"
    }
  ],
  "paths": {
    "/api/trending": {
      "get": {
        "tags": [
          "Swellmeter Trending API"
        ],
        "summary": "What is trending right now, per country",
        "description": "The newest trending searches for 1-5 countries (up to 10 each, Google rank order): query, approxTraffic (Google's rounded lower bound, e.g. 2000+) and traffic as a number, started (when Google says the trend began), firstSeenToday and snapshotsToday (from our polling), alsoTrendingIn (other countries where the same search is trending now) and up to 3 news articles. snapshots says how fresh each country is.",
        "operationId": "trendingNowGet",
        "parameters": [
          {
            "name": "geo",
            "in": "query",
            "required": false,
            "description": "ISO-2 country code, or up to 5 separated by commas (US, GB, DE, IN, BR, JP, ...). See /api/countries.",
            "schema": {
              "type": "string"
            },
            "example": "US,GB"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per country, 1-10 (default 10)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {
                  "results": [
                    {
                      "geo": "US",
                      "country": "United States",
                      "rank": 8,
                      "query": "flash flood warning",
                      "approxTraffic": "500+",
                      "traffic": 500,
                      "started": "2026-10-01T04:00:00Z",
                      "firstSeenToday": "2026-10-01T04:29:53Z",
                      "snapshotsToday": 3,
                      "alsoTrendingIn": [],
                      "news": [
                        {
                          "title": "Conservative Freedom Fest with Kid Rock canceled after only 6 VIP tickets sell",
                          "url": "https://www.usatoday.com/story/entertainment/music/2026/09/22/freedom-fest-cancelled-low-vip-ticket-sales/91894276007/",
                          "source": "USA Today"
                        },
                        {
                          "title": "Eric Deters cancels Freedom Fest amid low VIP ticket sales",
                          "url": "https://www.cincinnati.com/story/news/politics/2026/09/21/eric-deters-cancels-freedom-fest-amid-low-vip-ticket-sales/91871302007/",
                          "source": "Cincinnati Enquirer"
                        },
                        {
                          "title": "Kid Rock MAGAFest Goes Bust, Wendy's Goes Emo and More Top Stories of the Week",
                          "url": "https://metalinjection.net/injection-reflection/kid-rock-magafest-wendys-top-stories-of-the-week",
                          "source": "Metal Injection"
                        }
                      ]
                    },
                    {
                      "geo": "GB",
                      "country": "United Kingdom",
                      "rank": 1,
                      "query": "strait of hormuz",
                      "approxTraffic": "2000+",
                      "traffic": 2000,
                      "started": "2026-10-01T04:40:00Z",
                      "firstSeenToday": "2026-10-01T04:59:59Z",
                      "snapshotsToday": 1,
                      "alsoTrendingIn": [
                        "ZA"
                      ],
                      "news": [
                        {
                          "title": "Crude oil exports through the Strait of Hormuz hit prewar levels, but fuel shipments remain constrained",
                          "url": "https://www.cnbc.com/2026/09/30/iran-war-strait-hormuz-gulf-oil-fuel.html",
                          "source": "CNBC"
                        },
                        {
                          "title": "Is Iran losing its leverage over the Strait of Hormuz?",
                          "url": "https://www.aljazeera.com/news/2026/9/30/economic-war-is-iran-losing-its-leverage-over-the-strait-of-hormuz",
                          "source": "Al Jazeera"
                        },
                        {
                          "title": "Oil Prices Fall as Gulf Crude Exports Recover",
                          "url": "https://www.wsj.com/business/energy-oil/oil-prices-rise-as-u-s-iran-talks-remain-uncertain-1a33ff00",
                          "source": "WSJ"
                        }
                      ]
                    },
                    {
                      "geo": "GB",
                      "country": "United Kingdom",
                      "rank": 7,
                      "query": "ind vs sl",
                      "approxTraffic": "5000+",
                      "traffic": 5000,
                      "started": "2026-10-01T03:40:00Z",
                      "firstSeenToday": "2026-10-01T04:29:53Z",
                      "snapshotsToday": 3,
                      "alsoTrendingIn": [
                        "AU",
                        "CA",
                        "DE",
                        "NZ"
                      ],
                      "news": [
                        {
                          "title": "India vs Sri Lanka, 2nd Semi-Final, Asian Games 2026 Live Cricket Stream, live scores, ball-by-ball commentary, highlights, videos, news, and more in USA & Canada",
                          "url": "https://www.cricbuzz.com/live-cricket-scores/171060/ind-vs-sl-2nd-semi-final-asian-games-2026",
                          "source": "Cricbuzz"
                        },
                        {
                          "title": "India vs. Sri Lanka live win probability, score, chances of victory for Asian Games 2026 semi-final",
                          "url": "https://sports.yahoo.com/articles/india-vs-sri-lanka-live-034529771.html",
                          "source": "Yahoo Sports"
                        },
                        {
                          "title": "Sri Lanka and Bangladesh advance as rain washes out cricket again",
                          "url": "https://www.reuters.com/sports/cricket/sri-lanka-bangladesh-advance-rain-washes-out-cricket-again-2026-09-29/",
                          "source": "Reuters"
                        }
                      ]
                    }
                  ],
                  "count": 3,
                  "snapshots": {
                    "US": {
                      "asOf": "2026-10-01T04:59:59Z",
                      "ageMinutes": 2
                    },
                    "GB": {
                      "asOf": "2026-10-01T04:59:59Z",
                      "ageMinutes": 2
                    }
                  },
                  "source": "Google Trends \"Trending now\" public RSS feed (trends.google.com/trending/rss), polled about every 15 minutes per country",
                  "limits": {
                    "requestsPerMinutePerIp": 10,
                    "countriesPerCall": 5,
                    "historyDays": 30,
                    "timeoutSeconds": 15
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Free tier used up (50/day per IP) or rate/plan limit reached; the body has an upgrade link.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "Took too long; ask for fewer items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Swellmeter Trending API"
        ],
        "summary": "What is trending right now, per country",
        "description": "The newest trending searches for 1-5 countries (up to 10 each, Google rank order): query, approxTraffic (Google's rounded lower bound, e.g. 2000+) and traffic as a number, started (when Google says the trend began), firstSeenToday and snapshotsToday (from our polling), alsoTrendingIn (other countries where the same search is trending now) and up to 3 news articles. snapshots says how fresh each country is.",
        "operationId": "trendingNowPost",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "geo": {
                    "type": "string"
                  },
                  "limit": {
                    "type": "integer"
                  }
                }
              },
              "example": {
                "geo": "US,DE",
                "limit": 5
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {
                  "results": [
                    {
                      "geo": "US",
                      "country": "United States",
                      "rank": 8,
                      "query": "flash flood warning",
                      "approxTraffic": "500+",
                      "traffic": 500,
                      "started": "2026-10-01T04:00:00Z",
                      "firstSeenToday": "2026-10-01T04:29:53Z",
                      "snapshotsToday": 3,
                      "alsoTrendingIn": [],
                      "news": [
                        {
                          "title": "Conservative Freedom Fest with Kid Rock canceled after only 6 VIP tickets sell",
                          "url": "https://www.usatoday.com/story/entertainment/music/2026/09/22/freedom-fest-cancelled-low-vip-ticket-sales/91894276007/",
                          "source": "USA Today"
                        },
                        {
                          "title": "Eric Deters cancels Freedom Fest amid low VIP ticket sales",
                          "url": "https://www.cincinnati.com/story/news/politics/2026/09/21/eric-deters-cancels-freedom-fest-amid-low-vip-ticket-sales/91871302007/",
                          "source": "Cincinnati Enquirer"
                        },
                        {
                          "title": "Kid Rock MAGAFest Goes Bust, Wendy's Goes Emo and More Top Stories of the Week",
                          "url": "https://metalinjection.net/injection-reflection/kid-rock-magafest-wendys-top-stories-of-the-week",
                          "source": "Metal Injection"
                        }
                      ]
                    },
                    {
                      "geo": "GB",
                      "country": "United Kingdom",
                      "rank": 1,
                      "query": "strait of hormuz",
                      "approxTraffic": "2000+",
                      "traffic": 2000,
                      "started": "2026-10-01T04:40:00Z",
                      "firstSeenToday": "2026-10-01T04:59:59Z",
                      "snapshotsToday": 1,
                      "alsoTrendingIn": [
                        "ZA"
                      ],
                      "news": [
                        {
                          "title": "Crude oil exports through the Strait of Hormuz hit prewar levels, but fuel shipments remain constrained",
                          "url": "https://www.cnbc.com/2026/09/30/iran-war-strait-hormuz-gulf-oil-fuel.html",
                          "source": "CNBC"
                        },
                        {
                          "title": "Is Iran losing its leverage over the Strait of Hormuz?",
                          "url": "https://www.aljazeera.com/news/2026/9/30/economic-war-is-iran-losing-its-leverage-over-the-strait-of-hormuz",
                          "source": "Al Jazeera"
                        },
                        {
                          "title": "Oil Prices Fall as Gulf Crude Exports Recover",
                          "url": "https://www.wsj.com/business/energy-oil/oil-prices-rise-as-u-s-iran-talks-remain-uncertain-1a33ff00",
                          "source": "WSJ"
                        }
                      ]
                    },
                    {
                      "geo": "GB",
                      "country": "United Kingdom",
                      "rank": 7,
                      "query": "ind vs sl",
                      "approxTraffic": "5000+",
                      "traffic": 5000,
                      "started": "2026-10-01T03:40:00Z",
                      "firstSeenToday": "2026-10-01T04:29:53Z",
                      "snapshotsToday": 3,
                      "alsoTrendingIn": [
                        "AU",
                        "CA",
                        "DE",
                        "NZ"
                      ],
                      "news": [
                        {
                          "title": "India vs Sri Lanka, 2nd Semi-Final, Asian Games 2026 Live Cricket Stream, live scores, ball-by-ball commentary, highlights, videos, news, and more in USA & Canada",
                          "url": "https://www.cricbuzz.com/live-cricket-scores/171060/ind-vs-sl-2nd-semi-final-asian-games-2026",
                          "source": "Cricbuzz"
                        },
                        {
                          "title": "India vs. Sri Lanka live win probability, score, chances of victory for Asian Games 2026 semi-final",
                          "url": "https://sports.yahoo.com/articles/india-vs-sri-lanka-live-034529771.html",
                          "source": "Yahoo Sports"
                        },
                        {
                          "title": "Sri Lanka and Bangladesh advance as rain washes out cricket again",
                          "url": "https://www.reuters.com/sports/cricket/sri-lanka-bangladesh-advance-rain-washes-out-cricket-again-2026-09-29/",
                          "source": "Reuters"
                        }
                      ]
                    }
                  ],
                  "count": 3,
                  "snapshots": {
                    "US": {
                      "asOf": "2026-10-01T04:59:59Z",
                      "ageMinutes": 2
                    },
                    "GB": {
                      "asOf": "2026-10-01T04:59:59Z",
                      "ageMinutes": 2
                    }
                  },
                  "source": "Google Trends \"Trending now\" public RSS feed (trends.google.com/trending/rss), polled about every 15 minutes per country",
                  "limits": {
                    "requestsPerMinutePerIp": 10,
                    "countriesPerCall": 5,
                    "historyDays": 30,
                    "timeoutSeconds": 15
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Free tier used up (50/day per IP) or rate/plan limit reached; the body has an upgrade link.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "Took too long; ask for fewer items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/day": {
      "get": {
        "tags": [
          "Swellmeter Trending API"
        ],
        "summary": "Everything that trended in a country on one day (today or the last 30 days)",
        "description": "Every trending search seen that UTC day for 1-5 countries, biggest peak traffic first: query, peakTraffic, approxTraffic, bestRank, firstSeen, lastSeen, started, snapshots and news. Google's feed shows only the newest 10; this is the full day.",
        "operationId": "trendingDayGet",
        "parameters": [
          {
            "name": "geo",
            "in": "query",
            "required": false,
            "description": "ISO-2 country code, or up to 5 separated by commas (US, GB, DE, IN, BR, JP, ...). See /api/countries.",
            "schema": {
              "type": "string"
            },
            "example": "US,GB"
          },
          {
            "name": "date",
            "in": "query",
            "required": false,
            "description": "YYYY-MM-DD (UTC). Default today.",
            "schema": {
              "type": "string"
            },
            "example": ""
          },
          {
            "name": "minTraffic",
            "in": "query",
            "required": false,
            "description": "Only topics whose peak traffic reached this (e.g. 1000)",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max rows, 1-500 (default 100)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Free tier used up (50/day per IP) or rate/plan limit reached; the body has an upgrade link.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "Took too long; ask for fewer items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Swellmeter Trending API"
        ],
        "summary": "Everything that trended in a country on one day (today or the last 30 days)",
        "description": "Every trending search seen that UTC day for 1-5 countries, biggest peak traffic first: query, peakTraffic, approxTraffic, bestRank, firstSeen, lastSeen, started, snapshots and news. Google's feed shows only the newest 10; this is the full day.",
        "operationId": "trendingDayPost",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "geo": {
                    "type": "string"
                  },
                  "date": {
                    "type": "string"
                  },
                  "minTraffic": {
                    "type": "integer"
                  },
                  "limit": {
                    "type": "integer"
                  }
                }
              },
              "example": {
                "geo": "GB",
                "minTraffic": 1000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Free tier used up (50/day per IP) or rate/plan limit reached; the body has an upgrade link.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "Took too long; ask for fewer items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/global": {
      "get": {
        "tags": [
          "Swellmeter Trending API"
        ],
        "summary": "Searches trending in several countries at once",
        "description": "Topics trending right now in 2 or more of the 30 countries, most countries first: query, countryCount, countries, totalTraffic and a news article.",
        "operationId": "crossCountryTrendsGet",
        "parameters": [
          {
            "name": "minCountries",
            "in": "query",
            "required": false,
            "description": "At least this many countries (default 2)",
            "schema": {
              "type": "integer",
              "minimum": 2,
              "default": 2
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-50 (default 20)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Free tier used up (50/day per IP) or rate/plan limit reached; the body has an upgrade link.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "Took too long; ask for fewer items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Swellmeter Trending API"
        ],
        "summary": "Searches trending in several countries at once",
        "description": "Topics trending right now in 2 or more of the 30 countries, most countries first: query, countryCount, countries, totalTraffic and a news article.",
        "operationId": "crossCountryTrendsPost",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "minCountries": {
                    "type": "integer"
                  },
                  "limit": {
                    "type": "integer"
                  }
                }
              },
              "example": {
                "minCountries": 3
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Free tier used up (50/day per IP) or rate/plan limit reached; the body has an upgrade link.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "Took too long; ask for fewer items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/topic": {
      "get": {
        "tags": [
          "Swellmeter Trending API"
        ],
        "summary": "Did a topic trend in the last 30 days? Where and when?",
        "description": "Searches the history for trending searches containing every word of q: for each match, the countries where it trended with firstSeen, lastSeenDay and peakTraffic. Optional geo filter and days window.",
        "operationId": "topicHistoryGet",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Topic words, e.g. iphone or champions league",
            "schema": {
              "type": "string"
            },
            "example": "iphone"
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Look back 1-30 days (default 30)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 30,
              "default": 30
            }
          },
          {
            "name": "geo",
            "in": "query",
            "required": false,
            "description": "Optional ISO-2 countries to keep",
            "schema": {
              "type": "string"
            },
            "example": ""
          }
        ],
        "responses": {
          "200": {
            "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Free tier used up (50/day per IP) or rate/plan limit reached; the body has an upgrade link.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "Took too long; ask for fewer items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Swellmeter Trending API"
        ],
        "summary": "Did a topic trend in the last 30 days? Where and when?",
        "description": "Searches the history for trending searches containing every word of q: for each match, the countries where it trended with firstSeen, lastSeenDay and peakTraffic. Optional geo filter and days window.",
        "operationId": "topicHistoryPost",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "q": {
                    "type": "string"
                  },
                  "days": {
                    "type": "integer"
                  },
                  "geo": {
                    "type": "string"
                  }
                },
                "required": [
                  "q"
                ]
              },
              "example": {
                "q": "champions league",
                "days": 7
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Free tier used up (50/day per IP) or rate/plan limit reached; the body has an upgrade link.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "Took too long; ask for fewer items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/countries": {
      "get": {
        "tags": [
          "Swellmeter Trending API"
        ],
        "summary": "The 30 countries, their last poll time and history start (not metered)",
        "description": "ISO-2 code, country name, the time of the last successful read of each country, and when history begins.",
        "operationId": "countriesGet",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Free tier used up (50/day per IP) or rate/plan limit reached; the body has an upgrade link.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "Took too long; ask for fewer items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Swellmeter Trending API"
        ],
        "summary": "The 30 countries, their last poll time and history start (not metered)",
        "description": "ISO-2 code, country name, the time of the last successful read of each country, and when history begins.",
        "operationId": "countriesPost",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Free tier used up (50/day per IP) or rate/plan limit reached; the body has an upgrade link.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "Took too long; ask for fewer items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "retryAfterSeconds": {
            "type": "integer"
          },
          "limits": {
            "type": "object"
          }
        },
        "required": [
          "error",
          "message"
        ]
      }
    },
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Optional. Paid plan key from https://swellmeter-api.cybermax-tools.workers.dev/docs#pricing; leave out for the free tier."
      },
      "BearerKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Same key as a Bearer token."
      }
    }
  },
  "x-mcp-server": "https://swellmeter-api.cybermax-tools.workers.dev/mcp",
  "externalDocs": {
    "description": "Get an API key (pricing)",
    "url": "https://swellmeter-api.cybermax-tools.workers.dev/docs#pricing"
  },
  "security": [
    {},
    {
      "ApiKeyHeader": []
    },
    {
      "BearerKey": []
    }
  ]
}