Have you ever needed to quickly try out a query against the Twitter API? Well then... meet twurl.
twurl. It’s an Open Source, command-line tool (written in Ruby) that enables you to quickly poke the Twitter API for data, and try out query syntax. I use it daily to verify bug reports, to help to validate test cases submitted via our developer forums, or help to answer questions posted on the
Why is it called “twurl”? Simple - it’s a bit like curl, for the Twitter API! 🤓
twurl, you can test individual endpoints and queries, and check for responses. Since it is a command-line tool, you can chain it with a handy JSON utilities like jq. jq lets you quickly format JSON documents and API responses in a pretty manner, and query or reformat them. Oh, and of course, it is really handy for scripting 📄 You can find more information on the website, including a lot of examples of how to use it effectively.
- One thing to note here is that because jq has some issues with large integers, it will mangle the numeric long integer IDs inside Tweet objects, so you should always use the
The first thing you’ll need is a working Ruby interpreter installed. On my own Mac, I'm using recent Ruby installed via rvm (which I've historically preferred to rbenv, but I recognise both are useful version and install managers); on Linux installs, there's a good chance that Ruby is pre-installed, but if not, your package manager can probably help you; on Windows, you are likely to be able use RubyInstaller.
The other thing you will need to do is to register for a Twitter Developer Account, and then create a Twitter app in your dashboard to get going. Once you've done that, you will need to get your Consumer API Key and API Secret from the Details->Keys and tokens tab for the app. There's no need to generate Access Key and Secret on the dashboard, as you will be authorizing your app in the following steps.
$ gem install twurl
twurl gem is installed, you should find that running the
twurl command line presents the help information (confirm via
Good! we're making a start. Now let's authorize to Twitter. You can use
twurl -T to invoke the tutorial,
twurl -h for a list of options, or you can go ahead with the full
twurl authorize syntax and provide your Consumer API Key and API Secret.
Once authorized, here are a few simple commands you can try out.
Get @jack's first Tweet:
$ twurl "/1.1/statuses/show/20.json"
Get @twitterdev's user profile:
$ twurl "/1.1/users/show.json?screen_name=twitterdev"
- Tip! don't get caught out by your shell. In the second case, I used a URL parameter with
?param1=syntax. If I had not added double quotes around the whole URL, my shell (zsh, in my case) would have responded with
zsh: no matches found. It gets worse if you include additional URL parameters with the
¶m2=syntax, as the
&will background the command, in many shells. If in doubt, add quotes!
Post a Tweet:
$ twurl -X POST "/1.1/statuses/update.json?status=this is a new Tweet sent using twurl"
Get a Tweet with poll from the Labs endpoint:
If you have enrolled to test the new Twitter Developer Labs APIs, you can use
twurl to test them, too. Here's an example fetching a recent Tweet with a poll, requesting detailed information and expanding the poll data and author user object.
$ twurl "/labs/1/tweets?ids=1155833627743272960&format=detailed&expansions=author_id,attachments.poll_ids"
Remember that if you want to pretty print the results, you can do something like piping the output to
If you enjoy learning from examples, you’ll find a Gist with a bunch of handy
twurl queries here, to give you a feel for how powerful it is.
There are also instructions on how to use
twurl with the Twitter Ads API (note that the Ads API requires your developer account to have additional whitelisting); and our friend Sam Schmir has his own nice tutorial on Medium, again more oriented to the Ads API, but there are some useful tips in there as well.
Let me know if you have any questions!