Filter realtime Tweets

Overview contents
  • PowerTrack API
  • statuses/filter

    • Enterprise

    PowerTrack API

    This is an enterprise API available within our managed access levels only. To use this API, you must first set up an account with our enterprise sales team. Learn more

    The PowerTrack API provides customers with the ability to filter the full Twitter firehose, and only receive the data that they or their customers are interested in. This is accomplished by applying the PowerTrack filtering language - see Rules and filtering - to match Tweets based on a wide variety of attributes, including user attributes, geo-location, language, and many others. Using PowerTrack rules to filter Tweet ensures that customers receive all of the data, and only the data they need for your app.

    Core components

    The PowerTrack API consists of two endpoints:

    Rules endpoint

    A separate endpoint managed independently by your application, the rules endpoint supports GET, POST, POST _method=delete and rule validation methods with basic authentication for managing your ruleset. It can support thousands of rules that allow you to filter the realtime stream of data for the topics and conversations that you care about. The rules endpoint can be accessed, managed, and will persist regardless of your connection status to the stream - you can also update (add/remove) rules while connected to the stream and the changes will take effect almost immediately.

    Stream endpoint

    Connecting to the streaming endpoint consists of a simple GET request using basic authentication. Once a connection is established, data is delivered in JSON format (see sample payload below) through a persistent HTTP Streaming connection. You will only receive data matching your rules while connected to the stream.

    Rule tags

    A single PowerTrack stream can support thousands of rules, so being able to discern which rule(s) matched a given Tweet becomes important. This is easily solved by using rule tags. Upon rule creation, you can assign a tag value which will be returned in the matching_rules object (see here) of the response payload.

    Rule tags can represent an end customer use case, a topic or conversation, or another helpful identifier that you can use to route incoming Tweets accordingly.

    If, in addition to realtime data, your product also requires instant access to recent data, we recommend using our Search API.

    Available operators

    The PowerTrack API currently supports the following operators:

    • keyword
    • emoji
    • "exact phrase match"
    • "keyword1 keyword2"~N
    • contains:
    • from:
    • to:
    • url:
    • url_title:
    • url_description:
    • url_contains:
    • has:links
    • sample:
    • #
    • point_radius:[lon lat radius]
    • bounding_box:[west_long south_lat east_long north_lat]
    • @
    • $
    • bio:
    • bio_name:
    • retweets_of:
    • lang:
    • bio_location:
    • statuses_count:
    • followers_count:
    • friends_count:
    • listed_count:
    • is:verified
    • source:
    • place:
    • place_country:
    • has:geo
    • has:mentions
    • has:hashtags
    • has:images
    • has:videos
    • has:media
    • has:symbols
    • is:retweet
    • is:quote
    • retweets_of_status_id:
    • in_reply_to_status_id:
    • has:profile_geo
    • profile_point_radius:[long lat radius]
    • profile_bounding_box:[west_long south_lat east_long north_lat]
    • profile_country:
    • profile_region:
    • profile_locality:
    • profile_subregion:

    For more details, please see the Getting started with premium operators guide.

    Sample payload

    Below is a sample payload from the PowerTrack API:

      {
  "created_at": "Fri Apr 01 20:20:07 +0000 2016",
  "id": 715997192373288962,
  "id_str": "715997192373288962",
  "text": "It's Friday!! \ud83d\udc79 #AprilFools - funny pranks https:\/\/t.co\/b9ZdzRxzFK",
  "source": "\u003ca href=\"http:\/\/twitter.com\" rel=\"nofollow\"\u003eTwitter Web Client\u003c\/a\u003e",
  "truncated": false,
  "in_reply_to_status_id": null,
  "in_reply_to_status_id_str": null,
  "in_reply_to_user_id": null,
  "in_reply_to_user_id_str": null,
  "in_reply_to_screen_name": null,
  "user": {
    "id": 3001969357,
    "id_str": "3001969357",
    "name": "Jordan Brinks",
    "screen_name": "furiouscamper",
    "location": "Birmingham",
    "url": "http:\/\/indigofiddle.com",
    "description": "Alter Ego - Twitter PE",
    "derived": {
      "locations": [
        {
          "country": "United States",
          "country_code": "US",
          "locality": "Birmingham",
          "region": "Alabama",
          "full_name": "Birmingham, Alabama, United States",
          "geo": {
            "coordinates": [
              -86.80249,
              33.52066
            ],
            "type": "point"
          }
        }
      ]
    },
    "protected": false,
    "verified": false,
    "followers_count": 15,
    "friends_count": 24,
    "listed_count": 1,
    "favourites_count": 14,
    "statuses_count": 221,
    "created_at": "Thu Jan 29 18:27:49 +0000 2015",
    "utc_offset": null,
    "time_zone": "null",
    "geo_enabled": true,
    "lang": "en",
    "contributors_enabled": false,
    "is_translator": false,
    "profile_background_color": "000000",
    "profile_background_image_url": "http:\/\/abs.twimg.com\/images\/themes\/theme1\/bg.png",
    "profile_background_image_url_https": "https:\/\/abs.twimg.com\/images\/themes\/theme1\/bg.png",
    "profile_background_tile": false,
    "profile_link_color": "FF691F",
    "profile_sidebar_border_color": "000000",
    "profile_sidebar_fill_color": "000000",
    "profile_text_color": "000000",
    "profile_use_background_image": false,
    "profile_image_url": "http:\/\/pbs.twimg.com\/profile_images\/601155672395227136\/qakfE9EU_normal.jpg",
    "profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/601155672395227136\/qakfE9EU_normal.jpg",
    "profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/3001969357\/1432161817",
    "default_profile": false,
    "default_profile_image": false,
    "following": null,
    "follow_request_sent": null,
    "notifications": null
  },
  "geo": null,
  "coordinates": null,
  "place": {
    "id": "fd70c22040963ac7",
    "url": "https:\/\/api.twitter.com\/1.1\/geo\/id\/fd70c22040963ac7.json",
    "place_type": "city",
    "name": "Boulder",
    "full_name": "Boulder, CO",
    "country_code": "US",
    "country": "United States",
    "bounding_box": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -105.301776,
            39.953552
          ],
          [
            -105.301776,
            40.094411
          ],
          [
            -105.183597,
            40.094411
          ],
          [
            -105.183597,
            39.953552
          ]
        ]
      ]
    },
    "attributes": {
      
    }
  },
  "contributors": null,
  "is_quote_status": false,
  "retweet_count": 0,
  "favorite_count": 0,
  "entities": {
    "hashtags": [
      {
        "text": "AprilFools",
        "indices": [
          16,
          27
        ]
      }
    ],
    "urls": [
      {
        "url": "https:\/\/t.co\/b9ZdzRxzFK",
        "expanded_url": "http:\/\/www.today.com\/parents\/joke-s-you-kid-11-family-friendly-april-fools-pranks-t83276",
        "display_url": "today.com\/parents\/joke-s\u2026",
        "unwound": {
          "url": "http:\/\/www.today.com\/parents\/joke-s-you-kid-11-family-friendly-april-fools-pranks-t83276",
          "status": 200,
          "title": "The joke's on you, kid: 11 family-friendly April Fools pranks",
          "description": "If your kids are practical jokers, turn this April Fools' Day into a family affair."
        },
        "indices": [
          43,
          66
        ]
      }
    ],
    "user_mentions": [
      
    ],
    "symbols": [
      
    ]
  },
  "favorited": false,
  "retweeted": false,
  "possibly_sensitive": false,
  "filter_level": "low",
  "lang": "en",
  "timestamp_ms": "1459542007903",
  "matching_rules": [
    {
      "tag": null,
      "id": 715947673707089920
    }
  ]
}