Practical Guide for using Sina Weibo's API

Hi! We are Wang Ling and Guang Xiang from the Language Technologies Institute in Carnegie Mellon University.

This is a practical guide for programmers and researchers who intend to use Sina Weibo's Open API as part of their work. We found during our research (description found here) that the current official documentation is unclear and inconsistent in some extent, and in several occasions we had to learn using a trial and error process, which took some time and effort. Thus, we are writing this guide to share what we know and facilitate the usage of this API to new users.

This guide is intended for both Mandarin and non-Mandarin speakers.

In this guide you will learn to:

Create a Sina Weibo Account

Set up Open Weibo Account and Register an Application

Using the Sina Weibo API

1 - Creating a Sina Weibo Account

The first step is to create an Weibo account, this should be relatively straight-forward, but might be hard if you cannot read Mandarin. If thats your case follow the steps below.

1-1 - Go to http://www.weibo.com/ and you should see the interface below

1-2 - To create a new account click on

1-3 - You should see the interface below

1-4 - This form uses a cellphone number to activate your account, since some people do not have this, click on the following link to create an account using your email account:

1-5 - Fill the fields in the form
Here's the English translations of these fields:

邮箱: your email address

设置密码: your desired password

昵称: your desired nickname

姓名: your name (not required)

护照: your passport number (not required)

验证码: verification code (type the letters on the image)

Click on the orange button to submit.

If successful, you should see the message below, confirming that an email has been sent to you with the activation code.

1-6 - Access your email account and confirm
You should receive an email with the following contents

Copy the code in your email to your browser (in our case clicking does not seem to work).

1-7 - Input Personal Information
You should be redirected to a page with the form to fill with your personal information
Here's the English translations of these fields(feel free to fill these randomly if you are a non-Mandarin speaker):

昵称: your nickname

性别: your gender (男=male, 女=female)

性感状态: your relationship status (单身=single)

所在地: your location (if you cannot read Mandarin, you are probably not in China, so pick 国外(foreign country) and 美国(USA))

学校: your school (if you cannot read Mandarin, just choose a random one...)

公司: your company (not required)

MSN: your MSN account (not required)

QQ: your QQ account (not required)

Click on the orange button to submit.

If successful, you should be redirected to the page below, to select people to follow. This is not required so click on the yellow button to proceed.

Next, you should be redirected to the following page , to select your interests. It is required to select at least 1 interest. To do this, click on any image you want on the first two rows. You should see a tick over the image, if done correctly. Then, click on the yellow button to proceed.

1-8 - Done! You should be redirected to your account page. Enjoy your account and take pride in being a active member of a community of 368 million users.
Note: if you need to log in, your username will be your email account and password you set in step 1-5.

Go back to the top

2 - Set up Open Weibo Account and Register an Application

To use the API you need the following:

app client ID
app client secret
redirect uri

The goal of this section is to obtain them. There is a good guide here, that explains how to get these, which we fellowed in our work. The problem is that it is in Mandarin and some parts are outdated.

2-1 - Login
Go to http://www.open.weibo.com/ and then click on the link "登录" on the top right corner of the screen. A window should open where you need to input your email and your password. Afterwards, click on the green button to login

2-2 - Basic Info
Next, hover your mouse over your username in the top right of the screen, and choose the first option in the menu that pops.
You should be redirected to an form where you need to fill with your basic information. Again, here are the English translations:

开发这类型: type of account (个人=personal, 公司=company), if you choose company you will need to provide additional information, which we will not cover in this guide.
开发者名称: developer's name

所在地区: your location (if you cannot read Mandarin, you are probably not in China, so pick 国外(foreign country) and 美国(USA))

邮箱: your email address

联系电话: your phone number

聊天工具: your chat tool

网站: your website

Click on the blue button to submit.
You will be prompted to confirm that your email is correct. Make sure it is, since you will be sent an activation email. Then, confirm by clicking on the blue button.
You should see a confirmation message, which says that an email has been sent.
After 5 seconds, you should be redirected to the initial page. Your progress bar on the left part of the screen should be 20% at this point.
2-3 - Confirm Account
Open your email account and you should see an new email.
Copy the link to your browser and you should be redirected to the initial webpage. If successful, the progress bar on the left should say 30% now.
2-4 - Register Application
On the top bar, click on the third button from the left (it should say "应用开发").

Next, click on the green button (创建应用=create application).

A window should pop up asking for the type of application, we will choose the third one from the left(网页应用=web application).

You will need to fill another form with the application's data.
As usual. here are the English translations:

应用名称: your application's name (must be unique)
应用地址: your application's website

应用简介: short description

应用介绍: extended description

域名绑定: fixed domain (not sure what this means, we just set to no(否))

标签: labels (if you do understand the labels, just pick a random one)

我已阅读并接受: I have read the terms and conditions and accept them

After filling the form, click on the left button(创建).

2-5 - Get info to use API
From the last step, you should be redirected to your applications main page. You will be able to find the App Key in our case (in this case 530271774).

To get the App Secret, click the second button on the left menu(应用信息=application information). In our case, it is "172d83f3a8c8e09f7185eec148b02ce8".

To set a Redirect URI, first click on the second button(高级信息=advanced information) in the submenu that should be open now. Then, you should see a bar with the words "OAuth2.0 接权设置". To edit this, click on the button on the right side of that bar(编辑=edit).

You should have to fill the two empty fields with an URL address. In most cases, it does not matter what you choose. The first field(接权回调页) will be your Redirect URI, which is needed to authenticate your application. We set this to https://github.com/wlin12", but any valid URL should be fine.

Congratz! By now you should have the App Key, App Secret and an Redirect URI. This is all you need to start using the Weibo API. Go back to the top

3 - Using the Client API

In this section, we will show examples of the main functionalities of the API. The API itself has too many functionalities to describe them one by one, so we will only focus on the most important ones, such as authenticating to obtain a secret key.

3-1 - About the API
The Weibo API is implemented as a series of Restful Web Services. To call a given service, you need to know the uri location of the service(Ex:"http://api.t.sina.com.cn/statuses/user_timeline.json") and the parameters. The server will reply with a JSON format message. The list of services, input parameters and output parameters are specified in the documentation.
Luckily, there are many client wrappers that allow you to abstract from the details of the communication between the client and server. These can be found here.
3-2 - Authentication The first service that you will need to call is the authentication service in order to get an Access Token. This is done in 2 steps.
First, you need to get an authentication code using the service described here. The service is located at https://api.weibo.com/oauth2/authorize and the parameters are:

client_id - your app key
redirect_uri - your redirect URI
response_type - response type (should be code)

For your convenience, you can test this using the form below. You can use the default parameters of the account we created for this guide, although, I encourage you to test it using your own account.
Note:This will open a new window.

client_id:
redirect_uri:
response_type:

After sending the message, you should see the authentication window below. To authorize, click on the red button(授权=authorize).

You should be redirected to your redirect URI. The authentication code can be found in the url itself as the parameter "code". In our case, we were redirected to "https://github.com/wlin12?code=387f5b11fe2503e45b41addd4bdb5d52". Thus, our authentication code is 387f5b11fe2503e45b41addd4bdb5d52.

With this code, you can get an access token using the service described in here. This service is located at https://api.weibo.com/oauth2/access_token and the parameters we need to use are:

client_id - your app key
client_secret - your app secret
redirect_uri - your redirect URI
grant_type - the type of request, which is set to "authorization_code".
code - the code you obtained in the first step

Once more, you can try this using the following form:
Note:This will open a new window.

client_id:
client_secret:
redirect_uri:
grant_type:
code:

This should open a window, with the following JSON message:

{"access_token":"2.00xusAWD0YuxsZ10f9689fa7sIoHJC","remind_in":"157679999","expires_in":157679999,"uid":"3221452355"}

The access token here would be 2.00xusAWD0YuxsZ10f9689fa7sIoHJC, so congratz! You are officially authenticated. From our experience, this token lasts a long long time, since we haven't authenticated for months.

For more details, the authentication process is described here.
3-3 - Usage Examples
By now, you should be a pro using the API, so we will just show some examples using the API.
First, we will use the public timeline service which retrieves posts in the public domain. We can do this using the service in http://open.weibo.com/wiki/2/statuses/public_timeline/en. The url is https://api.weibo.com/2/statuses/public_timeline.json and the parameters are:

client_id - your app key
access_token - access token obtained after authenticating
page - page number of the results

client_id:
access_token:
page:

The server will respond with a JSON message with the messages, or return an error message describing what went wrong (Ex: if your page number is too large).
One important note is that Weibo rate limits accounts so that only 150 requests can be made per hour. Thus, you might get an 403 error due to rate limiting.
So, please do not use my account information in your web application!

Next, we use show another service, which returns a list of hot posts in a given category. This is described here. The url is https://api.weibo.com/2/suggestions/users/hot.json and the parameters are:

client_id - your app key
access_token - access token obtained after authenticating
category - possible categories:
DEFAULT,ENT,MUSIC,FASHION,LITERATURE,
BUSINESS,SPORT,SPORTS,HEALTH,AUTO,
HOUSE,TRIP,STOCK,FOOD,FATE,ART,TECH,
CARTOON,GAMES,MEDIUM,MARKETER

client_id:
access_token:
category:

This should return a JSON message with the top users of the chosen category and their latest message.
Finally, we will try to return a list of comments for a given post. This is described here. The url is https://api.weibo.com/2/suggestions/users/hot.json and the parameters are:

source - your app key
access_token - access token obtained after authenticating
id - weibo post id
count - number of comments per page
page - page number

source:
access_token:
id:
count:
page:

This should return a JSON message with the a list of comments to the post.
Here are some more random examples:
User Timeline:

source:
access_token:
id:
count:
page:

User Timeline:

source:
access_token:
id:
count:
page:

Timeline Batch:

source:
access_token:
id:
count:
page:

This ends our guide. We hope it was helpful.
If you have any questions feel free to contact us (Wang Ling or Guang Xiang).
Go back to the top

Practical Guide for using Sina Weibo's API
Hi! We are Wang Ling and Guang Xiang from the Language Technologies Institute in Carnegie Mellon University. This is a practical guide for programmers and researchers who intend to use Sina Weibo's Open API as part of their work. We found during our research (description found here) that the current official documentation is unclear and inconsistent in some extent, and in several occasions we had to learn using a trial and error process, which took some time and effort. Thus, we are writing this guide to share what we know and facilitate the usage of this API to new users. This guide is intended for both Mandarin and non-Mandarin speakers. In this guide you will learn to: Create a Sina Weibo Account Set up Open Weibo Account and Register an Application Using the Sina Weibo API
1 - Creating a Sina Weibo Account The first step is to create an Weibo account, this should be relatively straight-forward, but might be hard if you cannot read Mandarin. If thats your case follow the steps below. 1-1 - Go to http://www.weibo.com/ and you should see the interface below 1-2 - To create a new account click on 1-3 - You should see the interface below 1-4 - This form uses a cellphone number to activate your account, since some people do not have this, click on the following link to create an account using your email account: 1-5 - Fill the fields in the form Here's the English translations of these fields: 邮箱: your email address 设置密码: your desired password 昵称: your desired nickname 姓名: your name (not required) 护照: your passport number (not required) 验证码: verification code (type the letters on the image) Click on the orange button to submit. If successful, you should see the message below, confirming that an email has been sent to you with the activation code. 1-6 - Access your email account and confirm You should receive an email with the following contents Copy the code in your email to your browser (in our case clicking does not seem to work). 1-7 - Input Personal Information You should be redirected to a page with the form to fill with your personal information Here's the English translations of these fields(feel free to fill these randomly if you are a non-Mandarin speaker): 昵称: your nickname 性别: your gender (男=male, 女=female) 性感状态: your relationship status (单身=single) 所在地: your location (if you cannot read Mandarin, you are probably not in China, so pick 国外(foreign country) and 美国(USA)) 学校: your school (if you cannot read Mandarin, just choose a random one...) 公司: your company (not required) MSN: your MSN account (not required) QQ: your QQ account (not required) Click on the orange button to submit. If successful, you should be redirected to the page below, to select people to follow. This is not required so click on the yellow button to proceed. Next, you should be redirected to the following page , to select your interests. It is required to select at least 1 interest. To do this, click on any image you want on the first two rows. You should see a tick over the image, if done correctly. Then, click on the yellow button to proceed. 1-8 - Done! You should be redirected to your account page. Enjoy your account and take pride in being a active member of a community of 368 million users. Note: if you need to log in, your username will be your email account and password you set in step 1-5. Go back to the top 2 - Set up Open Weibo Account and Register an Application To use the API you need the following: app client ID app client secret redirect uri The goal of this section is to obtain them. There is a good guide here, that explains how to get these, which we fellowed in our work. The problem is that it is in Mandarin and some parts are outdated. 2-1 - Login Go to http://www.open.weibo.com/ and then click on the link "登录" on the top right corner of the screen. A window should open where you need to input your email and your password. Afterwards, click on the green button to login 2-2 - Basic Info Next, hover your mouse over your username in the top right of the screen, and choose the first option in the menu that pops. You should be redirected to an form where you need to fill with your basic information. Again, here are the English translations: 开发这类型: type of account (个人=personal, 公司=company), if you choose company you will need to provide additional information, which we will not cover in this guide. 开发者名称: developer's name 所在地区: your location (if you cannot read Mandarin, you are probably not in China, so pick 国外(foreign country) and 美国(USA)) 邮箱: your email address 联系电话: your phone number 聊天工具: your chat tool 网站: your website Click on the blue button to submit. You will be prompted to confirm that your email is correct. Make sure it is, since you will be sent an activation email. Then, confirm by clicking on the blue button. You should see a confirmation message, which says that an email has been sent. After 5 seconds, you should be redirected to the initial page. Your progress bar on the left part of the screen should be 20% at this point. 2-3 - Confirm Account Open your email account and you should see an new email. Copy the link to your browser and you should be redirected to the initial webpage. If successful, the progress bar on the left should say 30% now. 2-4 - Register Application On the top bar, click on the third button from the left (it should say "应用开发"). Next, click on the green button (创建应用=create application). A window should pop up asking for the type of application, we will choose the third one from the left(网页应用=web application). You will need to fill another form with the application's data. As usual. here are the English translations: 应用名称: your application's name (must be unique) 应用地址: your application's website 应用简介: short description 应用介绍: extended description 域名绑定: fixed domain (not sure what this means, we just set to no(否)) 标签: labels (if you do understand the labels, just pick a random one) 我已阅读并接受: I have read the terms and conditions and accept them After filling the form, click on the left button(创建). 2-5 - Get info to use API From the last step, you should be redirected to your applications main page. You will be able to find the App Key in our case (in this case 530271774). To get the App Secret, click the second button on the left menu(应用信息=application information). In our case, it is "172d83f3a8c8e09f7185eec148b02ce8". To set a Redirect URI, first click on the second button(高级信息=advanced information) in the submenu that should be open now. Then, you should see a bar with the words "OAuth2.0 接权设置". To edit this, click on the button on the right side of that bar(编辑=edit). You should have to fill the two empty fields with an URL address. In most cases, it does not matter what you choose. The first field(接权回调页) will be your Redirect URI, which is needed to authenticate your application. We set this to https://github.com/wlin12", but any valid URL should be fine. Congratz! By now you should have the App Key, App Secret and an Redirect URI. This is all you need to start using the Weibo API. Go back to the top 3 - Using the Client API In this section, we will show examples of the main functionalities of the API. The API itself has too many functionalities to describe them one by one, so we will only focus on the most important ones, such as authenticating to obtain a secret key. 3-1 - About the API The Weibo API is implemented as a series of Restful Web Services. To call a given service, you need to know the uri location of the service(Ex:"http://api.t.sina.com.cn/statuses/user_timeline.json") and the parameters. The server will reply with a JSON format message. The list of services, input parameters and output parameters are specified in the documentation. Luckily, there are many client wrappers that allow you to abstract from the details of the communication between the client and server. These can be found here. 3-2 - Authentication The first service that you will need to call is the authentication service in order to get an Access Token. This is done in 2 steps. First, you need to get an authentication code using the service described here. The service is located at https://api.weibo.com/oauth2/authorize and the parameters are: client_id - your app key redirect_uri - your redirect URI response_type - response type (should be code) For your convenience, you can test this using the form below. You can use the default parameters of the account we created for this guide, although, I encourage you to test it using your own account. Note:This will open a new window. client_id: redirect_uri: response_type: After sending the message, you should see the authentication window below. To authorize, click on the red button(授权=authorize). You should be redirected to your redirect URI. The authentication code can be found in the url itself as the parameter "code". In our case, we were redirected to "https://github.com/wlin12?code=387f5b11fe2503e45b41addd4bdb5d52". Thus, our authentication code is 387f5b11fe2503e45b41addd4bdb5d52. With this code, you can get an access token using the service described in here. This service is located at https://api.weibo.com/oauth2/access_token and the parameters we need to use are: client_id - your app key client_secret - your app secret redirect_uri - your redirect URI grant_type - the type of request, which is set to "authorization_code". code - the code you obtained in the first step Once more, you can try this using the following form: Note:This will open a new window. client_id: client_secret: redirect_uri: grant_type: code: This should open a window, with the following JSON message: {"access_token":"2.00xusAWD0YuxsZ10f9689fa7sIoHJC","remind_in":"157679999","expires_in":157679999,"uid":"3221452355"} The access token here would be 2.00xusAWD0YuxsZ10f9689fa7sIoHJC, so congratz! You are officially authenticated. From our experience, this token lasts a long long time, since we haven't authenticated for months. For more details, the authentication process is described here. 3-3 - Usage Examples By now, you should be a pro using the API, so we will just show some examples using the API. First, we will use the public timeline service which retrieves posts in the public domain. We can do this using the service in http://open.weibo.com/wiki/2/statuses/public_timeline/en. The url is https://api.weibo.com/2/statuses/public_timeline.json and the parameters are: client_id - your app key access_token - access token obtained after authenticating page - page number of the results client_id: access_token: page: The server will respond with a JSON message with the messages, or return an error message describing what went wrong (Ex: if your page number is too large). One important note is that Weibo rate limits accounts so that only 150 requests can be made per hour. Thus, you might get an 403 error due to rate limiting. So, please do not use my account information in your web application! Next, we use show another service, which returns a list of hot posts in a given category. This is described here. The url is https://api.weibo.com/2/suggestions/users/hot.json and the parameters are: client_id - your app key access_token - access token obtained after authenticating category - possible categories: DEFAULT,ENT,MUSIC,FASHION,LITERATURE, BUSINESS,SPORT,SPORTS,HEALTH,AUTO, HOUSE,TRIP,STOCK,FOOD,FATE,ART,TECH, CARTOON,GAMES,MEDIUM,MARKETER client_id: access_token: category: This should return a JSON message with the top users of the chosen category and their latest message. Finally, we will try to return a list of comments for a given post. This is described here. The url is https://api.weibo.com/2/suggestions/users/hot.json and the parameters are: source - your app key access_token - access token obtained after authenticating id - weibo post id count - number of comments per page page - page number source: access_token: id: count: page: This should return a JSON message with the a list of comments to the post. Here are some more random examples: User Timeline: source: access_token: id: count: page: User Timeline: source: access_token: id: count: page: Timeline Batch: source: access_token: id: count: page: This ends our guide. We hope it was helpful. If you have any questions feel free to contact us (Wang Ling or Guang Xiang). Go back to the top