Hatena::Grouphatenadeveloper

はてなココスポット API 第1版

ja/coco/apis/v1/spots

はてなココスポット API 第1版

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

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

本ドキュメントははてなココのスポット及びカテゴリーについての操作を行う API について解説するものです。

はてなココスポット API 第1版の概要

はてなココスポット API 第1版は、 OAuth 認証を利用した API です。 HTTP の GET や POST を特定の URL に対して行うことで、はてなココのスポットやカテゴリーの情報を取得したり、設定したりできます。

認証

本 API は OAuth によるユーザー認証に対応しています。 OAuth 認証の詳細に関しては、はてなのOAuthを利用する方法を参照してください。

スポット、及びカテゴリーの情報の取得には read_public 操作、スポットの作成や情報の変更には write_public 操作の承認を得ている必要があります。


スポット検索 (/api/v1/spots.json)

位置座標を元にスポットを検索してその情報を取得できます。

認証

この API は read_public 権限の OAuth 認証を使って利用できますが、 OAuth 認証無しでも利用できます。

認証されていると、そのユーザーのよく行くスポット情報、及び各スポットに関するそのユーザーの情報(スポットへのイマココ回数など)が取得できます。

リクエスト

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

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

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

引数名引数値省略した時の値(最大値)
geolat(必須)緯度 (度単位の実数)省略不可
geolong(必須)経度 (度単位の実数)省略不可
lよく行くスポット/近くのスポットそれぞれの最大取得件数25(50)
page取得するページ(数値)0(50)
present_geolatユーザーの現在緯度(度単位の実数)0
present_geolongユーザーの現在軽度(度単位の実数)0
q検索したい文字列指定なし

レスポンス

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

{ "groups": [
    { 
         "type": "Nearby", // 近くのスポット
         "spots": [
             { 
               "name": "スポット名",
               "key": "123456abcde",             // スポットを一意に識別するキー
               "owner_hatena_id": "dummy",       // スポット作成者のはてなid
               "geolat": "35",
               "geolong": "135",
               "rating": "3.5",                  // レビューのレーティングの平均値
               "image_url": "http: //img.f.hatena.ne.jp/images/fotolife/p/path/to/image.jpg",
               "distance": 4,                    // 現在位置からの距離(単位はm)
               "private": 0,
               "checkinable_for_friends": 1,     // ともだちもイマココ可能かどうか
               "total_checkin_count": 13         // いままでイマココされた回数
               "primarycategory": {              // カテゴリー情報
                   "fullpathname": "交通",       // 親カテゴリ名/子カテゴリ名
                   "icon_url": "http://c.hatena.ne.jp/images/category/icon-transport.png",    // カテゴリアイコンURL
                   "nodename": "交通",           // カテゴリ名
                   "id": "41" },
               "stats": {                        // そのスポットに関するユーザー固有の情報(認証時のみ)
                   "checkin_count": 0            // 認証ユーザーがそのスポットにイマココした回数
               },
               "rallies": [                      // そのスポットを登録しているラリー情報
                 { "name": "テストラリー",
                   "target_spot_count": "10",    // そのラリーに登録されているスポットの数
                   "id": "123456789"
                }],
             },
             ...
         ]
    },
    { 
         "type": "Nearby Favorites" // よく行くスポット(認証時のみ)
         "spots": [
            ...    // 近くのスポットのの"spots"と同じ形式
         ]
    }
]
}

スポット作成 (/api/v1/addspot.json)

新規スポットを作成することができます。

認証

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

リクエスト

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

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

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

引数名引数値省略した時の値
geolat(必須)緯度 (度単位の実数)省略不可
geolong(必須)経度 (度単位の実数)省略不可
name(必須)スポット名省略不可
primarycategoryid(必須)カテゴリのid(数値)省略不可
privateひみつスポットかどうか(0か1)0(公開スポット)
checkinable_for_friendsひみつスポットとするとき、ともだちはイマココできるようにするかどうか(0か1)0(ともだちもイマココ不可)

レスポンス

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

{
    "name": "スポット名",
    "key": "123456abcde",          // スポットを一意に識別するキー
    "owner_hatena_id": "dummy",    // スポット作成者のはてなid
    "geolat": "35",
    "geolong": "135",
    "rating": "3.5",               // レビューのレーティングの平均値
    "image_url": "http: //img.f.hatena.ne.jp/images/fotolife/p/pondelion232/20100813/20100813120553.jpg",
    "private": 0,
    "checkinable_for_friends": 1,  // ともだちもイマココ可能かどうか
    "primarycategory": {           // カテゴリー情報
        "fullpathname": "交通",    // 親カテゴリ名/子カテゴリ名
        "icon_url": "http://c.hatena.ne.jp/images/category/icon-transport.png",   // カテゴリアイコンURL
        "nodename": "交通",        // カテゴリ名
        "id": "41" },
}

カテゴリー情報取得 (/api/v1/categories.json)

はてなココにおける全カテゴリー情報を取得できます。

認証

この API は read_public 権限の OAuth 認証を使って利用できますが、 OAuth 認証無しでも利用できます。

リクエスト

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

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

レスポンス

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

{
    "categories": [
        { "icon_url": "http://c.hatena.ne.jp/images/category/icon-gourmet.png",
          "name": "グルメ",
          "id": "10",
          "is_root": 1 },    // 親カテゴリの有無
        { "icon_url": "http://c.hatena.ne.jp/images/category/icon-gourmet-restaurant.png",
          "name": "食堂・レストラン",
          "id": "12",
          "parent_id": "10",
          "is_root": 0 },
        ...
    ]
}

カテゴリーアイコン デザイン素材

はてなココで利用されている、カテゴリーアイコンの元データ(イラストレータCS形式、EPS形式)を自由に利用できるデザイン素材としてクリエイティブ・コモンズ・ライセンスで公開します。はてなココのAPIを使ったウェブサービス開発はもちろん、それ以外の用途としてのご利用も可能です。

ライセンス

カテゴリーアイコン デザイン素材は『クリエイティブ・コモンズ 表示 2.1 日本 ライセンス』に基づいて、無償、かつ自由にご利用いただけます。ライセンスの詳細については、クリエイティブ・コモンズのウェブサイトをご覧ください。

クリエイティブ・コモンズ・ライセンスこの 作品 は クリエイティブ・コモンズ 表示 2.1 日本 ライセンスの下に提供されています。

クリエイティブ・コモンズについては以下のサイトを参照してください。
http://creativecommons.jp/faq

ダウンロード

101215coco-category-icon.zip(3.12MB)

エラーレスポンス

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

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

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

関連ドキュメント

次の2つの API は、本ドキュメントで説明した API と同様にスポット検索の結果を返すものですが、より簡潔な JSON データを取得できます。

変更履歴

  • 2010年12月13日 API 仕様を公開
  • 2010年12月15日 カテゴリーアイコンデザイン素材を追加