APIv1 Wrapper Usage

It’s fairly simple to use the wrapper, so here’s how you do it.

If you want a more thorough run down of any of the API calls, visit the chr docs, and read the API section.


It’s fairly easy to setup a wrapper instance, but you will need some things:

  • The URL to the chr instance (in this case we’ll use: chr.so)
  • Your API key (in this case, it’s just: ...)

Here’s how you set up your wrapper:

>>># Obviously v1 is for APIv1
>>> import chrw.v1

>>> # chr.so is our url, ... is our API key
>>> w = chrw.v1.wrapper("chr.so", "...")


Shortening URLs can be done with a call to the chrw.v1.wrapper.shorten() method.

>>> reply = w.shorten("http://foo-bar.example.com/baz", custom="foo", give_delete=True)
>>> pprint.pprint(reply)
{u'delete': u'XXXXXXXXXX',
 u'enum': 0,
 u'error': u'false',
 u'given': u'http://foo-bar.example.com/baz',
 u'message': u'Successfully shrunk your URL!',
 u'short': u'+foo',
 u'url': u'http://chr.so/+foo'}


If you want to delete a URL, you’ll need to call chrw.v1.wrapper.delete() with the deletion key you got when you made the URL.

>>> reply = w.delete("+foo", "XXXXXXXXXX")
>>> pprint.pprint(reply)
{u'enum': 0,
 u'error': u'false',
 u'message': u'Successfully deleted http://chr.so/+foo'}


Pulling up information about a given URL could not be easier than calling chrw.v1.wrapper.stats().

>>> reply = w.stats("+foo")
>>> pprint.pprint(reply)
{u'clicks': {u'browsers': {u'unknown': 0},
             u'pd': {u'01/08': 0,
                     u'01/09': 0,
                     u'02/05': 0,
                     u'02/06': 0},
             u'platforms': {u'unknown': 0}},
 u'enum': 0,
 u'error': u'false',
 u'hits': {u'all': 0, u'ratio': u'0', u'return': 0, u'unique': 1},
 u'long': u'http://foo-bar.example.com/baz',
 u'long_clip': u'http://foo-bar.example.com/baz',
 u'message': u'Here are your stats, piping hot from the oven!',
 u'short': u'+foo',
 u'short_url': u'http://chr.so/+foo'}

This simply tells us that there hasn’t been any clicks yet. Not a single damn one. :(


If you have a shortened URL you’d like info on, you can simply call chrw.v1.wrapper.expand(), and all of your questions will be answered.

>>> reply = w.expand("+foo")
>>> pprint.pprint(reply)
{u'enum': 0,
 u'error': u'false',
 u'long': u'http://foo-bar.example.com/baz',
 u'message': u"Here's the expanded URL",
 u'short': u'+foo'}


At some point in time, you’re bound to come across some exceptions.

The API is turned off, your API key is nolonger valid, you gave a bad URL; it could be anything!

These are easy to handle with try: ... except clauses in Python, and you can find the exception list at chrw.exceptions.

A quick example, which involves catching chrw.exceptions.RequestRateTooHigh.

>>> import chrw.v1
>>> w = chrw.v1.wrapper("chr.so", "...")
>>> try:
...     for x in xrange(0, 10):
...         reply = w.shorten("http://some-damn-website.com/{0}".format(x))
... except chrw.exceptions.RequestRateTooHigh:
...     print "Girl, you requestin' too darn fast!"
...     print "Slow yo' self down!"
...     raise
Girl, you requestin' too darn fast!
Slow yo' self down!
Traceback (most recent call last):
  File "<stdin>", line 3, in <module>
  File "/home/chris/github/chrw/chrw/v1.py", line 93, in shorten
    "delete": "true" if give_delete else ""
  File "/home/chris/github/chrw/chrw/v1.py", line 33, in rate_limited_function
    raise chrw.exceptions.RequestRateTooHigh, msg
chrw.exceptions.RequestRateTooHigh: Last request was 0:00:00.000016, should be at least 0:00:01