TwittrAPI LogoTwittrAPI
Docs
Trends & Analytics

Trends & Analytics

Track trending topics, hashtags, and real-time engagement metrics.

Overview

The Trends endpoints provide access to current trending topics, hashtag analytics, and real-time engagement metrics.

Endpoints

Get Trending Topics

Retrieves current trending topics.

GET /trends/topics

Parameters

NameTypeRequiredDescription
woeidintegerNoWhere On Earth ID (Default: 1 = Worldwide)
limitintegerNoNumber of results (Default: 20, Max: 50)

Headers

X-API-KEY: <YOUR_API_KEY>

Response Example

{
  "data": [
    {
      "name": "#AI",
      "url": "https://twitter.com/search?q=%23AI",
      "promoted_content": null,
      "query": "#AI",
      "tweet_volume": 156420,
      "rank": 1,
      "category": "Technology",
      "trending_since": "2024-10-01T10:00:00.000Z"
    },
    {
      "name": "World Cup",
      "url": "https://twitter.com/search?q=World%20Cup",
      "tweet_volume": 523000,
      "rank": 2,
      "category": "Sports"
    }
  ],
  "location": {
    "name": "Worldwide",
    "woeid": 1
  },
  "as_of": "2024-10-01T12:00:00.000Z"
}

Get Trending Hashtags

Retrieves currently trending hashtags.

GET /trends/hashtags

Parameters

NameTypeRequiredDescription
countrystringNoCountry Code (ISO 3166-1 alpha-2, e.g. "US", "DE")
limitintegerNoNumber of results (Default: 20, Max: 50)
categorystringNoCategory: all, technology, sports, entertainment, politics

Response Example

{
  "data": [
    {
      "hashtag": "AI",
      "tweet_count_24h": 156420,
      "growth_rate": 45.2,
      "trending_score": 9.3,
      "related_hashtags": ["MachineLearning", "Tech", "Innovation"],
      "top_tweet": {
        "id": "1234567890123456789",
        "text": "Example tweet with #AI",
        "author": {...},
        "metrics": {
          "like_count": 5234,
          "retweet_count": 1523
        }
      }
    }
  ],
  "meta": {
    "country": "US",
    "timestamp": "2024-10-01T12:00:00.000Z"
  }
}

Get Hashtag Analytics

Retrieves detailed analytics for a specific hashtag.

GET /trends/hashtag/{hashtag}/analytics

Parameters

NameTypeRequiredDescription
hashtagstringYesThe hashtag (without #)
timeframestringNo1h, 6h, 24h, 7d, 30d (Default: 24h)

Response Example

{
  "hashtag": "AI",
  "analytics": {
    "total_tweets": 156420,
    "unique_authors": 42350,
    "total_impressions": 15642000,
    "engagement_rate": 4.2,
    "sentiment": {
      "positive": 65.3,
      "neutral": 28.1,
      "negative": 6.6
    },
    "peak_hour": "2024-10-01T14:00:00.000Z",
    "peak_volume": 12450
  },
  "timeline": [
    {
      "timestamp": "2024-10-01T00:00:00.000Z",
      "tweet_count": 4521,
      "engagement": 18942
    },
    {
      "timestamp": "2024-10-01T01:00:00.000Z",
      "tweet_count": 3892,
      "engagement": 15234
    }
  ],
  "top_contributors": [
    {
      "username": "tech_influencer",
      "tweet_count": 15,
      "total_engagement": 52340
    }
  ],
  "related_hashtags": [
    {
      "hashtag": "MachineLearning",
      "correlation": 0.78,
      "co_occurrence": 8542
    }
  ]
}

Get Location Trends

Retrieves trends for a specific location.

GET /trends/location/{woeid}

Parameters

NameTypeRequiredDescription
woeidintegerYesWhere On Earth ID

Common WOEIDs

LocationWOEID
Worldwide1
USA23424977
UK23424975
Germany23424829
Japan23424856
New York2459115
London44418
Berlin638242

Response Example

{
  "location": {
    "name": "Germany",
    "woeid": 23424829,
    "country": "Germany",
    "country_code": "DE"
  },
  "trends": [
    {
      "name": "#Bundesliga",
      "tweet_volume": 45230,
      "rank": 1
    }
  ],
  "as_of": "2024-10-01T12:00:00.000Z"
}

Get Available Locations

Retrieves all available trend locations.

GET /trends/locations

Response Example

{
  "data": [
    {
      "name": "Worldwide",
      "woeid": 1,
      "country": "",
      "country_code": null,
      "placeType": {
        "code": 19,
        "name": "Supername"
      }
    },
    {
      "name": "Berlin",
      "woeid": 638242,
      "country": "Germany",
      "country_code": "DE",
      "placeType": {
        "code": 7,
        "name": "Town"
      }
    }
  ]
}

Get Tweet Analytics

Retrieves detailed engagement metrics for a tweet.

GET /analytics/tweet/{tweet_id}

Response Example

{
  "tweet_id": "1234567890123456789",
  "metrics": {
    "impressions": 52340,
    "engagements": 2156,
    "engagement_rate": 4.12,
    "detail_expands": 342,
    "profile_clicks": 87,
    "url_clicks": 156,
    "hashtag_clicks": 45,
    "media_views": 12340,
    "media_engagements": 523
  },
  "virality_score": 7.8,
  "reach": {
    "organic": 42340,
    "viral": 10000
  },
  "timeline": [
    {
      "hour": 0,
      "impressions": 1234,
      "engagements": 52
    }
  ]
}

Get User Analytics

Retrieves analytics for a user over a specific time period.

GET /analytics/user/{user_id}

Parameters

NameTypeRequiredDescription
user_idstringYesThe user ID
timeframestringNo7d, 30d, 90d (Default: 30d)

Response Example

{
  "user_id": "987654321",
  "period": {
    "start": "2024-09-01T00:00:00.000Z",
    "end": "2024-10-01T00:00:00.000Z"
  },
  "tweets": {
    "total": 156,
    "average_per_day": 5.2,
    "total_impressions": 524000,
    "total_engagements": 15420,
    "avg_engagement_rate": 2.94
  },
  "growth": {
    "followers_gained": 1250,
    "followers_lost": 87,
    "net_growth": 1163,
    "growth_rate": 8.2
  },
  "top_tweet": {
    "id": "1234567890123456789",
    "text": "...",
    "impressions": 52340,
    "engagements": 2156
  }
}

Rate Limits

  • Basic Plan: 50 Requests/hour
  • Pro Plan: 500 Requests/hour
  • Enterprise Plan: 5,000 Requests/hour

Error Codes

CodeDescription
400Bad Request - Invalid parameters
401Unauthorized - Missing or invalid API Key
404Not Found - Resource not found
429Too Many Requests - Rate limit exceeded
500Internal Server Error
SearchCommunities