How to use twurl to quickly test the Twitter API
Published: 2019-07-29 15:06:32

Have you ever needed to quickly try out a query against the Twitter API? Well then... meet [twurl](https://github.com/twitter/twurl).

### The Swiss Army Knife for the Twitter APIs

I 💙 `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](https://twittercommunity.com), or help to answer questions posted on the `twitter` tag on Stack Overflow. 

Why is it called “twurl”? Simple - it’s a bit like curl, for the Twitter API! 🤓

Using `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](https://github.com/stedolan/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](http://stedolan.github.io/jq/), 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](https://developer.twitter.com/en/docs/basics/twitter-ids.html), it will mangle the numeric long integer IDs inside Tweet objects, so you should always use the `_str` variants instead.

### Getting started

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](https://rubyinstaller.org/).

The other thing you will need to do is to register for a [Twitter Developer Account](https://t.co/apply-for-access), 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.

### Next steps

`$ gem install twurl`

Once your `twurl` gem is installed, you should find that running the `twurl` command line presents the help information (confirm via `which twurl`). 

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.

### Ready?

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 `&param2=` 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](https://developer.twitter.com/en/labs), you can use `twurl` to test them, too. Here's an example fetching [a recent Tweet with a poll](https://twitter.com/andypiper/status/1155833627743272960), 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 `jq`.

### Want to learn more?

If you enjoy learning from examples, you’ll find a Gist with a bunch of handy `twurl` queries [here](https://gist.github.com/andypiper/32bdb4c7f0b8d65385fc7c8fa3988083), to give you a feel for how powerful it is. 

There are also [instructions](https://developer.twitter.com/en/docs/tutorials/using-twurl.html) on how to use `twurl` with the [Twitter Ads API](https://developer.twitter.com/en/docs/ads/general/overview) (note that the Ads API requires your developer account to have additional whitelisting); and our friend Sam Schmir has his own [nice tutorial](https://medium.com/@SamSchmir/a-guide-to-the-twitter-api-and-twurl-8711466a0635) 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!