Hatena::Grouphatenadeveloper

Hatena Timeline Native Retrieval API

en/nano/timeline/nativelist

Hatena Timeline Native Retrieval API

Notice

This is a documentation for an API to extract lists of entries from Hatena Timeline. The API described in this document is experimental; it's format might be changed, or the API might be erased at anytime without announcements. We are considering additions of more developer-friendly APIs for purposes. Inputs from developers are welcome.

Overview

Hatena Timeline Native Retrieval API is an OAuth-based RESTful API. By accessing a URL using HTTP GET method, you can retrieve a list of timeline entries in a form similar to Hatena's internal storage format.

Authentication

The API supports OAuth-based user authentication. You can obtain Consumer Keys for the OAuth access from the Access Hatena services with OAuth section in your User Settings. There is a tutorial document はてなサービスにおける OAuth (available only in Japanese at the time of writing, but sample codes are also included there).

The scope read_private is required for all operations in the API.

Retrieval

Timeline entries can be retrieved by accessing the URL below using the HTTP GET method:

http://n.hatena.ne.jp/timeline.json

Note that future revision of this API might replace the URL scheme into https.

Parameters in HTTP requests

The following parameter can be included in the query component of the request URL in the application/x-www-form-urlencoded format:

Parameter nameParameter value#
locationHatena service0-1
pageDeprecated Page number0-1
per_pageMaximum number of entries0-1 (Auto if omitted)
reftimeDate-time range0-1 (Auto if omitted)

Not all entries can be retrieved using this API; Old entries can be expired.

For the reftime parameter, you can specify a string consist of sign, time, and offset (e.g. -1314803385,1). The sign component + represents newer, while - represents older. Time and offset components identify the reference point to retrieve entries. The offsetth entry before or after the specified time and subsequent entries are retrieved. Time can be specified by so-called Unix time format. The reftime parameter should always be specified explicitly. To retrieve latest entries, specify -time,0, where time represents the current timestamp.

Deprecated The page parameter has historically been used to specify the range of retrieval using page number. It should not be used any more. If the location parameter is set to http://c.hatena.ne.jp/ (or the parameter is omitted), the default page value is 1. Otherwise, the default is not specified. If the page parameter is specified, other parameters might be ignored.

The location parameter can take one of following values:

http://c.hatena.ne.jp/ Hatena Coco (Friend Update)
http://h.hatena.ne.jp/ Hatena Haiku (Antenna)

HTTP responses

If the retrieval has succeeded, a 200 (OK) response is returned with JSON data described in the next section.

If the retrieval has failed, an error response such as 400 (Bad Request) or 401 (Authorization Required) is returned.

JSON response data

Returned JSON data is an object with following members:

NameValue semanticsType of value
has_next (If page is specified)Deprecated Whether there is the next page or notboolean
itemsList of entries in the timelineArray
newer_url (If reftime is specified)The URL to retrieve newer entriesString
older_url (If reftime is specified)The URL to retrieve older entriesURL
page (If page is specified)Deprecated Page numberNumber

Entries

Each object in the items array represents an entry, containing following members;

NameValue semanticsType of value
app_icon_urlApplication icon URLURL
app_logo_urlApplication logo URLURL
app_nameApplication nameString
app_urlApplication URLString
authorEntry authorTarget
body_diary_textBody text (In Hatena Diary's Hatena Notation)String
body_haiku_textBody text (In Hatena Haiku's Hatena Notation)String
body_textBody textString
created_onTimestampDatetime
data_categoryEntry typeNumber
eidEntry unique IDNumber
entity1Obsolete Related user 1Target
entity2Obsolete Related user 2Target
mono_keyProduct IDAlphanumeric string
photo_urlPhoto URLURL
photo_small_urlPhoto thumbnail URLURL
question_summary_textSummary of questionString
question_urlQuestion page URLURL
reply_to_authorAuthor of the parent entryTarget
reply_to_eidEntry ID of the parent entryNumber
source_targetSource applicationTarget
spot_review_scoreSpot review scoreNumber
star_urlPermalink URLURL
summary_textSummaryString
targetTarget (Spot for checkins and reviews)Target

Members other than eid, data_category, created_on, and star_url can be omitted if they have no value.

More members might be added in future.

Targets

Values of author, target, and similar members are objects with following members:

NameValue semanticsType of value
url_nameIdentifier (as used in URLs)String
display_nameNickname, spot name, or as suchString

If url_name contains no @ character, it represents a Hatena ID. Otherwise, it represents an entity that is not a Hatena User.

These members can be omitted if they have no value. More members might be added in future.

Entry types

Typical data_category values include:

ValueDescription
1Comment (Old format)
2Text (Open to Hatena Users, Old format)
3Obsolete "Become friend" notice
10Checkin in Hatena Coco
11Spot review in Hatena Coco
14Text (Open to everyone, Old format)
15Text (Open to Hatena Haiku2 users, Old format)
16Text (Open to friends and friends of a friend, Old format)
17Text (Open to friends, Old format)
19Text (Open to specified users)
20Text (Permission is determined by user configuration)
30Comment in HatenaOne
31Modification of Happie
43Notice of application installation
45Notice of Hatena Plus application
50Flipnote in Flipnote Hatena
62Entry in Hatena Haiku
70Reply to an answer in Hatena Question
75Question in Hatena Question
76Answer to a question in Hatena Question
77Comment to a question in Hatena Question
78Addition to the watch list in Hatena Question
79Enquete in Hatena Question
80Answer to an enquete in Hatena Question
85Friendship notification
87Bookmark in Hatena Bookmark
89Photo/video in Hatena Fotolife
95Comment to a checkin in Hatena Coco
97Entry in Hatena Blog
112Entry in Hatena Diary

More entry types might be added in future.

More notes

For boolean, false is represented by one of null, 0, or "0"; True is represented by any other value.

For number, the value is represented by a number or the string representation of the number.

Datetime is represented by a number in the so-called Unix time format.

Examples

GET /timeline.json?reftime=-123456890,1 HTTP/1.1
Host: n.hatena.com
Authorization: OAuth ...
User-Agent: ExampleUserAgent/1.0

HTTP/1.1 200 OK
Content-Type: application/json

{
  "older_url": "http://...",
  "newer_url": "http://...",
  "items": [
    {
      "eid": "25152122414212111",
      "star_url": "http://n.hatena.ne.jp/...",
      ...
    },
    ...
  ]
}

Changes

  • February 1, 2012 Added new data_categorys.
  • February 13, 2012 Added a new data_category.
  • October 1, 2012 Deleted HatenaOne.