YOURLS' API

YOURLS' API

特征

• 生成或获取现有的短URL，带有顺序关键字或自定义关键字
  获取一些关于你的链接的统计信息：点击链接，点击最少的链接，最新链接
  输出格式：JSON、XML或简单的原始文本
  Authentify或者用户名/密码或使用安全密码机制

Usage

You need to send parameters to http://your-own-domain-here.com/yourls-api.php either via GET or POST (remember to URL encode parameters if via GET). These parameters are:

你需要发送参数 http://your-own-domain-here.com/yourls-api.php 通过GET或POST（记住URL编码的参数，如果通过获得）。这些参数是：

• 一个有效的用户名/密码对，或您的签名（见文章的API请求）
  请求的操作：“URL缩短”（得到一个短链接的URL），“扩大”（得到一个URL缩短长的URL），URL的状态”（获得一个短网址统计），“统计”（获取你的链接属性）或“数据库属性”（获得全球链接和点击

• A valid username / password pair, or your signature (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 and title for custom short URLs
  • output format: either "jsonp", "json", "xml" or "simple"
• With action = "expand" :
  • the shorturl to expand (can be either 'abc' or 'http://site/abc')
  • output format: either "jsonp", "json", "xml" or "simple"
• 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"
• 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"
• With action = "db-stats" :
  • output format: either "jsonp", "json" or "xml"

Sample requests

Example of a GET request with Javascript (using jQuery) to shorten a URL

var api_url  = 'http://sho.rt/yourls-api.php';
var response = $.get( api_url, {
    username: "your_username",
    password: "your_password",
    action:   "shorturl",
    format:   "json",
    url:      "http://ozh.org/"
    },
    // 回调函数，它将处理服务器响应
    function( data) {
        // 现在用数据做一些事情，例如显示新的短URL
        alert(data.shorturl);
    }
);

php  POST  请求扩展短URL的示例  Example of a POST request with PHP to expand a short URL

<?php
$username = 'your_username';
$password = 'your_password';
$api_url =  'http://sho.rt/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": "ozh",
    "url": "http:\/\/ozh.org",
    "title": "Ozh RICHARD \u00ab ozh.org",
    "date": "2014-10-24 16:01:39",
    "ip": "127.0.0.1"
  },
  "status": "success",
  "message": "http:\/\/ozh.org added to database",
  "title": "Ozh RICHARD \u00ab ozh.org",
  "shorturl": "http:\/\/sho.rt\/1f",
  "statusCode": 200
}

Sample return in XML format for the expand action

<result>
    <keyword>ozh</keyword>
    <shorturl>http://sho.rt/ozh</shorturl>
    <longurl>http://ozh.org/</longurl>
    <message>success</message>
    <statusCode>200</statusCode>
</result>

Sample file

There's a sample PHP file included that serves as an example on how to play with the API

Expand the API

You can easily implement custom API actions with a plugin. See the plugin list for examples.