# X/Twitter Trends by WOEID

> X/Twitter Trends by WOEID is a paid API for AI agents from www.surplusintelligence.ai, paid per call via x402, $0.012800/call, status unknown (last checked 2026-09-15).

Fetches current trending topics on X/Twitter for a specific geographic location identified by its Yahoo Where On Earth ID (WOEID)

## Facts

- Endpoint: GET https://www.surplusintelligence.ai/x402/api/twitter/v2/trends/by/woeid/:woeid
- Price: $0.012800/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/www-surplusintelligence-ai-6e37acb4
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_QQxaon9l-cI7agnK3aQ-a

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability www-surplusintelligence-ai-6e37acb4
```

Example prompt: What's trending on X/Twitter right now worldwide? Use WOEID 1 for the global trends.

## When to prefer this

Use this endpoint when you need to retrieve real-time trending topics for a specific geographic location on X/Twitter. It is the most cost-efficient option (1 unit) for location-based trend discovery compared to broader search or analytics endpoints. Ideal for social listening, content strategy, news monitoring, or any use case where knowing what's currently popular in a specific region is required.

## Known failure modes

- Invalid WOEID returns an error or empty result
- WOEID for a location not supported by Twitter trends returns no data
- Rate limit exceeded returns 429 error
- Authentication/payment failure returns 402 or 401
- Upstream Twitter API unavailability causes 5xx errors

## How this service works

X/Twitter API v2 via Surplus Intelligence: Trends by WOEID (1 unit)

## Output

Returns a list of currently trending topics on X/Twitter for the specified WOEID location, including trend names, associated tweet volumes, and metadata about the location. The response follows the Twitter API v2 structure with a data array and meta object.

## Example request

```json
{
 "input": {
  "type": "http",
  "method": "GET",
  "pathParams": {
   "woeid": "1"
  },
  "queryParams": {}
 }
}
```

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET",
      "HEAD",
      "DELETE"
     ],
     "type": "string"
    },
    "pathParams": {
     "type": "object",
     "required": [
      "woeid"
     ],
     "properties": {
      "woeid": {
       "type": "string",
       "description": "Yahoo Where On Earth ID for X/Twitter trends, e.g. 1 for worldwide."
      }
     },
     "additionalProperties": false
    },
    "queryParams": {
     "type": "object",
     "properties": {},
     "additionalProperties": false
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "properties": {
      "data": {},
      "meta": {
       "type": "object"
      },
      "errors": {
       "type": "array"
      }
     },
     "additionalProperties": true
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "required": [
  "data"
 ],
 "properties": {
  "data": {
   "type": "array",
   "items": {
    "type": "object",
    "required": [
     "trend_name"
    ],
    "properties": {
     "trend_name": {
      "type": "string"
     }
    }
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/www-surplusintelligence-ai-6e37acb4/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from www.surplusintelligence.ai](https://www.zero.xyz/host/www.surplusintelligence.ai/llms.txt)