yourls-api

yourls-api is a JavaScript library that provides bindings for the YOURLS API using JSONP.

Connecting

yourls.connect(url[, credentials])

This is the first step and where you'll provide the URL of the YOURLS API you wish to connect to, baring in mind that the URL should point to the yourls-api.php file and not just its directory. If you're going to be connecting to a private YOURLS installation you'll also need to provide either the username/password or the signature token if you're wanting to use passwordless API requests (the signature token takes precedence here).

var exampl = yourls.connect('http://exam.pl/yourls-api.php', {
//  username: 'admin'
//, password: 'qwerty'
  , signature: '3002a61584'
})

Despite the name no connection or authentication is carried out at this point and this initial method simply stores these values to prevent you from specifying them with every API call.

Shortening

yourls.shorten(url[, keyword], callback(data)[, context])

This method shortens the URL provided optionally using a custom keyword/hash.

exampl.shorten('http://neocotic.com/yourls-api', 'yourls', function(data) {
  console.log(data.shorturl) // http://exam.pl/yourls
})

Statistics

yourls.stats([filter, ][limit, ]callback(data)[, context])

This method fetches the statistics on all your links but also allows you to filter and limit what is returned.

exampl.stats('last', 1, function(data) {
  var myLink = data.links.link_1
  console.log(myLink.shorturl)         // http://exam.pl/yourls
  console.log(myLink.url)              // http://neocotic.com/yourls-api
  console.log(myLink.title)            // yourls-api · neocotic
  console.log(myLink.clicks)           // 1987
  // Overall statistics
  console.log(data.stats.total_links)  // 12
  console.log(data.stats.total_clicks) // 2012
})

URL Information

yourls.url(url)

Unlike the other API calls this constructs an instance of a yourls.url for the URL provided (which should be a shortened URL).

var myUrl = exampl.url('http://exam.pl/yourls')

Once you have this instance more operations become available that are applicable only to the URL provided here.

Expanding

yourls.url.expand(callback(data)[, context])

This method fetches the original long URL for your link.

myUrl.expand(function (data) {
    console.log(data.keyword)  // yourls
    console.log(data.shorturl) // http://exam.pl/yourls
    console.log(data.longurl)  // http://neocotic.com/yourls-api
})

Statistics

yourls.url.stats(callback(data)[, context])

This method fetches the statistics for your link.

myUrl.stats(function (data) {
    console.log(data.link.shorturl) // http://exam.pl/yourls
    console.log(data.link.url)      // http://neocotic.com/yourls-api
    console.log(data.link.title)    // yourls-api · neocotic
    console.log(data.link.clicks)   // 1987
})

Miscellaneous

The API exposes some properties and methods which may only be useful to users in special cases.

yourls.noConflict()

Relinquish yourls-api's control of the yourls global variable. If another library uses this variable calling this method will reassign it back to that library.

yourls.VERSION

The current version of yourls-api.

Bugs

If you have any problems with this library or would like to see the changes currently in development browse our issues.

Questions?

Take a look at the documentation to get a better understanding of what the code is doing.

If that doesn't help, feel free to follow me on Twitter, @neocotic.