Here, Mac OS X (*) Twitter Users, I made you this:

Download: twitterapicount.sh

Download it, put it somewhere like $HOME/bin/twitterapicount.sh and do this in Terminal:

chmod 755 ~/bin/twitterapicount.sh

then open a new Terminal.app window and type

twitterapicount.sh YourTwitterName YourTwitterPassword

and it will tell you

A) How many API hits Twitter is currently giving out

B) How many API hits you have used this hour

C) How long you have to wait for a new batch of API hits

For example, the current information for my TJ account is shown here (note the $ is used just to represent the Terminal.app prompt):

$ twitterapicount.sh tj REDACTED


Twitter API totals for account:     tj

Number of API Hits Allowed Per Hour:    70
Number of Hits You Have Remaining:  65

Time remaining until API count reset:   52 minutes

Background

Craig Hockenberry (aka chockenberry), the man behind The Bird helped out some Twittees by letting us know that we could find out this limit by fetching an XML file like this:

curl -u TWITTERNAME:TWITTERPASSWORD http://twitter.com/account/rate_limit_status.xml

which gives you results like this:

<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <reset-time type="datetime">2008-07-09T18:42:21+00:00</reset-time>
  <remaining-hits type="integer">65</remaining-hits>
  <hourly-limit type="integer">70</hourly-limit>
  <reset-time-in-seconds type="integer">1215628941</reset-time-in-seconds>
</hash>

which is totally awesome if you’re a computer, but not so good if you’re a human.

That information can be easily parsed into human-readable format, which is all this script does. You can open it in TextEdit or BBedit or whatever if you’d like to see what it does. I get a little OCD when writing comments in code, and it’s not elegant (Ruby/Perl/etc coders look away! I’m hideous!) but it works.

Warnings and Options

If there is someone else logged into your computer (via ssh, for example) and they happen to run ‘ps’ at just the right time when this script is running, they might see your Twitter password. For most people this is as unlikely as getting pregnant while riding a pogo stick wearing ski pants, but in the interest of full-disclosure, I thought I’d mention it.

If you are worried about this, you have two options:

1) Open the file, read the source and follow the instructions to hard-code your username and password into it. Then you will only have to call the file “twitterapicount.sh” and it will give you the info. NOTE: if you do this, run

chmod 700 ~/bin/twitterapicount.sh

afterwards to make sure that no one else can read it.

2) If you don’t want your password showing up in ‘ps’ and you don’t want to muck with the source code, just run the program and tell it your username and leave off the password, and it will prompt you for it, like so:

$ twitterapicount.sh tj
twitterapicount.sh: You gave me the Twitter username "tj".
Now I need the password (this is not stored anywhere)


Password for tj ?

(Obviously you want to use your Twitter name, not ‘tj’)

Once you type in your password, it will proceed as normal.

I think that’s it.

Questions / comments / feedback: luomat at gmail com

() Oh, this will probably work for those of you who use other variants of Unx too.