Features
- Generate or get existing snai.ly URLs, with sequential or custom keyword.
- Get statistics about your links: top clicked links, least clicked links, newest links.
- Output format: JSON, XML, or simple raw text.
- Authenticate either with login/password or using a secure passwordless mechanism.
Usage
You need to send parameters to http://snai.ly/yourls-api.php
either via GET
or POST
(remember to URL-encode parameters if via GET). These parameters are:
- A valid
username
/password
pair, or yoursignature
(see Passwordless API requests) - The requested
action
: “shorturl” (get short URL for a link), “expand” (get long URL of a shorturl), “url-stats” (get stats about one short URL), “stats” (get stats about your links) or “db-stats” (get global link and click count) - With action = “shorturl” :
- the
url
to shorten - optional
keyword
andtitle
for custom short URLs - output
format
: either “jsonp”, “json”, “xml” or “simple”
- the
- With action = “expand” :
- the
shorturl
to expand (can be either ‘abc’ or ‘http://site/abc’) - output
format
: either “jsonp”, “json”, “xml” or “simple”
- the
- With action = “url-stats” :
- the
shorturl
for which to get stats (can be either ‘abc’ or ‘http://site/abc’) - output
format
: either “jsonp”, “json” or “xml”
- the
- With action = “stats” :
- the
filter
: either “top”, “bottom”, “rand” or “last” - the
limit
(maximum number of links to return) - output
format
: either “jsonp”, “json” or “xml”
- the
- With action = “db-stats” :
- output
format
: either “jsonp”, “json” or “xml”
- output
- With action = “version” :
- output
format
: either “jsonp”, “json”, “xml” or “simple”
- output
Sample requests
Example of a GET request with Javascript (using jQuery) to shorten a URL.
var api_url = 'http://snai.ly/yourls-api.php';
var response = $.get( api_url, {
username: "your_username",
password: "your_password",
action: "shorturl",
format: "json",
url: "http://zap-hosting.com/"
},
// callback function that will deal with the server response
function( data) {
// now do something with the data, for instance show new short URL:
alert(data.shorturl);
}
);
Example of a POST request with PHP to expand a short URL.
<?php
$username = 'your_username';
$password = 'your_password';
$api_url = 'http://snai.ly/yourls-api.php';
// Init the CURL session
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_url);
curl_setopt($ch, CURLOPT_HEADER, 0); // No header in the result
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return, do not echo result
curl_setopt($ch, CURLOPT_POST, 1); // This is a POST request
curl_setopt($ch, CURLOPT_POSTFIELDS, array( // Data to POST
'shorturl' => 'ozh',
'format' => 'json',
'action' => 'expand',
'username' => $username,
'password' => $password
));
// Fetch and return content
$data = curl_exec($ch);
curl_close($ch);
// Do something with the result. Here, we echo the long URL
$data = json_decode( $data );
echo $data->longurl;
Sample returns
Sample return in JSON format for the shorturl
action.
{
"url": {
"keyword": "zap",
"url": "http:\/\/zap-hosting.com",
"title": "zap MARVIN \u00ab zap-hosting.com",
"date": "2014-10-24 16:01:39",
"ip": "127.0.0.1"
},
"status": "success",
"message": "http:\/\/zap-hosting.com added to database",
"title": "zap MARVIN \u00ab zap-hosting.com",
"shorturl": "http:\/\/snai.ly\/1f",
"statusCode": 200
}
Sample return in XML format for the expand
action.
<result>
<keyword>zap</keyword>
<shorturl>http://snai.ly/zaphosting</shorturl>
<longurl>http://zap-hosting.com/</longurl>
<message>success</message>
<statusCode>200</statusCode>
</result>