API文档

如果需要帮助,你还可以
发邮件至: 955@vip.955.cc
我们会24小时内给你回复

▲ 返回顶部

API 简介

API允许第三方自由调用URL缩短或者URL还原,基于txt/json/jsonp模式。

目前没有针对用户的请求频数做限制,但是如果滥用或造成资源浪费,将可能会自动被封禁IP段。

现在 955 短网址已经支持 https 的调用(spdy)。您现在还可以调用 https://955.cc/short/,并且支持https访问生成的短网址。

支持的网址

如果缩短的网址没有写明协议,默认为 http://。除了支持 http,我们还支持 https/ftp/P2P 网址等。

1、简单模式

请求 955.cc/short/?url=baidu.com 返回txt明文,为压缩过后的网址。

http://955.cc/ay
如果出错则将返回类似这样的格式:
提示:你所输入的网址(URL)是不允许的。(-2) 

2、json

请求 955.cc/short/?url=baidu.com&format=json 返回json数据

{
"errno":0,
"url":"http:\/\/955.cc\/ay",
"error":""
}
如果 errno 为0说明成功,-1为URL因为安全原因被拦截,拦截原因见error。

3、jsonp

请求方式同上,但是format为jsonp,并要指定callback,

例如:955.cc/short/?url=baidu.com&format=jsonp&callback=test 将会返回类似数据:

test({
"errno":0,
"url":"http:\/\/955.cc\/ay",
"error":""
})

还原

如果请求的url参数格式是 http://955.cc/([a-zA-Z0-9]+) 则返回结果里的url显示的是原始URL。

例如:http://955.cc/short/?url=955.cc/ay&format=jsonp&callback=test 返回

test({
"errno":0,
"error":"",
"url":"http:\/\/baidu.com"
})

错误代码

  1. 0 为成功无错。
  2. -1为因为安全原因被拦截。拦截原因见 error 的说明。

        我们的系统会查询国内主流安全商并封禁威胁用户安全的网址。如果出现误报请邮件联系管理员。

  3. -2 为其他错误,往往是格式不对。
  4. -3是指定为jsonp时,如果未指定callback存会出现此错误。
  5. 如果内容为空或者http状态码非200,则说明系统出现异常,需要稍后再试。

使用的例子:

在jQuery中使用的例子:

$.getJSON('http://955.cc/short/?url=' + encodeURIComponent('http://baidu.com') + '&format=jsonp&callback=?',
function(data){
if(data.errno == 0) {
alert(data.url);
}
}
);

在Python中使用的例子:

#coding=utf8
import urllib2
content = urllib2.urlopen("http://955.cc/short/?url=www.douban.com").read()
print content

在Ruby中使用的例子:

require "open-uri"
content = open('http://955.cc/short/?url=www.douban.com').read
print content

在PHP中使用的例子:

<?php
$content = file_get_contents("http://955.cc/short/?url=" . urlencode($_SERVER['HTTP_HOST'])."&format=json");
var_dump(json_decode($content,1));

QRCode 二维码调用

调用格式为 http://955.cc/短地址代码.qr,例如: 「http://955.cc/ay.qr」,显示结果为:

此外如需为QR码指定尺寸,可以附带size参数,为图片的像素宽/高。例如:

http://955.cc/ay.qr?size=500
需要注意的是,1、尺寸大小范围为30~1000px。2、尽量使用常见取整的像素值,例如 120px、200px,未来可能会对传入尺寸化去不常见格式的个位数,以助于Cache。

数据统计API

数据统计API是2013年五月份后开放的,数据也是自此开始统计的,支持查询单个短网址的数据。(由于系统升级,5~7月数据不再提供,API获取的数据从2013年7月底起,如对旧数据有需求请联系我们。)

我们致力于成为更开放的平台,在保护隐私的基础上将逐步提供更多API。需要注意的是:

  • 1、请控制好请求频率。如有特殊需求请与我们邮件沟通。
  • 2、统计的数据是从 2013 年五月份七月底启用新架构后的。
  • 3、目前仅支持 json 方式调用。

全部数据

调用地址为: http://955.cc/api/statistics/{$code}.json?type=all 例如:http://955.cc/api/statistics/ay.json?type=all

返回格式举例:

{
"code": "ay",
"data": {
"ips": 13,
"clicks": 987
}
}
data字段里,ips是所有时间的ip数,clicks是所有时间的点击数。

每日数据

调用地址为: http://955.cc/api/statistics/{$code}.json 例如:http://955.cc/api/statistics/ay.json

支持的参数: date,例如 "2013-05-07"、"yesterday"。 由 timelib 的 strtodatetime 方法解析格式。

返回格式举例:

{
"date": "2013-7-30",
"ips": 4,
"clicks": 254,
"hour": {
"0": 16,
"1": 16,
"2": 16,
"3": 15,
"4": 16,
"5": 12,
"6": 16,
"7": 16,
"8": 16,
"9": 16,
"10": 16,
"11": 16,
"12": 16,
"13": 16,
"14": 16,
"15": 11,
"16": 8
},
"province": {
"辽宁": 62,
"陕西": 64,
"浙江": 65,
"山东": 63
}
}
字段说明:clicks:当日点击数。ips:ip数。date:数据的日期。hour:每小时的点击数,key是小时,value是该小时的点击数。province:各个省份的点击数。国外则显示国名。