Hatena::Grouphatenadeveloper

はてなココイマココ API 第1版

ja/coco/apis/v1/heres

はてなココイマココ API 第1版

はてなココは2014年7月1日をもってサービスを終了しました。この文書に記載のAPIは現在利用できません。長らくのご愛顧ありがとうございました。

本ドキュメントに関する注意事項

本ドキュメントははてなココのイマココについての操作を行う API について解説するものです。

はてなココイマココ API 第1版の概要

はてなココイマココ API 第1版は、 OAuth 認証を利用した API です。 HTTP の GET や POST を特定の URL に対して行うことで、はてなココのイマココの情報の取得や設定を行えます。

認証

本 API は OAuth によるユーザー認証に対応しています。 OAuth 認証の詳細に関しては、はてなサービスにおける OAuth を参照してください。

イマココの情報の取得には read_private 操作、イマココの投稿には write_private 操作の承認を得ている必要があります。

イマココ投稿 (/api/v1/checkin.json)

指定したスポットにたいしてイマココを投稿することができます。

認証

この API は write_private 権限の OAuth 認証を使って利用できます。認証は必須です。

リクエスト

以下のURLに対して HTTP POSTリクエストを発行します。

http://c.hatena.com/api/v1/checkin.json

HTTP 要求の本体 (body) には次の引数を application/x-www-form-urlencoded 形式、もしくはmultipart/form-data形式で含める必要があります。画像を含める場合multipart/form-data形式である必要があります。また、テキストは UTF-8 で符号化された文字列でなければなりません。

引数名引数値省略した時の値
key(必須)スポットのキー(文字列)省略不可
bodyイマココに含めるひとことなし
twitterイマココをtwitterへ投稿(0か1)0(投稿しない)
mixiイマココをmixiへ投稿(0か1)0(投稿しない)
photos画像データなし

レスポンス

リクエストが成功すると以下のようなjson形式のデータが含まれたレスポンスが返却されます。

{
    "checkin": {
        "id": 123456789,
        "created": '2010-01-01T00:00:00+09:00',
        "spot": {    // イマココしたスポットの情報
            "key": "1234567abcde",
            "name": "スポット名",
            "geolat": "35",
            "geolong": "135",
            "private": 0    // ひみつスポットかどうか
        },
        "user": {
            "user_id": 'dummy',
            "nickname": 'だみーさん',
            "profile_icon": 'http://www.st-hatena.com/users/du/dummy/profile.gif'
        },
        "body": "イマココしました",
        "photos": [
            {
                "original":"http://img.f.hatena.ne.jp/images/fotolife/p/path/to/original.jpg", // オリジナル画像URL
                "decorated":"http://img.f.hatena.ne.jp/images/fotolife/p/path/to/decorated..jpg" // ハッピィが移りこんだ画像
                "decorated_thumbnail":"http://img.f.hatena.ne.jp/images/fotolife/p/path/to;decorated_thumb.jpg", // ハッピィが移りこんだサムネイル画像URL
            },
            ...
        ],
        "can_comment": 1,       // そのイマココに認証ユーザーがコメントできるかどうか
        "cococoins": [          // イマココにより取得したコインの枚数とその理由
            {
                "count": 2,
                "reason": "はじめてイマココしました",
            },
        ],
    }
}

注意

APIによるイマココでは、ラリーのクリアはできません。


イマココ履歴取得 (/api/v1/history.json)

特定のともだちのイマココ履歴を取得することができます。

認証

この API は read_private 権限の OAuth 認証を使って利用できます。認証は必須です。

リクエスト

以下のURLに対して HTTP GET リクエストを発行します。

http://c.hatena.com/api/v1/history.json

URL の query 部分に次の引数を application/x-www-form-urlencoded 形式で含める必要があります。また、テキストは UTF-8 で符号化された文字列でなければなりません。

引数名引数値省略した時の値(最大値)
name(必須)対象ユーザーのはてなid(文字列)省略不可
l最大取得件数25(50)
page取得するページ(数値)0(50)

レスポンス

リクエストが成功すると以下のようなjson形式のデータが含まれたレスポンスが返却されます。

{"checkins": [
    {
        "id": "12345678",
        "created": "2010-01-01T00:00:00+09: 00",
        "spot": {
            "name": "スポット名",
            "key": "1234567abcde",
            "owner_hatena_id": "dummy",
            "geolat": "35",
            "geolong": "135",
            "rating": "3.5",   // レビューの平均評価
            "image_url": "http://img.f.hatena.ne.jp/images/fotolife/p/path/to/image.jpg", // そのスポットのアイコン画像
            "private": 0,
            "checkinable_for_friends": 1,
            "total_checkin_count": "10",
            "primarycategory": {
                "fullpathname": "ビル・建物/会社・事業所",
                "icon_url": "http: //c.hatena.ne.jp/images/category/icon-town-company.png",
                "nodename": "会社・事業所",
                "id": "27"
            }
        },
        "user": {
            "nickname": "ダミー",
            "profile_icon": "http: //www.st-hatena.com/users/da/dummy/happie_face.gif",
            "user_id": "dummy"
        },
        "body": "イマココしました",
        "comments": [           // そのイマココに付いているコメント
            {
                "created": "2010-01-01T00:10:00+09: 00",
                "body": "テストのコメント!",
                "user": {
                    "nickname": "ダミー",
                    "profile_icon": "http: //www.st-hatena.com/users/d/dummy/profile.gif",
                    "user_id": "dummy"
                }
            },
            ...
        ],
        "can_comment": 1,
        "rallies": [             // そのイマココで達成したラリー一覧
            {
                "id": 123456789,
                "name": 'ダミーラリー',
                "target_spot_count": 10,
                "stamped_spot_count": 5,
            }
        ],
    },
    ...
]
}

ともだちイマココ取得 (/api/v1/checkins.json)

ともだちのイマココ履歴を取得することができます。

認証

この API は read_private 権限の OAuth 認証を使って利用できます。認証は必須です。

リクエスト

以下のURLに対して HTTP GET リクエストを発行します。

http://c.hatena.com/api/v1/checkins.json

URL の query 部分に次の引数を application/x-www-form-urlencoded 形式で含める必要があります。また、テキストは UTF-8 で符号化された文字列でなければなりません。



引数名引数値省略した時の値(最大値)
l最大取得件数25(50)
page取得するページ(数値)0(50)

レスポンス

レスポンスの形式は上記イマココ履歴取得APIと同じです。

エラーレスポンス

はてなココイマココAPIに対して不正な操作を行った場合にはエラーレスポンスが返却されます。各エラーレスポンスには次のような意味があります。

400 (Bad Request)
リクエストが不正な時に返却されます。リクエストの引数を確認してください。
401 (Authorization Required)
認証が必要な処理を認証せずに行なった時に返却されます。
403 (Forbidden)
アクセス権のないリソースへのリクエストを行った時に返却されます。対象リソースにアクセス権限があるかどうか確認してください。
404 (Not Found)
存在しないリソースへのリクエストを行った時に返却されます。URLを確認してください。
405 (Method Not Allowed)
リソースに対して許可されないメソッドでリクエストを行ったときに返却されます。
500 (Internal Server Error)
はてなココスポットAPI側で何らかの問題が発生した時に返却されます。

その他のレスポンスコードが返却された場合は HTTP1.1の仕様に準拠します。

変更履歴

  • 2010年12月13日 API 仕様を公開