Hatena::Grouphatenadeveloper

Hatena Haiku User and Keyword APIs

en/haiku/apis/rest/targets

Hatena Haiku User and Keyword APIs

Notice on this document

This document is part of the Hatena Haiku RESTful APIs documentation.

Overview of User and Keyword APIs

Hatena Haiku User and Keyword APIs can be used to retrieve or modify users and keywords.

NameOpetation
friendships/showRetrieve user data
keywords/showRetrieve keyword data
keywords/hotRetrieve the list of Hot Keywords
keywords/listSearch for keywords
keywords/relation/createAssociate two keywords as related
keywords/relation/destroyDisassociate a pair of related keywords

The word parameter

New in Hatena Haiku 1.1

For APIs retrieving or modifying a keyword, the word of the keyword MUST be specified by including the {keyword} part in the request URL or by specifying the word parameter. As the former does not always work as intended, the latter way, i.e. specifying the word parameter is RECOMMENDED.

friendships/show

Return the data of the specified user.

URL

http://{domain}/api/friendships/show/{url_name}.{format}?{parameters}
{domain}Hatena Haiku domain name; h.hatena.ne.jp or h.hatena.com, as you like.
{format}Format of the result; json or xml.
{eid}The ID of the entry.
{url_name}The Hatena ID of the user.
{parameters}Parameters in the form name1=value1&name2=value2&....

Authentication

Authentication is unnecessary.

Method

Use the HTTP GET method.

Parameters

Following parameters are available: callback

Result

If succeeded, the User object for the specified user is returned.

keywords/show

Return the data of the specified keyword.

URL

http://{domain}/api/keywords/show.{format}?{parameters}
http://{domain}/api/keywords/show/{keyword}.{format}?{parameters} (Deprecated)
{domain}Hatena Haiku domain name; h.hatena.ne.jp or h.hatena.com, as you like.
{format}Format of the result; json or xml.
{eid}The ID of the entry.
{parameters}Parameters in the form name1=value1&name2=value2&....
{keyword}Deprecated The word of the keyword. It is encouraged to specify the word parameter instead.

Authentication

Authentication is unnecessary.

Method

Use the HTTP GET method.

Parameters

Following parameters are available: callback, New in Hatena Haiku 1.1 without_related_keywords, word

If the URL does not contain {keyword}, the parameter word MUST be specified.

If you are not intended to retrieve related keywords of the keyword, you are advised to specify a true value to the parameter without_related_keywords.

Result

If succeeded, the Keyword object is returned.

keywords/list

Returns the list of the keyword, which is corresponding to http://h.hatena.com/keywords and http://h.hatena.ne,jp/keywords in the Web site. It can also be used to search for keywords.

URL

http://{domain}/api/keywords/list.{format}?{parameters}
{domain}Hatena Haiku domain name; h.hatena.ne.jp for Japanese version, h.hatena.com for global version.
{format}Format of the result; json or xml.
{parameters}Parameters in the form name1=value1&name2=value2&....

Authentication

Authentication is unnecessary.

Method

Use the HTTP GET method.

Parameters

Following parameters are available: callback, page, New in Hatena Haiku 1.1 without_related_keywords, word

If the parameter word is specified, its value is used as the search query. If missing, the list of keywords shown in the Top page of the Hatena Haiku Web site.

The parameter page specifies the number of page to return. The maximum value is 100.

If you are not intended to retrieve related keywords of the keyword, you are advised to specify a true value to the parameter without_related_keywords.

Result

If succeeded, the array of Keyword objects is returned.

keywords/hot

Return the list of Hot Keywords, as shown in http://h.hatena.com/hotkeywords or http://h.hatena.ne.jp/hotkeywords in the Web site.

URL

http://{domain}/api/keywords/hot.{format}?{parameters}
{domain}Hatena Haiku domain name; h.hatena.ne.jp for Japanese version, h.hatena.com for global version.
{format}Format of the result; json or xml.
{parameters}Parameters in the form name1=value1&name2=value2&....

Authentication

Authentication is unnecessary.

Method

Use the HTTP GET method.

Parameters

Following parameters are available: callback, New in Hatena Haiku 1.1 without_related_keywords

If you are not intended to retrieve related keywords of the keyword, you are advised to specify a true value to the parameter without_related_keywords.

Result

If succeeded, the array of Keyword objects is returned.

keywords/relation/create

Associate two keywords as a pair of related keywords.

URL

http://{domain}/api/keywords/relation/create.{format}?{parameters}
{domain}Hatena Haiku domain name; h.hatena.ne.jp or h.hatena.com, as you like.
{format}Format of the result; json or xml.
{parameters}Parameters in the form name1=value1&name2=value2&....

Authentication

OAuth (write_public scope) or Basic authentication is REQUIRED.

Method

Use the HTTP POST method.

Parameters

Following parameters are available: callback, word1, word2, New in Hatena Haiku 1.1 without_related_keywords

Specify the word of two associated keywords in the parameters word1 and word2. These parameters are REQUIRED.

If you are not intended to retrieve related keywords of the keyword in the result data, you are advised to specify a true value to the parameter without_related_keywords.

Result

If succeeded, the Keyword object for the keyword specified by the parameter word1 is returned.

keywords/relation/destroy

Disassociate a pair of related keywords. Related keywords can be disassociated by whom associated the keywords or, if one of them is the user keyword, the user.

URL

http://{domain}/api/keywords/relation/destroy.{format}?{parameters}
{domain}Hatena Haiku domain name; h.hatena.ne.jp or h.hatena.com, as you like.
{format}Format of the result; json or xml.
{parameters}Parameters in the form name1=value1&name2=value2&....

Authentication

OAuth (write_public scope) or Basic authentication is REQUIRED.

Method

Use the HTTP POST method.

Parameters

Following parameters are available: callback, word1, word2, New in Hatena Haiku 1.1 without_related_keywords

Specify the word of two disassociated keywords in the parameters word1 and word2. These parameters are REQUIRED.

If you are not intended to retrieve related keywords of the keyword in the result data, you are advised to specify a true value to the parameter without_related_keywords.

Result

If succeeded, the Keyword object for the keyword specified by the parameter word1 is returned.

Examples

GET http://h.hatena.com/api/friendships/show/jkondo.xml

<user>
  <name>jkondo</name>
  <followers_count>3</followers_count>
  <id>jkondo</id>
  <profile_image_url>http://www.hatena.ne.jp/users/jk/jkondo/profile.gif</profile_image_url>
  <screen_name>jkondo</screen_name>

  <url>http://h.hatena.com/jkondo/</url>
</user>

GET http://h.hatena.com/api/friendships/show/jkondo.json

{
   "followers_count" : 3,
   "url" : "http://h.hatena.com/jkondo/",
   "profile_image_url" : "http://www.hatena.ne.jp/users/jk/jkondo/profile.gif",
   "name" : "jkondo",
   "id" : "jkondo",
   "screen_name" : "jkondo"
}

History

  • December 13, 2010 Republished in Hatena Developer Center.
  • December 24, 2010 Added new features in Hatena Haiku 1.1 Beta.
  • February 14, 2011 Added new features in Hatena Haiku 1.1.