My favorites ▼ | Sign in
Project Home Wiki Issues
Search
for
ApiDocumentation  
同学网 API 文档 15210246172
Featured
Updated Jan 10, 2010 by zenglei0...@gmail.com

API更新记录

2009-12-31

  • 添加了checkin的相关方法
2009-09-16
  • 修正了消息里返回图片(photo_url)的bug

2009-08-06

  • 同学API内测版上线

关键词说明

  • 某某的朋友: 是某某关注的人
  • 某某的关注者:是关注某某的人
  • 所有消息文本保存的时候，都经过了html编码，调用的是PHP(html_entity_decode)方法，如果不是以html显示的话，需要对文本经过编码后输出方可
  • 消息文本中包含UBB标签，以下是PHP解析:
    • 匹配标准用户/VIP标签:'/\[url\=(http\:\/\/(vip\.|www\.|)(tongxue|fr)\.com\/([a-zA-Z0-9]{1,50}))\]([^\]]?)\[\/url\]/i" 显示成: "< a href='$1' class='username'>$5</ a>'
    • 匹配URL标签: /\[url\=((https?|ftp)\\:\\/\\/(\\w+(\\:\w+)@)?\\w+(\\.\\w+)(\\/[\\[\\]]*)*)\]([\]]?)\[\/url\]/i" 显示成: "< a href='$1' target='blank'>$7</ a >

基本概念

用户验证

如需要验证用户，验证方式为 HTTP Basic 验证。

用户 id

用户 id 在个人网址中，例如：http://tongxue.com/tongxue 蓝色的部分即为用户 id。

使用 API 的简单途径

如果你的系统中有 cURL，就可以通过非常简单的方式使用这些API了。

示例：

  • 显示随便看看的消息
curl http://api.tongxue.com/statuses/public_timeline.php
  • 显示用户消息
curl -u loginname:password http://api.tongxue.com/statuses/user_timeline.php
  • 显示用户和好友的信息
curl -u loginname:password http://api.tongxue.com/statuses/friends_timeline.php
  • 发布消息
curl -u loginname:password -d status="消息内容" http://api.tongxue.com/statuses/update.xml

API应用认证

通过认证的应用，在每条消息后会有 '通过 YOUR_APP_NAME' 的信息，YOUR_APP_NAME是你的应用名，并链接到应用的发布网址。

你的应用希望通过认证？请：

  1. 确保发新消息正确的传递了 source 参数（参考下面的 statuses update 方法）
  2. 请到同学网开发者论坛发帖，注明应用的source参数、应用名称、网址及简介。我们的工作人员将及时处理。

说明：

  • source参数请使用英文，source参数仅作为识别标志、不在网页上显示
  • 应用名称 将显示在网页上，也就是上文提到的YOUR_APP_NAME，建议使用中文

API 方法说明

消息相关的方法

显示随便看看的消息

路径： http://api.tongxue.com/statuses/public_timeline.php

参数：

  • count (可选) - 消息数，范围 1-20，默认为 20。
示例： http://api.tongxue.com/statuses/public_timeline.php?count=10
  • format (可选）beta － 消息内容格式，当 format=html 时，返回消息的内容字段是进行@识别，网址识别等后台处理之后的html代码。
  • callback (可选) - JavaScript 函数名，使用 JSON 格式时可用，将 JSON 对象作为参数直接调用
示例： http://api.tongxue.com/statuses/public_timeline.json?callback=getStatuses

显示用户和好友的消息

路径： http://api.tongxue.com/statuses/friends_timeline.php

参数：

  • id (可选，注意：将来可能不再支持此参数) - 用户 id，没有此参数或用户设隐私时需验证用户。有此参数时返回的是此用户和好友的所有消息，没有此参数时返回的是当前用户的首页中的最新消息。
示例： http://api.tongxue.com/statuses/friends_timeline.php?id=tongxue
  • count (可选) - 消息数，范围 1-20，默认为 20。
示例： http://api.tongxue.com/statuses/friends_timeline.php?count=10
  • since_id (可选) - 仅返回比此 ID 大的消息。
示例： http://api.tongxue.com/statuses/friends_timeline.xml?since_id=6IAZmgy1TzA
  • max_id (可选) - 仅返回 ID 小于等于此 ID 的消息。
示例： http://api.tongxue.com/statuses/friends_timeline.xml?max_id=6IAZmgy1TzA
  • page (可选) - 页码，从 1 开始
示例： http://api.tongxue.com/statuses/friends_timeline.json?page=3
  • format (可选）beta － 消息内容格式，当 format=html 时，返回消息的内容字段是进行@识别，网址识别等后台处理之后的html代码。
  • callback (可选) - JavaScript 函数名，使用 JSON 格式时可用，将 JSON 对象作为参数直接调用
示例： http://api.tongxue.com/statuses/friends_timeline.json?callback=getStatuses
  • since (可选) - 取这个时间段后的消息。注意，传递时间日期时，只能转换为日期的long型数值才能传递

显示用户的消息

路径： http://api.tongxue.com/statuses/user_timeline.php

参数：

  • id (可选) - 用户 id，没有此参数或用户设隐私时需验证用户。
示例： http://api.tongxue.com/statuses/user_timeline.php?id=tongxue 或 http://api.tongxue.com/statuses/user_timeline/tongxue.php
  • count (可选) - 消息数，范围 1-20，默认为 20。
示例： http://api.tongxue.com/statuses/user_timeline.php?count=10
  • since_id (可选) - 仅返回比此 ID 大的消息。
示例： http://api.tongxue.com/statuses/user_timeline.xml?since_id=6IAZmgy1TzA1
  • max_id (可选) - 仅返回 ID 小于等于此 ID 的消息。
示例： http://api.tongxue.com/statuses/user_timeline.xml?max_id=6IAZmgy1TzA
  • page (可选) - 页码，从 1 开始
示例： http://api.tongxue.com/statuses/user_timeline.json?page=3
  • format (可选）beta － 消息内容格式，当 format=html 时，返回消息的内容字段是进行@识别，网址识别等后台处理之后的html代码。
  • callback (可选) - JavaScript 函数名，使用 JSON 格式时可用，将 JSON 对象作为参数直接调用
示例： http://api.tongxue.com/statuses/user_timeline.json?callback=getStatuses
  • since (可选) - 取这个时间段后的消息。注意，传递时间日期时，只能转换为日期的long型数值才能传递

显示指定消息

路径： http://api.tongxue.com/statuses/show.php

参数：

  • id (必需) - 消息的id。
示例： curl -u loginname:password http://api.tongxue.com/statuses/show.php?id = 17db80f740171d1c57ce588073fbccfc

显示发给当前用户的消息

路径： http://api.tongxue.com/statuses/replies.php

参数：

  • count (可选) - 消息数，范围 1-20，默认为 20。
示例： http://api.tongxue.com/statuses/replies.php?count=10
  • since_id (可选) - 仅返回比此 ID 大的消息。
示例： http://api.tongxue.com/statuses/replies.xml?since_id=6IAZmgy1TzA
  • max_id (可选) - 仅返回 ID 小于等于此 ID 的消息。
示例： http://api.tongxue.com/statuses/replies.xml?max_id=6IAZmgy1TzA
  • page (可选) - 页码，从 1 开始
示例： http://api.tongxue.com/statuses/replies.json?page=3
  • format (可选）beta － 消息内容格式，当 format=html 时，返回消息的内容字段是进行@识别，网址识别等后台处理之后的html代码。
  • since (可选) - 取这个时间段后的消息。注意，传递时间日期时，只能转换为日期的long型数值才能传递

发布消息

路径： http://api.tongxue.com/statuses/update.php

方法：POST

参数：

  • status (必需) - 消息内容，使用 POST 方式提交
  • in_reply_to_status_id （可选）- 如果是回复某一条消息，则在这里指明被回复的消息的ID。
  • source (可选) - 消息来源，使用 POST 方式提交，如果与同学网的数据库匹配，网页上将以此格式显示： status(消息内容) 通过 source 对应的 API 应用名称（参考上面的 API应用认证 相关说明)。

转发消息

转发 实际上是发布一条新消息，使用的是发布消息接口，我们推荐的实现是：

  • 新消息内容采用 "转：@用户名 原消息" 的格式
  • 在POST内容中增加 "repost_status_id=原消息id"

删除消息

路径： http://api.tongxue.com/statuses/destroy.php

方法：POST

参数：

  • id (必需) - 消息的id。
示例： http://api.tongxue.com/statuses/destroy/6IAZmgy1TzA.xml

照片相关的方法New!

同学网上传API模拟HTML的file input上传照片，也就是 HTTP POST 时 Content-Type 设置为 multipart/form-data。参考RFC1867 http://www.ietf.org/rfc/rfc1867.txt

照片上传

路径：http://api.tongxue.com/statuses/photos/upload.php

方法：POST

参数：

  • photo（必须）- 照片文件。和<input type="file" name="photo" />效果一样
  • status（可选）- 照片描述
  • source (可选）- 字符串；客户端标识。

搜索相关的方法

公开搜索

路径：http://api.tongxue.com/search/public_timeline.php

参数：

  • q（必须）- 检索串。
示例：http://api.tongxue.com/search/public_timeline.xml?q=tongxue 或 http://api.tongxue.com/search/public_timeline/%E9%A5%AD%E5%90%A6.xml，这里 %E9%A5%AD%E5%90%A6 是同学网的UTF8编码。
  • max_id (可选) - 仅返回 ID 小于此 ID 的消息。
示例： http://api.tongxue.com/search/public_timeline.xml?max_id=6IAZmgy1TzA

热词New!

返回当前的同学网热词。

路径：http://api.tongxue.com/trends.php

用户相关的方法

显示好友列表

路径： http://api.tongxue.com/statuses/users/followings.php

参数：

  • count (可选) - 消息数，范围 1-20，默认为 20。
  • id (可选) - 用户 id，没有此参数或用户设隐私时需验证用户。
示例： http://api.tongxue.com/statuses/users/followings.xml?id=tongxue
  • page (可选) - 页码，从 1 开始
示例： http://api.tongxue.com/statuses/users/followings.xml?page=3

显示关注者列表

路径： http://api.tongxue.com/statuses/users/followers.php

参数：

  • count (可选) - 消息数，范围 1-20，默认为 20。
  • id (可选) - 用户 id，没有此参数或用户设隐私时需验证用户。
示例： http://api.tongxue.com/statuses/users/followers.xml?id=tongxue
  • page (可选) - 页码，从 1 开始
示例： http://api.tongxue.com/statuses/users/followers.json?page=3

显示用户详细信息

路径： http://api.tongxue.com/statuses/users/show.php

参数：

  • id (可选) - 用户 id，没有此参数或用户设隐私时需验证用户。没有此参数时为当前用户。
示例： http://api.tongxue.com/statuses/users/show.xml?id=tongxue

站内信相关的方法

显示用户收到的站内信

路径： http://api.tongxue.com/direct_messages.php

参数：

  • count (可选) - 站内信数，范围 1-20，默认为 20。
示例： http://api.tongxue.com/direct_messages.xml?count=10
  • since_id (可选) - 仅返回比此 ID 大的站内信。
示例： http://api.tongxue.com/direct_messages.xml?since_id=12345
  • max_id (可选) - 仅返回 ID 小于等于此 ID 的站内信。
示例： http://api.tongxue.com/direct_messages.xml?max_id=6IAZmgy1TzA
  • page (可选) - 页码，从 1 开始
示例： http://api.tongxue.com/direct_messages.json?page=3

显示用户发的站内信

路径： http://api.tongxue.com/direct_messages/sent.php

参数：

  • count (可选) - 站内信数，范围 1-20，默认为 20。
示例： http://api.tongxue.com/direct_messages/sent.xml?count=10
  • since_id (可选) - 仅返回比此 ID 大的站内信。
示例： http://api.tongxue.com/direct_messages/sent.xml?since_id=12345
  • max_id (可选) - 仅返回 ID 小于等于此 ID 的站内信。
示例： http://api.tongxue.com/direct_messages/sent.xml?max_id=6IAZmgy1TzA
  • page (可选) - 页码，从 1 开始
示例： http://api.tongxue.com/direct_messages/sent.json?page=3

发送站内信

路径： http://api.tongxue.com/direct_messages/new.php

方法：POST

参数：

  • user (必需) - 收信人 id ，使用 POST 方式提交
  • text (必需) - 站内信内容，使用 POST 方式提交
  • in_reply_to_id （可选）- 表示回复某条站内信

删除站内信

路径： http://api.tongxue.com/direct_messages/destroy.php

方法：POST

参数：

  • id (必需) - 站内信的id。
示例： http://api.tongxue.com/direct_messages/destroy.xml?id=102

收藏相关的方法

显示用户的收藏列表

路径： http://api.tongxue.com/statuses/favorites.php

参数：

  • id (可选) - 用户 id，没有此参数或用户设隐私时需验证用户。
示例： http://api.tongxue.com/statuses/favorites.xml
  • count (可选) - 站内信数，范围 1-20，默认为 20。
示例： http://api.tongxue.com/statuses/favorites.xml?count=10
  • page (可选) - 页码，从 1 开始
示例： http://api.tongxue.com/statuses/favorites.xml?page=3
  • since (可选) - 取这个时间段后的消息。注意，传递时间日期时，只能转换为日期的long型数值才能传递

收藏某条消息

路径： http://api.tongxue.com/statuses/favorites/create.php

方法：POST

参数：

  • id (必需) - 消息的id
示例： http://api.tongxue.com/statuses/favorites/create.php?id=消息的id

删除收藏

路径： http://api.tongxue.com/statuses/favorites/destroy.php

方法：POST

参数：

  • id (必需) - 消息的id。
示例： http://api.tongxue.com/statuses/favorites/destroy.php?id=kdjfe866djf

朋友关系方法

添加朋友

路径： http://api.tongxue.com/statuses/followings/create.php

方法：POST

参数：

  • id (必需) - 用户 id
示例： http://api.tongxue.com/statuses/followings/create.php?id=tongxue

删除朋友

路径： http://api.tongxue.com/statuses/followings/destroy.php

方法：POST

参数：

  • id (必需) - 用户 id
示例： http://api.tongxue.com/statuses/followings/destroy.php?id=tongxue

判断朋友关系是否存在

路径： http://api.tongxue.com/statuses/followings/exists.php

参数：

  • user_a (必需) - 第一个用户的id
  • user_b (必需) - 第二个用户的id
示例： http://api.tongxue.com/statuses/followings/exists.php?user_a=tongxue&user_b=liangyue

朋友和关注者方法New!

显示朋友id列表

路径： http://api.tongxue.com/statuses/followings/ids.php

参数：

  • format (可选) - 数据返回格式，json或xml，默认为json。

  • id (可选) - 用户 id，没有此参数或用户设隐私时需验证用户。
示例： http://api.tongxue.com/statuses/followings/ids.php?id=tongxue

显示关注者id列表

路径： http://api.tongxue.com/statuses/followers/ids.php

参数：

  • format (可选) - 数据返回格式，json或xml，默认为json。

  • id (可选) - 用户 id，没有此参数或用户设隐私时需验证用户。
示例： http://api.tongxue.com/statuses/followers/ids.php?id=tongxue

提醒相关方法

获得提醒数目

路径： http://api.tongxue.com/notifications/index.php

参数：

  • id (必需) - 用户 id
示例： http://api.tongxue.com/notifications/index.xml?id=tongxue

  • callback (可选) - JavaScript 函数名，使用 JSON 格式时可用，将 JSON 对象作为参数直接调用
示例： http://api.tongxue.com/notifications/index.json?callback=getStatuses

返回值：

  • reply_num - 留言数
  • msg_num - 站内信数
  • noti_num - 站内通知数

对某个类型的提醒清零

路径： http://api.tongxue.com/notifications/clear.php

参数：

  • id (必需) - 用户 id
示例： http://api.tongxue.com/notifications/clear.xml?id=tongxue 或 http://api.tongxue.com/notifications/clear.php？id=tongxue

  • callback (可选) - JavaScript 函数名，使用 JSON 格式时可用，将 JSON 对象作为参数直接调用
示例： http://api.tongxue.com/notifications/clear.json?callback=getStatuses
  • t: reply(回复),msg(站内信),noti(通知)

返回值：

  • 1: 成功
  • 0: 失败

黑名单方法

加入黑名单

路径： http://api.tongxue.com/blocks/create.php

参数：

  • id (必需) - 用户 id
示例： http://api.tongxue.com/blocks/create.xml?id=tongxue

解除黑名单

路径： http://api.tongxue.com/blocks/destroy.php

参数：

  • id (必需) - 用户 id
示例： http://api.tongxue.com/blocks/destroy.xml?id=tongxue

账号方法

验证用户

检验用户名密码是否正确

路径： http://api.tongxue.com/account/verify_credentials.php

参数：无

保存搜索相关的方法New!

显示登录用户的搜索保存列表

路径： http://api.tongxue.com/saved_searches.php

显示指定的搜索词

路径： http://api.tongxue.com/saved_searches/show/id.php

参数：

  • id (必需) - 搜索词的id。
示例： http://api.tongxue.com/saved_searches/show/12345.xml

保存搜索词

路径： http://api.tongxue.com/saved_searches/create.php

方法：POST

参数：

  • query (必需) - 要保存的搜索词
示例： curl -u user:password -d "query=tongxue" http://api.tongxue.com/saved_searches/create.xml

删除搜索词

路径： http://api.tongxue.com/saved_searches/destroy/id.php

方法：POST

参数：

  • id (必需) - 消息的id。
示例： http://api.tongxue.com/saved_searches/destroy/12345.json 或 http://api.tongxue.com/saved_searches/destroy/12345.xml

地图功能

获得用户最近check in的地点列表

路径： http://api.tongxue.com/place/user_checkin_list.php

注意 ：此方法需要验证用户

参数：

  • count (可选) - 消息数，范围 1-20，默认为 5
  • format (可选) - 数据返回格式，json或xml，默认为json等后台处理之后的html代码
示例：http://api.tongxue.com/place/user_checkin_list.php?id=tongxue&count=5&format=xml

用户check in到某一个地点

路径： http://api.tongxue.com/place/user_checkin.php

注意 ：此方法需要验证用户

参数：

  • place_id(必须) ， 要check in的地点id。
  • format (可选) - 数据返回格式，json或xml，默认为json等后台处理之后的html代码
示例：http://api.tongxue.com/place/user_checkin.php?place_id=61&format=xml

辅助方法

测试API

用指定格式返回一个 ok 值，返回的 HTTP code 为 200

路径： http://api.tongxue.com/help/test.php

参数：无

返回的参数模块

消息模块

消息模块由消息的信息组成，其中用一个用户模块来描述消息的发起人 

<status>
<create_at>
<id>
<text>
<source>
<in_reply_to_profile_link>
<truncated>
<in_reply_to_status_id>
<in_reply_to_user_id>
<favorited>
<in_reply_to_screen_name>
<photo_url>
<user>
<id>
<name>
<screen_name>
<gender>
<personal_link>
<location>
<description>
<profile_image_url>
<url>
<protected>
<followers_count>

用户基本信息模块

用户基本信息模块由用户的基本信息组成，其中用一个消息模块来描述此用户最新的一条消息 

<user>
<id>
<name>
<screen_name>
<gender>
<personal_link>
<location>
<description>
<profile_image_url>
<url>
<protected>
<followers_count>
<status>
<create_at>
<id>
<text>
<source>
<truncated>
<in_reply_to_status_id>
<in_reply_to_user_id>
<favorited>
<in_reply_to_screen_name>

用户扩展信息模块

用户扩展信息模块，较详细的表示了用户的各项信息。(以后还会继续补充) 

<user>
<id>
<name>
<gender>
<personal_link>
<screen_name>
<location>
<description>
<profile_image_url>
<url>
<protected>
<followings_count>
<followers_count>
<favourites_count>
<statuses_count>
<create_at>
<following>
<notifications>
<utc_offset>

站内信模块

站内信模块由站内信的各项属性组成，其中由sender模块表示发信人信息，recipient模块表示收信人信息 

<direct_message>
<id>
<text>
<sender_id>
<recipient_id>
<create_at>
<sender_screen_name>
<recipient_screen_name>
<sender>
<id>
<name>
<gender>
<personal_link>
<screen_name>
<location>
<description>
<profile_image_url>
<url>
<protected>
<followers_count>
<recipient>
<id>
<name>
<gender>
<personal_link>
<screen_name>
<location>
<description>
<profile_image_url>
<url>
<protected>
<followers_count>

返回的参数属性值

created_source

描述：1: 原始发，2: 转载，3: 留言, 4: 回复消息, 5: 关注, 6: 上传照片到相册, 7: 头像, 8: 同时

in_reply_to_profile_link

描述: 回复用户的个性域名

personal_link

描述: 用户的个性域名，如果为空的话，则为用户ID

gender

描述: 1 是男，2 是女

create_at

描述: 元素的创建时间

示例: Fri Apr 10 12:59:35 +0000 2009

description

描述: 用户的自述

示例: 默认值为空

favorited

描述: 表示当前消息是否已被收藏

示例: true, false

favorites_count

描述: 当前用户的收藏数

示例: 0, 268

following

描述: 表示被验证用户是否已经把当前用户加为好友了

示例: true, false

followers_count

描述: 当前用户的被关注数

示例: 0, 2013

followings_count

描述: 当前用户的好友数

示例: 0, 801

name

描述: 当前用户的昵称

示例: 同学网, 阿正

id

描述: 元素的独立id

示例: 4L0aUggHfq8 (消息id), tongxue (用户id)

in_reply_to_screen_name

描述: 消息所回复的用户昵称

示例: (空值), 同学网

in_reply_to_status_id

描述: 被回复的消息id

示例: (空值), 4L0aUggHfq8

in_reply_to_user_id

描述: 消息所回复的用户id

示例: (空值), tongxue

location

描述: 用户的所在地

示例: 北京, 上海

notifications

描述: 表示被验证的用户是否接收当前用户的消息通知

示例: true, false

profile_image_url

描述: 当前用户的头像地址

示例:

protected

描述: 表示当前用户是否设置了“需要我批准才能查看我的消息”

示例: true, false

screen_name

描述: 当前用户的昵称

示例: 同学网, 阿正

source

描述: 消息的发布途径,假如没有事先定好的source参数，使用：10000，来自于API

示例: 网页, 手机上网

statuses_count

描述: 当前用户的消息数

示例: 0, 2068

text

描述: 消息的内容

示例: 同学网排行榜新增最新动态，可以看到刚刚给自己打过标签的人。

truncated

描述: 表示当前消息是否需要截断

示例: true, false

url

描述: 用户个人信息中的网站地址

示例: http://dev.tongxue.com

意见反馈

请访问同学网开发者论坛

Comment by vvto...@gmail.com, Nov 20, 2009

收藏返回为空？？

Comment by chy...@gmail.com, Nov 9, 2010

place_id(必须) ， 要check in的地点id。 如何获得此id?


► Sign in to add a comment
Powered by Google Project Hosting