Today we released updates to core Tweets, Users & search endpoints currently in Labs. We would love to hear your thoughts and feedback on these changes through our Labs feedback forum. Some of these updates are based on feedback we’ve already received, so thank you for your help!
All updates are listed below, however one of the larger themes of this release is based on the request and response format. To make things easier to use and more familiar to developers, we updated the API to return specific data objects based on request parameters – similar to other industry APIs. The new versions of endpoints and changes are documented here, and they are available to test now at the /labs/2/ routes below. Check out our Postman collection to get started!
In order to easily switch to the new version, we’ve put together a migration guide highlighting the updates, and we’ve listed all new release features in our changelog.
Both the previous version /labs/1/ and the new version /labs/2/ will exist simultaneously and Labs v1 endpoints will be supported for 90 days after this initial release. Previous version documentation is still available here. You can provide us feedback on these updates and our versioning strategy via our feedback channel.
This is an atypical version bump for us since Metrics, Filtered Stream, and Sampled Stream aren’t included. We will be bringing these other Labs endpoints to v2 soon after this initial release.
Here is a short summary of what has changed:
New fields parameter: We’re introducing the fields parameter in requests to specify response data, which gives developers the ability to request only the data needed. By default, the id and text fields of a Tweet object, and the id, name, and username fields of a User object will be included in the response data. Example fields parameters for Tweets include created_at, lang, expansions, all available fields in our documentation.
Removing format parameter: With the update for fields, the developer is in control of the format of the response data and what should or shouldn’t be included. In parallel with the fields launch, we’re also removing the format parameter formerly format=(compact,default,detailed). The same result is still possible, but with additional granularity, using fields parameters, more on this comparison in our migration guide.
Updating source object: We’re cleaning up source in the Tweet object to remove HTML tags and improve the ability to parse this field. An example of how this is changing is below:
Before:
"source":"\u003ca href=\"https:\/\/mobile.twitter.com\" rel=\"nofollow\"\u003eTwitter Web App\u003c\/a\u003e"
After:
"source":"Twitter Web App"
Renaming stats object and field parameter: Updating stats object name to public_metrics within the Tweet object to match the request field parameter name.
Within the Tweet object, the public_metrics object includes publicly available Tweet metrics for the specified Tweet, example shown below:
"public_metrics": {
"retweet_count": 20,
"reply_count": 5,
"like_count": 71,
"quote_count": 3
}
Within the User object, the public_metrics object includes publicly available Users metrics for the specified User, example shown below:
"public_metrics": {
"followers_count": 593,
"following_count": 496,
"tweet_count": 1038,
"listed_count": 4
}
Note: the /metrics endpoint allows developers to retrieve additional private Tweet metrics for their authorized user’s Tweets.
In previous versions of the Twitter API, the definition of a response format was required in order to get data returned in a few limited ways. Instead of defining format=(compat,default,detailed) the API is reconfigured to by default return the simplest version of data. Additional fields can now be requested through the fields parameter.
Example request for Recent Search
Default request:
Request:
https://api.twitter.com/labs/2/tweets/search?query=from:twitterdev&max_results=10
Response (default):
Summary
{
"data": [
{
"id": "1226967976454316033",
"text": "Our global community of developers help drive the Twitter platform.\n\n🌍 🌏 🌎 https://t.co/WigZfR85FS"
},
{
"id": "1225917697675886593",
"text": "@TwitterEng *ahem* https://t.co/aroJHt2zQ1"
},
{
"id": "1225914265946730497",
"text": "RT @usman4all: Join us tomorrow for #TapIntoTwitterLafia Q1 Meetup of the year tomorrow. #TapIntoTwitter\nCc: @TwitterDev @compston @lvhcolo…"
},
{
"id": "1225470895902412800",
"text": "RT @AureliaSpecker: 📣 If you enjoyed the London commute tutorial I wrote in November last year, check out the refactored version that uses…"
},
{
"id": "1225458878277705728",
"text": "Twitter libraries are a great way to use our API. Did you know:\n\n✨ 100+ libraries support the Twitter API\n✨ In 25+ programming languages 🐍☕️♦️ \n\nExplore our curated list of community built libraries 📚\n\nhttps://t.co/mgXiWmt9SY"
}
],
"meta": {
"newest_id": "1226967976454316033",
"oldest_id": "1225458878277705728",
"result_count": 5
}
}
Request specifying more field parameters for specific metadata
Request:
https://api.twitter.com/labs/2/tweets/search?tweet.fields=created_at,lang,public_metrics,source&query=from:twitterdev&max_results=10
Response:
{
"data": [
{
"created_at": "2020-02-10T20:35:36.000Z",
"id": "1226967976454316033",
"lang": "en",
"public_metrics": {
"retweet_count": 1,
"reply_count": 0,
"like_count": 20,
"quote_count": 3
},
"source": "Twitter Web App",
"text": "Our global community of developers help drive the Twitter platform.\n\n🌍 🌏 🌎 https://t.co/WigZfR85FS"
},
{
"created_at": "2020-02-07T23:02:10.000Z",
"id": "1225917697675886593",
"lang": "en",
"public_metrics": {
"retweet_count": 81,
"reply_count": 10,
"like_count": 501,
"quote_count": 4
},
"source": "Twitter Web App",
"text": "@TwitterEng *ahem* https://t.co/aroJHt2zQ1"
},
{
"created_at": "2020-02-07T22:48:32.000Z",
"id": "1225914265946730497",
"lang": "en",
"public_metrics": {
"retweet_count": 7,
"reply_count": 0,
"like_count": 0,
"quote_count": 0
},
"source": "Twitter Web App",
"text": "RT @usman4all: Join us tomorrow for #TapIntoTwitterLafia Q1 Meetup of the year tomorrow. #TapIntoTwitter\nCc: @TwitterDev @compston @lvhcolo…"
},
{
"created_at": "2020-02-06T17:26:44.000Z",
"id": "1225470895902412800",
"lang": "en",
"public_metrics": {
"retweet_count": 11,
"reply_count": 0,
"like_count": 0,
"quote_count": 0
},
"source": "Twitter for iPhone",
"text": "RT @AureliaSpecker: 📣 If you enjoyed the London commute tutorial I wrote in November last year, check out the refactored version that uses…"
},
{
"created_at": "2020-02-06T16:38:59.000Z",
"id": "1225458878277705728",
"lang": "en",
"public_metrics": {
"retweet_count": 20,
"reply_count": 5,
"like_count": 71,
"quote_count": 3
},
"source": "Twitter Web App",
"text": "Twitter libraries are a great way to use our API. Did you know:\n\n✨ 100+ libraries support the Twitter API\n✨ In 25+ programming languages 🐍☕️♦️ \n\nExplore our curated list of community built libraries 📚\n\nhttps://t.co/mgXiWmt9SY"
}
],
"meta": {
"newest_id": "1226967976454316033",
"oldest_id": "1225458878277705728",
"result_count": 5
}
}
Note: The core search, pagination and other functionality of Recent Search will stay the same.
Example request for Users
Request:
You have two options here:
https://api.twitter.com/labs/2/users/by/username/twitterdev
OR
https://api.twitter.com/labs/2/users/by?usernames=twitterdev
Response (default):
{
"data": [
{
"id": "2244994945",
"name": "Twitter Dev",
"username": "TwitterDev"
}
]
}
Request specifying more field parameters for specific metadata, this time for two users.
Request:
https://api.twitter.com/labs/2/users/by?usernames=twitterdev,twitterapi&user.fields=created_at,location,description,pinned_tweet_id
Response:
{
"data": [
{
"created_at": "2013-12-14T04:35:55.000Z",
"description": "The voice of Twitter's #DevRel team, and your official source for updates, news, & events about Twitter's API.\n\nNeed help? Visit https://t.co/DVDf7qKyS9",
"id": "2244994945",
"location": "127.0.0.1",
"name": "Twitter Dev",
"pinned_tweet_id": "1214281000932593667",
"username": "TwitterDev"
},
{
"created_at": "2007-05-23T06:01:13.000Z",
"description": "The Real Twitter API. Tweets about API changes, service issues and our Developer Platform. Don't get an answer? It's on my website.",
"id": "6253282",
"location": "San Francisco, CA",
"name": "Twitter API",
"username": "TwitterAPI"
}
]
}
Removing the most_recent_tweet_id expansion in Users: While we heard from some developers that this feature was valuable (e.g. to identify the language used in recent Tweets), it wasn’t scalable to support across the entire set of Tweet retrieval products. We’re considering other ways to solve the problem in the future. Note that pinned_tweet_id is still available.
Other notable updates include:
-
Adjusting the path and query parameters for single and multi-username lookup with the GET /users endpoint. More details in the migration guide.
-
New functionality with v2 can be accessed now for all developers already enrolled Labs by using the /labs/2/ paths for Tweets, Users and Recent Search. Other Labs endpoints (Filter, Stream) will be included with Labs v2 soon.
We are continuing to welcome any feedback on the endpoints and functionality we are building in Labs through our feedback forum.
Regards,
The Twitter Developer team