Hatena::Grouphatenadeveloper

Hatena Haiku Timeline APIs

en/haiku/apis/rest/timelines

Hatena Haiku Timeline APIs

Notice on this document

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

Overview of Timeline APIs

A timeline is a list of zero or more entries. Hatena Haiku Timeline APIs provide access to various kinds of timelines:

NameCorresponding page in Hatena Haiku Web site
statuses/public_timelineHatena Haiku Top page
statuses/keyword_timelineEntries page of a keyword
statuses/user_timelineEntries page of a user
statuses/friends_timelineAntenna page of a user
statuses/albumAlbum page of a keyword or the entire service

Common parameters

APIs described in this document accept following parameters in the query component of the request URL:

Parameter nameDescriptionDatatype#
countNumber of entries to retrieve. The maximum value is 200. Assumed as 20 if missing.NumberAt most one (1)
pageNumber of the page to retrieve. The first page is 1. Assumed as 1 if missing. The maximum value is 100.NumberAt most one (1)
sinceThe date and time interrupting retrieval. Entries older than this date and time would not be included in the result. If missing, all entries that satisfy other conditions are included.HTTP datetimeAt most one (1)
sortSort order of entries. Specify new for New entries, or hot for Hot entries. This parameter can only be specified for timelines whose Hot entries mode is available on the Hatena Haiku Web site. Assumed as new if missing. At most one (1)

statuses/public_timeline

Returns the most recent entries posted to non-user keywords, as shown in http://h.hatena.com/ and http://h.hatena.ne.jp/ (Top pages).

URL

http://{domain}/api/statuses/public_timeline.{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 body_formats, count, page, since

Result

If succeeded, it returns the Array of Entry objects.

statuses/friends_timeline

Returns the most recent entries posted by the authenticating user's, or specified user's favorite users and keywords. It is corresponding to http://h.hatena.com/following and http://h.hatena.ne.jp/following (Antenna pages).

URL

http://{domain}/api/statuses/friends_timeline.{format}?{parameters}
http://{domain}/api/statuses/friends_timeline/{url_name}.{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&....
{url_name}The Hatena ID of the user whose timeline is retrieved.

Authentication

If the URL contains {url_name}, authentication is unnecessary.

If the URL does not contain {url_name}, OAuth (read_public scope) or Basic authentication is REQUIRED.

Method

Use the HTTP GET method.

Parameters

Following parameters are available: callback, count, page, since, New in Hatena Haiku 1.1 body_formats

Result

If succeeded, it returns the Array of Entry objects.

statuses/user_timeline

Returns the most recent entries posted by the authenticating user, or the specified user. It is corresponding to http://h.hatena.com/{username}/ or http://h.hatena.ne.jp/{username}/ (user's Entries page).

URL

http://{domain}/api/statuses/user_timeline.{format}?{parameters}
http://{domain}/api/statuses/user_timeline/{url_name}.{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&....
{url_name}The Hatena ID of the user whose timeline is retrieved.

Authentication

If the URL contains {url_name}, authentication is unnecessary.

If the URL does not contain {url_name}, OAuth (read_public scope) or Basic authentication is REQUIRED.

Method

Use the HTTP GET method.

Parameters

Following parameters are available: callback, count, page, since, New in Hatena Haiku 1.1 body_formats, media, sort

The media parameter accepts either default or album. If default is specified, all kinds of entries are included; If album is specified, only entries that contain images are included. The default value for the parameter is default.

Result

If succeeded, it returns the Array of Entry objects.

statuses/keyword_timeline

Returns the most recent entries posted to the specified keyword. It is corresponding to http://h.hatena.com/keyword/{keyword}/, http://h.hatena.ne.jp/keyword/{keyword}/, or other keyword's Entries pages.

URL

http://{domain}/api/statuses/keyword_timeline.{format}?{parameters}
http://{domain}/api/statuses/keyword_timeline/{keyword}.{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&....
{keyword}Deprecated The word of the keyword whose timeline is retrieved. 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, count, page, since, New in Hatena Haiku 1.1 body_formats, sort, word

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

Result

If succeeded, it returns the Array of Entry objects.

statuses/album

Returns the most recent entries containing images. It is corresponding http://h.hatena.com/album and http://h.hatena.ne.jp/album and other album pages.

URL

http://{domain}/api/statuses/album.{format}?{parameters}
http://{domain}/api/statuses/album/{keyword}.{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&....
{keyword}Deprecated The word of the keyword whose timeline is retrieved. 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 body_formats, count, page, since, sort, word

If the URL does not contain {keyword} and there is no word parameter specified, image entries from the entire service is returned.

Result

If succeeded, it returns the Array of Entry objects.

Examples

GET http://h.hatena.com/api/statuses/public_timeline.xml

<statuses type="array">
  <status>
    <id>12345678901234</id>
    <created_at>2008-08-19T00:00:00Z</created_at>
    <favorited>0</favorited>
    <in_reply_to_status_id>98765432109876</in_reply_to_status_id>
    <in_reply_to_user_id>jkondo</in_reply_to_user_id>

    <keyword>Hatena Default-san</keyword>
    <link>http://h.hatena.com/jkondo/12345678901234</link>
    <source>web</source>
    <text>Hatena Default-san=Hi, you are very cute!</text>
    <user>
      <name>jkondo</name>
      <followers_count>1</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>
  </status>
  <!-- ... -->
</statuses>

GET http://h.hatena.com/api/statuses/public_timeline.json

[
   {
      "keyword" : "Hatena Default-san",
      "source" : "web",
      "link" : "http://h.hatena.com/jkondo/12345678901234",
      "favorited" : 0,
      "created_at" : "2008-08-19T00:00:00Z",
      "text" : "Hatena Default-san=Hi, you are very cute!",
      "in_reply_to_user_id" : "jkondo",
      "user" : {
         "followers_count" : 1,
         "name" : "jkondo",
         "url" : "http://h.hatena.com/jkondo/",
         "profile_image_url" : "http://www.hatena.ne.jp/users/jk/jkondo/profile.gif",
         "id" : "jkondo",
         "screen_name" : "jkondo"
      },
      "id" : "12345678901234",
      "in_reply_to_status_id" : "98765432109876"
   },
   ...
]

Related documents

Hatena Haiku RSS feeds
Timelines can also be retrieved as RSS feeds.

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.