Tweets' API endpoints
Use this API to get tweets and stats for hashtags, keywords, users and lists.
It queues a Twitter query in our system to be processed. The request returns a resourceId that is stored in the Postman environment as reportId and a short version of it as reportCode. These variables are later used by the endpoints. Internally, this creates a report document as well.
{
“query”: {
“or”: [“pamplona”, “obanos”],
“limit”: 100
}
}
That query would search for publications that contain the word “pamplona” or the word “obanos” limiting the resultset to a hundred publications (starting now towards the past). That limit can be increased.
When creating a search, you will get as "tweets" original tweets and retweets.
These parameters are very important when creating queries that retrieve tweets and stats:
- must: string array; All terms must be present. It’s equivalent to a logic AND
- or: string array; At least one of the terms must be present.
- nor: string array; None of the terms must be present.
- limit: integer; limits the number of publications below the theoretical maximum. It’s quite useful for testing.
- lang: string; Publications language.
- startDate: unix time; Date at which the search will stop as long as the limit (either manual or by default) hasn’t been reached.
- endDate: unix time; Date from which the search will dismiss publications.
NOTE: At least one of the following parameters must be present in the payload: must or or. The rest are optional.
It is possible to search only for original content (original tweets), that means dismissing retweets. In order to get that just add the term “-RT” to one of must or or nor fields.
It is possible to search for tweets emitted from a given account using from:@accountAlias. So for example, to get the tweets by @ElonMusk you will have to write: from:@elonmusk -RT, being the query:
{
"must": [
"from:elonmusk"
"-RT"
]
}
Queries can contain Twitter's advanced search commands (aka operators) in order to further refine the results. Some of these have been mentioned before in this page, but let's review the most important of them all here:
- Tweet containing several keywords: (all the words MUST be in the tweets){"must": ["Navarra","Tafalla","Pamplona"]}
- Some exact phrase{"must": ["Tweet Binder is the best tool in the world"]}
- Tweets containing several alternative keywords: tweets must contain at least ONE of them{"must": ["Navarra","OR","Tafalla","OR","Pamplona"]}
- Tweets containing a keyword and excluding some keywords{"must": ["Tweet","Binder","-Google","-Facebook","-SalesForce"]}
- Tweets from a keyword filtered by date/hour: you can use since:YEAR/MONTH/DAY and until:YEAR/MONTH/DAY or you can use UNIX TIME:{"must": ["Obanos","since:2023-03-01","until:2023-03-10"]}
- Tweets sent by one user:{"must": ["from:tweetbinder"]}
- Tweets sent by one user mentioning one keyword/user in a date range (combining several or the previous operators){"must": ["from:elonmusk","tweetbinder","since:2022-12-01"]}
- Tweets with a minimum number of retweets or likes: Retweets:{"must": ["Detroit","min_retweets:100"]}Likes:{"must": ["Detroit","min_faves:100"]}
- Tweets in one language:{"must": ["Tweet","Binder","lang:en"]}
- Tweets send only by verified accounts:{"must": ["Tweet","Binder","filter:verified"]}
- Filter tweets by type: media (pics, videos, etc), link, reply Links:{"must": ["boston","filter:links"]}Replies:{"must": ["boston","filter:replies"]}Images:{"must": ["Boston","filter:media"]}
- Tweets containing a particular and exact link:{"must": ["https://www.bostonglobe.com/2023/03/09/metro/active-shooter-drill-merrimack-college-aims-prepare-emergency-responders-act-quickly/?camp=bg%3Abrief%3Arss%3Afeedly&rss_id=feedly_rss_brief&s_campaign=bostonglobe%3Asocialflow%3Atwitter"]}
- Tweets sent by a Twitter list{"must": ["list:1492601169428025349"]}
These operators can be combined to create a more refined search.
This one returns a search document (AKA report) within our platform. The two most interesting fields might be:
- status: string; Most relevant values
- waiting : the search hasn’t finished yet
- generated: the search has finished and stats have been generated
- outdated: some new publications are pending for processing, this will only happen with streams (live reports).
- total: integer; Total number of publications processed so far. In general if the status is generated this will be the total number of publications.
This endpoint returns statistics about the publications. If the status is waiting it will return an error.
Tweet Binder provides numerous statistics for each search, here some of them:
- Total number of tweets (retweets included)
- Types of tweets
- Potential Impressions
- Potential Reach
- Likes / Retweets
- 12 User rankings: active, engager, etc.
- Sentiment
- Economic study
- Engagement
- Users' age on Twitter
- Lenght of the tweets
- Top languages
- Top sources
- Top hashtags
- Rankings of images by:
- Retweets
- Likes
- Ranking of tweets by:
- Retweets
- Likes
It deletes a report document.
It returns a list of report documents.
Base query, by default returns the latest 20 report publications (tweets) in descending order.
This is just an example that shows how to apply filters, in this case it should return the latest (newest) retweet. If there are no retweets data will be empty.
It exports to a json which will contain all the tweets in report. Steps are:
- 1.Export report: Pass report id to request report json export
- 2.Await until report has jsonGeneratedAt>generatedAt: Request report status until json is generated. It may take from some minutes to several hours depending on report size
- 3.Get report json url: After report is generated use this request to get URL to download JSON file
Last modified 17d ago