Trends & Analytics

Docs

Trends & Analytics

Track trending topics, hashtags, and real-time engagement metrics with location-based trends and comprehensive analytics.

Overview

The Trends & Analytics endpoints provide access to current trending topics, hashtag analytics, location-based trends, and detailed engagement metrics for tweets and users. These endpoints are essential for understanding what's happening on Twitter in real-time and analyzing content performance.

Key Features

Trending Topics: Discover what's trending worldwide or in specific locations
Hashtag Analytics: Get detailed analytics for specific hashtags
Location-Based Trends: Find trends for specific cities, countries, or regions
Tweet Analytics: Detailed engagement metrics for individual tweets
User Analytics: Performance metrics for user accounts
Real-Time Data: Get up-to-the-minute trend information
Historical Analysis: Analyze trends over time periods

Authentication

All endpoints require authentication via the X-API-KEY header:

X-API-KEY: YOUR_API_KEY

For detailed authentication information, see our Authentication Guide.

Understanding WOEID

WOEID (Where On Earth ID) is a unique identifier for geographic locations. It's used to specify locations for trend queries.

Finding WOEIDs

You can find WOEIDs using the /trends/locations endpoint or common values below.

Common WOEIDs

Location	WOEID	Type
Worldwide	1	Global
United States	23424977	Country
United Kingdom	23424975	Country
Germany	23424829	Country
France	23424819	Country
Japan	23424856	Country
Canada	23424775	Country
Australia	23424748	Country
New York	2459115	City
London	44418	City
Berlin	638242	City
Los Angeles	2442047	City
San Francisco	2487956	City
Tokyo	1118370	City
Paris	615702	City

How to Use WOEIDs

// Get trends for New York
const response = await fetch('/trends/topics?woeid=2459115', {
  headers: { 'X-API-KEY': API_KEY }
});
 
// Get trends for Germany
const response = await fetch('/trends/topics?woeid=23424829', {
  headers: { 'X-API-KEY': API_KEY }
});

Endpoints

Retrieves current trending topics for a specific location. This is the most commonly used endpoint for discovering what's trending.

Endpoint: GET /trends/topics

Query Parameters

Name	Type	Required	Description
`woeid`	integer	No	Where On Earth ID (Default: 1 = Worldwide)
`limit`	integer	No	Number of results (Default: 20, Max: 50)

Request Examples

Worldwide Trends:

curl --request GET \
  --url 'https://<direct.gateway>/trends/topics?woeid=1&limit=20' \
  --header 'X-API-KEY: YOUR_API_KEY'

Location-Specific Trends:

# New York trends
curl --request GET \
  --url 'https://<direct.gateway>/trends/topics?woeid=2459115&limit=20' \
  --header 'X-API-KEY: YOUR_API_KEY'

JavaScript:

// Get worldwide trends
const response = await fetch('https://<direct.gateway>/trends/topics?woeid=1&limit=20', {
  headers: { 'X-API-KEY': 'YOUR_API_KEY' }
});
const data = await response.json();
 
// Get trends for specific location
const nyTrends = await fetch('https://<direct.gateway>/trends/topics?woeid=2459115', {
  headers: { 'X-API-KEY': 'YOUR_API_KEY' }
});

Python:

import requests
 
# Worldwide trends
response = requests.get(
    'https://<direct.gateway>/trends/topics',
    params={'woeid': 1, 'limit': 20},
    headers={'X-API-KEY': 'YOUR_API_KEY'}
)
data = response.json()
 
# Location-specific trends
ny_trends = requests.get(
    'https://<direct.gateway>/trends/topics',
    params={'woeid': 2459115},
    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"
    },
    {
      "name": "Breaking News",
      "url": "https://twitter.com/search?q=Breaking%20News",
      "tweet_volume": null,
      "rank": 3,
      "category": "News"
    }
  ],
  "location": {
    "name": "Worldwide",
    "woeid": 1
  },
  "as_of": "2024-10-01T12:00:00.000Z"
}

Response Fields

Field	Type	Description
`name`	string	Trend name/topic
`url`	string	Twitter search URL for the trend
`query`	string	Search query for the trend
`tweet_volume`	integer\|null	Number of tweets (null if not available)
`rank`	integer	Position in trending list (1 = most popular)
`category`	string	Category (Technology, Sports, News, etc.)
`trending_since`	string	When the trend started (ISO 8601)
`promoted_content`	object\|null	Promoted content (if any)

Understanding Tweet Volume

High Volume (100K+): Major trending topic, likely news or viral content
Medium Volume (10K-100K): Popular topic with significant engagement
Low Volume (1K-10K): Emerging trend or niche topic
Null: Volume data not available (still trending but volume unknown)

Common Use Cases

Content Discovery: Find trending topics to create content about
News Monitoring: Track breaking news and events
Market Research: Understand what topics are popular in specific regions
Social Listening: Monitor trends relevant to your brand/industry

Retrieves currently trending hashtags with additional analytics like growth rate and trending score.

Endpoint: GET /trends/hashtags

Query Parameters

Name	Type	Required	Description
`country`	string	No	Country code (ISO 3166-1 alpha-2, e.g., "US", "DE", "GB")
`limit`	integer	No	Number of results (Default: 20, Max: 50)
`category`	string	No	Category filter: `all`, `technology`, `sports`, `entertainment`, `politics`, `business`

Request Examples

# All trending hashtags
curl --request GET \
  --url 'https://<direct.gateway>/trends/hashtags?limit=20' \
  --header 'X-API-KEY: YOUR_API_KEY'
 
# Technology hashtags in US
curl --request GET \
  --url 'https://<direct.gateway>/trends/hashtags?country=US&category=technology&limit=20' \
  --header 'X-API-KEY: YOUR_API_KEY'

JavaScript:

// Get trending hashtags
const response = await fetch('https://<direct.gateway>/trends/hashtags?limit=20', {
  headers: { 'X-API-KEY': 'YOUR_API_KEY' }
});
 
// Get technology hashtags in Germany
const techHashtags = await fetch(
  'https://<direct.gateway>/trends/hashtags?country=DE&category=technology',
  { headers: { 'X-API-KEY': 'YOUR_API_KEY' } }
);

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": {
          "username": "tech_influencer",
          "verified": true
        },
        "metrics": {
          "like_count": 5234,
          "retweet_count": 1523
        }
      }
    }
  ],
  "meta": {
    "country": "US",
    "timestamp": "2024-10-01T12:00:00.000Z"
  }
}

Understanding Analytics Metrics

Growth Rate: Percentage increase in tweet volume

> 50%: Rapidly growing trend
20-50%: Steady growth
< 20%: Slow or stable growth

Trending Score: Overall trending strength (0-10)

9-10: Extremely popular, likely to stay trending
7-8: Very popular, strong trend
5-6: Moderately trending
< 5: Weak trend, may fade soon

Get Hashtag Analytics

Retrieves detailed analytics for a specific hashtag over a time period. This is essential for understanding hashtag performance and engagement.

Endpoint: GET /trends/hashtag/{hashtag}/analytics

Path Parameters

Name	Type	Required	Description
`hashtag`	string	Yes	The hashtag without # symbol (e.g., "AI" not "#AI")

Query Parameters

Name	Type	Required	Description
`timeframe`	string	No	Time period: `1h`, `6h`, `24h`, `7d`, `30d` (Default: 24h)

Request Examples

curl --request GET \
  --url 'https://<direct.gateway>/trends/hashtag/AI/analytics?timeframe=24h' \
  --header 'X-API-KEY: YOUR_API_KEY'

JavaScript:

const response = await fetch(
  'https://<direct.gateway>/trends/hashtag/AI/analytics?timeframe=24h',
  { headers: { 'X-API-KEY': 'YOUR_API_KEY' } }
);
const analytics = await response.json();

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
    }
  ]
}

Interpreting Analytics Data

Total Tweets: Raw volume of tweets using the hashtag

High volume indicates broad awareness
Compare with previous periods to measure growth

Unique Authors: Number of different accounts using the hashtag

High unique authors = diverse participation
Low unique authors = concentrated discussion

Engagement Rate: Percentage of impressions that resulted in engagement

> 5%: Excellent engagement
2-5%: Good engagement
< 2%: Low engagement

Sentiment Analysis: Distribution of positive/neutral/negative sentiment

Use to understand public perception
Track sentiment changes over time

Peak Hour: Time when hashtag activity was highest

Useful for timing content
Understand when audience is most active

Related Hashtags: Hashtags frequently used together

Discover related topics
Find content opportunities

Get Location Trends

Retrieves trends for a specific location using WOEID.

Endpoint: GET /trends/location/{woeid}

Path Parameters

Name	Type	Required	Description
`woeid`	integer	Yes	Where On Earth ID

Request Examples

# Trends in Germany
curl --request GET \
  --url 'https://<direct.gateway>/trends/location/23424829' \
  --header 'X-API-KEY: YOUR_API_KEY'

JavaScript:

const germanyTrends = await fetch(
  'https://<direct.gateway>/trends/location/23424829',
  { headers: { 'X-API-KEY': 'YOUR_API_KEY' } }
);

Response Example

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

Get Available Locations

Retrieves all available locations for trend queries. Use this to discover WOEIDs for locations you want to track.

Endpoint: GET /trends/locations

Request Example

curl --request GET \
  --url 'https://<direct.gateway>/trends/locations' \
  --header 'X-API-KEY: YOUR_API_KEY'

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"
      }
    }
  ]
}

Use Cases

Discover Locations: Find WOEIDs for cities/countries
Build Location Lists: Create lists of locations to monitor
Location Validation: Verify WOEIDs before making requests

Get Tweet Analytics

Retrieves detailed engagement metrics for a specific tweet. Essential for understanding tweet performance.

Endpoint: GET /analytics/tweet/{tweet_id}

Path Parameters

Name	Type	Required	Description
`tweet_id`	string	Yes	The unique tweet ID

Request Example

curl --request GET \
  --url 'https://<direct.gateway>/analytics/tweet/1234567890123456789' \
  --header 'X-API-KEY: YOUR_API_KEY'

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
    }
  ]
}

Understanding Tweet Metrics

Impressions: Total number of times tweet was seen

Includes all views (timeline, profile, search, etc.)

Engagements: Total interactions (likes, retweets, replies, clicks)

Higher engagements = more successful tweet

Engagement Rate: Percentage of impressions that resulted in engagement

> 5%: Excellent performance
2-5%: Good performance
< 2%: Below average

Virality Score: Measure of how viral the tweet is (0-10)

> 8: Highly viral
5-8: Moderately viral
< 5: Low virality

Reach Breakdown:

Organic: Natural reach through timeline
Viral: Reach through retweets/shares

Get User Analytics

Retrieves analytics for a user account over a specific time period. Useful for understanding account performance.

Endpoint: GET /analytics/user/{user_id}

Path Parameters

Name	Type	Required	Description
`user_id`	string	Yes	The unique user ID

Query Parameters

Name	Type	Required	Description
`timeframe`	string	No	Time period: `7d`, `30d`, `90d` (Default: 30d)

Request Example

curl --request GET \
  --url 'https://<direct.gateway>/analytics/user/44196397?timeframe=30d' \
  --header 'X-API-KEY: YOUR_API_KEY'

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
  }
}

Interpreting User Analytics

Tweet Performance:

Total Impressions: Overall reach of content
Average Engagement Rate: Typical performance level
Total Engagements: Overall interaction volume

Growth Metrics:

Net Growth: Followers gained minus lost
Growth Rate: Percentage growth over period
Positive growth = account is growing

Top Tweet: Best performing tweet in period

Use to understand what content resonates
Replicate successful content strategies

Best Practices

Trends-Specific Tips

Monitor multiple locations: Track trends in multiple WOEIDs for comprehensive coverage
Cache trend data: Trends update every 5-15 minutes, cache for 5 minutes
Track hashtag performance: Monitor hashtag analytics over time to identify patterns
Use analytics sparingly: Analytics endpoints are more resource-intensive

For general API best practices including error handling, rate limits, and performance optimization, see our Best Practices Guide.

async function trackHashtag(hashtag, timeframe = '24h') {
  const response = await fetch(
    `/trends/hashtag/${hashtag}/analytics?timeframe=${timeframe}`,
    { headers: { 'X-API-KEY': API_KEY } }
  );
  const analytics = await response.json();
  
  // Store analytics for comparison over time
  await saveAnalytics(hashtag, analytics);
  
  return analytics;
}

4. Analyze Engagement Patterns

Use analytics to understand audience behavior:

function analyzeEngagement(analytics) {
  const insights = {
    bestHour: findPeakHour(analytics.timeline),
    avgEngagement: calculateAverage(analytics.analytics.engagement_rate),
    sentiment: analytics.analytics.sentiment,
    topContributors: analytics.top_contributors.slice(0, 5)
  };
  
  return insights;
}

For comprehensive error handling and rate limits information, see our guides:

Error Handling Guide - Complete error handling reference
Rate Limits Guide - Rate limit details and management

Troubleshooting

Issue	Symptoms	Possible Causes	Solutions
No trends for location	Empty results for valid WOEID	Location has no trending topics, WOEID is incorrect, time of day (some locations have fewer trends at certain times)	Verify WOEID using `/trends/locations`, try different time periods, check if location has active Twitter usage
Inconsistent analytics data	Analytics numbers don't match expected values	Data aggregation delays, different calculation methods, real-time updates	Analytics may have slight delays - use consistent timeframes for comparisons, allow time for data to stabilize

FAQ

How often do trends update?

Trends update approximately every 5-15 minutes. For real-time monitoring, poll every 5 minutes.

Can I get historical trends?

The API provides current trends. For historical data, you would need to track trends over time yourself.

Trending Topics: Can include keywords, phrases, or hashtags
Trending Hashtags: Only hashtags, with additional analytics

How accurate is sentiment analysis?

Sentiment analysis uses machine learning and may have accuracy limitations. Use as a general indicator, not absolute truth.

Can I track trends for multiple locations simultaneously?

Yes, make parallel requests for different WOEIDs. Be mindful of rate limits.

How do I interpret engagement rates?

Engagement rates vary by account size and content type. Compare with your historical averages for context.

Search Endpoints - Search for tweets and hashtags
Tweets Endpoints - Get tweet details
Users Endpoints - Get user information
Error Handling Guide - Error handling
Rate Limits Guide - Rate limits
Best Practices - API best practices

Search Spaces & Audio

Overview

Key Features

Authentication

Understanding WOEID

Finding WOEIDs

Common WOEIDs

How to Use WOEIDs

Endpoints

Get Trending Topics

Query Parameters

Request Examples

Response Example

Response Fields

Understanding Tweet Volume

Common Use Cases

Get Trending Hashtags

Query Parameters

Request Examples

Response Example

Understanding Analytics Metrics

Get Hashtag Analytics

Path Parameters

Query Parameters

Request Examples

Response Example

Interpreting Analytics Data

Get Location Trends

Path Parameters

Request Examples

Response Example

Get Available Locations

Request Example

Response Example

Use Cases

Get Tweet Analytics

Path Parameters

Request Example

Response Example

Understanding Tweet Metrics

Get User Analytics

Path Parameters

Query Parameters

Request Example

Response Example

Interpreting User Analytics

Best Practices

Trends-Specific Tips

4. Analyze Engagement Patterns

Troubleshooting

FAQ

How often do trends update?

Can I get historical trends?

What's the difference between trending topics and trending hashtags?

How accurate is sentiment analysis?

Can I track trends for multiple locations simultaneously?

How do I interpret engagement rates?

Related Documentation