ご当地キャラカタログAPI

概要

はじめに

  • ご当地キャラカタログAPIは、ソフトウェアの開発者が「ご当地キャラカタログ」の各種データにアクセスできるようにするためのサービスです。
    ご当地キャラカタログに登録された「ご当地キャラ」「イベント」「スポット」の各情報を検索・取得することが可能です。

API活用事例

Mashup Awards

注意事項

  • 当サイトのデータの使用にあたっては、利用規約を必ずお読み頂き、その内容を承諾した上でご利用下さい。
  • 現時点では、ご当地キャラカタログにログインが必要な機能（キャラへのコメント、評価、未確認キャラの投稿など）はAPIでは提供されていません。
  • 「ご当地キャラカタログAPI」は、現在ベータ版として公開しております。APIの確実な動作を保証するものではなく、仕様は今後変更される可能性があります。
  • APIについて質問や要望がありましたら、TINAMIの「APIに関する質問スレッド」までお願いします。

APIキーの取得について

  • ご当地キャラカタログAPIへアクセスするためには、TINAMIのAPIキーが必要になります。
    TINAMI、あるいはご当地キャラカタログのアカウントを使ってTINAMIにログインし、APIキーを取得して下さい。
  • APIキー申請フォームへ(TINAMIへ移動します)

アクセスポイントについて

  • リクエストは、http://localchara.jp/services/api/ に対して行います。
    （http://localchara.jp/api/ ではないので注意して下さい）
  • ※https://localchara.jp/services/api/ に対してリクエストをすることで、HTTPSによるアクセスが可能になりました。
    HTTPSでリクエストを行った場合、レスポンスに含まれるご当地キャラカタログ内のリソース（image, sourceなど）のURLもhttpsになります。

リクエストとレスポンスの仕様

  • 文字コードは入出力ともUTF-8です。
  • リクエストはGETメソッドで呼び出します。
  • 緯度・経度の座標は、世界測地系を使用します。
  • レスポンスはJSON型式の文字列です。Unicode文字は、"\uXXXX" の型式にエスケープされます。
  • 何らかのエラーが発生した場合、レスポンスの error 項目に true が入り、message にエラーメッセージが設定されます（全API共通）。
  • APIの呼び出し回数は、現在は90分間で180回までに制限させて頂きます。それ以上のペースで呼び出した場合はエラーを返します。

リクエスト例

  • http://localchara.jp/services/api/search/location/character?api_key=(取得したAPIキー)&ll=35.276452,136.251846

レスポンス例

成功時
  • {"total":141,"offset":0,"count":20,"result":[ {"id":2746,"name":"ひこにゃん","profile":"彦根藩二代藩主である井伊直孝公を…", … "source":"http://localchara.jp/catalog/2746"}, {"id":4093,"name":"ぎんにゃん","profile":"ぎんにゃんは２００９年、生徒から…", … "source":"http://localchara.jp/catalog/4093"}, ],"rate":179}
失敗時
  • {"error":true,"message":"APIキーが指定されていないか、値が不正です"}

位置検索

/search/location/character (位置情報からキャラクターを検索)
/search/location/event (位置情報からイベントを検索)
/search/location/spot (位置情報からスポットを検索)

  • それぞれ、緯度・経度を基点とした座標の周囲に登録されているキャラクター情報、イベント情報、スポット情報を検索します。
  • result項目のソート順は、全てリクエスト引数で渡された緯度経度に近い順です。

リクエスト引数（共通）

api_keyAPIキー。必須
ll「緯度,経度」の形の文字列を指定。必須
range取得範囲(m)。デフォルトは10km(10000)。範囲は0〜50km(50000)まで指定可能
offset取得件数開始位置。デフォルトは0（先頭から）
counts取得件数。デフォルトは20件。最大100件

レスポンス(共通)

errorエラーフラグ。エラーがなければfalse、あればtrue
total総件数
offset開始位置
count１つのページの表示件数
result検索されたデータのリスト。API毎の内容は以下を参照
rate呼び出し可能な残り回数

レスポンスのresult出力内容

/search/location/character
idキャラクターID
nameキャラクター名
profileプロフィール
imageサムネイル画像URL
image_fullオリジナル画像URL
belong所属団体
location所在地 (当道府県名 市町村名)
latitude緯度
longitude経度
distance引数で渡された緯度経度からの距離(m)
reviewご当地キャラカタログでの評価点数
review_countご当地キャラカタログでの評価したユーザー数
official公認キャラクターフラグ。公認キャラであればtrue
sourceご当地キャラカタログの該当URL
/search/location/event
idイベントID
nameイベント名
profileイベント内容
imageイベント画像
location開催場所
latitude緯度
longitude経度
distance引数で渡された緯度経度からの距離(m)
date_fromイベント開始日時
date_toイベント終了日時
sourceご当地キャラカタログの該当URL
  • イベントは、開催日が現在以降のものだけを検索対象とします。
/search/location/spot
idスポットID
nameスポット名
profileスポットの説明
image画像
location住所
latitude緯度
longitude経度
distance引数で渡された緯度経度からの距離(m)
sourceご当地キャラカタログの該当URL

文字列検索

/search/query/character (文字列からキャラクターを検索)
/search/query/event (文字列からイベントを検索)
/search/query/spot (文字列からスポットを検索)

  • それぞれ、登録されているキャラクター情報、イベント情報、スポット情報を、渡された文字列をキーにして検索します。

リクエスト引数（共通）

api_keyAPIキー。必須
offset取得件数開始位置。デフォルトは0（先頭から）
counts取得件数。デフォルトは20件。最大100件
keyword検索キーワード
method'and （AND検索） / 'or' （OR検索）
area地域名(北海道、東北、関東、東海、近畿、中国、四国、九州)
prefecture都道府県（「青森県」のように県まで指定する）
tag_modeタグのみを検索対象にする場合は1を指定
  • method,tag_modeは、キャラクター検索(/search/query/character)のみで有効です。
    イベント・スポット検索でkeywordに複数の文字列を指定した場合、自動的にOR検索となります。

レスポンス

/search/query/character

/search/location/character を参照して下さい。

/search/query/event

/search/location/event を参照して下さい。

/search/query/spot

/search/location/spot を参照して下さい。

  • /search/query系APIでは、distance項目は全て0を返します。
  • ソート順は、キャラクター(/search/query/character)は登録が新しい順、イベント(/search/query/event)は開催日付が近い順、スポット(/search/query/spot)は登録された順です。

情報

/info/character (キャラクター情報)

  • 指定されたIDのキャラクターの情報を取得します。

リクエスト引数

api_keyAPIキー。必須
idキャラクターID。必須
extraこのキャラが関連するイベント・スポット情報を一緒に取得するなら1

レスポンス

errorエラーフラグ
result検索されたデータ。個別の項目は以下を参照
rate呼び出し可能な残り回数
result項目の内容
idキャラクターID
nameキャラ名
belong所属団体
prefecture都道府県
city市区町村
latitude緯度
longitude経度
level地域レベル（都道府県、群・市、区町村の文字列）
profileプロフィール
urlURL
tag登録タグ(リスト型式)
imageキャラクター画像（サムネイル）
image_fullキャラクター画像（フルサイズ）
ref_url画像の参照元
official公認キャラクターフラグ
twitterツィッターアカウント（公式キャラ＋show_tweetが1の場合に返却）
blogブログのURL（公式キャラ＋show_feedが1の場合に返却）
sourceご当地キャラカタログの該当URL
eventsこのキャラに関連するイベント情報のリスト。引数にextraが指定されている場合に追加
spotsこのキャラに関連するスポット情報のリスト。引数にextraが指定されている場合に追加
events項目の内容
totalイベント件数
countresult に含まれるイベント情報の件数。最大で20件まで
result以下の情報の配列
idイベントID
nameイベント名
location開催場所
latitude緯度
longitude経度
distance距離(m)
date_fromイベント開始日時
date_toイベント終了日時
sourceご当地キャラカタログの該当URL
spots項目の内容
totalイベント件数
countresult に含まれるスポット情報の件数。最大で20件まで
result以下の情報の配列
idイベントID
nameイベント名
location開催場所
latitude緯度
longitude経度
distance距離(m)
sourceご当地キャラカタログの該当URL

/info/event (イベント情報)

  • 指定されたIDのイベント情報を取得します。

リクエスト引数

api_keyAPIキー。必須
idイベントID。必須

レスポンス

errorエラーフラグ
result検索されたデータ。個別の項目は以下を参照
rate呼び出し可能な残り回数
result項目の内容
idイベントID
nameイベント名
location開催場所
latitude緯度
longitude経度
prefecture都道府県
city市区町村
date_fromイベント開始日時
date_toイベント終了日時
profileイベント内容
imageイベント画像（サムネイル）
image_fullイベント画像（フルサイズ）
urlURL
contact連絡先
character関連キャラのリスト。項目は以下を参照
character_text関連キャラ（テキスト）
sourceご当地キャラカタログの該当URL
関連キャラリストの内容
idキャラクターID
nameキャラ名
imageプロフィール画像

/info/spot (スポット情報)

  • 指定されたIDのスポット情報を取得します。

リクエスト引数

api_keyAPIキー。必須
idスポットID。必須

レスポンス

errorエラーフラグ
result検索されたデータ。個別の項目は以下を参照
rate呼び出し可能な残り回数
result項目の内容
idスポットID
nameスポット名
address住所
prefecture都道府県
city市町村名
latitude緯度
longitude経度
profileスポットの説明
imageスポット画像
image_fullスポット画像（フルサイズ）
urlURL
contact連絡先
categoryカテゴリ（リスト）
character関連キャラIDのリスト
character_text関連キャラ（テキスト）
sourceご当地キャラカタログの該当URL

システムサービス

/system/limit (API呼び出し可能数取得)

リクエスト引数

api_keyAPIキー。必須

レスポンス

errorエラーフラグ
result検索されたデータ。個別の項目は以下を参照
limit上限
rate残りの呼び出し回数