This small library was created to provide an easy interface to YOURLS from a python program.

Simple example of shortening a URL:

import yourls.client

c = yourls.client.YourlsClient('http://localhost/yourls/yourls-api.php', username='username', password='password')
url = c.shorten('', custom='autoqa')


There has been a change in how errors are thrown in 0.2.0, please see the API documenatation for details.

Code Download

The code can be checked out from the github repository:
  • git clone git://
Or the code can be downloaded as a tarball from github:

API Documentation

exception yourls.YourlsError(message)[source]

Base exception for all Yourls exceptions

exception yourls.YourlsOperationError(url, message)[source]

Error during URL operations

class yourls.client.YourlsClient(apiurl, username=None, password=None, token=None)[source]

Expand a shortened URL to its original form

Parameters:shorturl – The URL to expand
Returns:str – The expanded URL
Raises :YourlsOperationError

Get statistics about a shortened URL

Parameters:shorturl – The URL to expand
Returns:a list of stuff - FIXME, this isn’t complete
Raises :YourlsOperationError
shorten(url, custom=None, title=None)[source]

Request a shortened URL from YOURLS with an optional keyword request

  • url (str) – The URL to shorten
  • custom (str) – The custom keyword to request
  • title (str) – Use the given title instead of download it from the URL, this will increase performances

str – The short URL

Raises :


Indices and tables

Table Of Contents

Next topic


This Page