Cinderella API v2 [ @imcgborder REST API ]

好きなストーリー めくってはじめよう Sing the Prologue♪

デレマスボーダーbotの情報を外部で活用したい開発者のみなさまへ、 API を提供しています。

目次一覧:

  1. Cinderella API の仕様について
  2. 全API共通
  3. イベント関係 API
  4. プロデューサー関係 API
  5. プロダクション関係 API
  6. アイドル・カード関係 API
  7. 道場関係 API
  8. フリートレード履歴関係 API

このドキュメントは、Cinderella API v2 の仕様を説明しています。2020年8月まで利用されていた古い API である、Cinderella API v1 のドキュメントはこちら です。現在は、新規利用では必ず v2 を利用してください。

Cinderella API の仕様について

Cinderella APIとは

デレマスボーダーbotのデータをAPIの形で提供しています。

外部アプリ(Webサイト、Twitter bot、Discord bot、各種デスクトップアプリなど)で、デレマスボーダーbotと同等のデータを利用することができます。

共通仕様

  1. 大原則として、デレマスボーダーbotが保有していない(欠けている)データはなにをどうやっても出力できません。Webポータルで表示されないデータは API でも出てきません。
  2. JSON 形式のみ対応しています。デフォルトでは整形された JSON を提供します。 pretty=false をクエリーとして付与すると、非整形の状態で提供され、より高速になります。
  3. 成否の判断は常に HTTP ステータスコードで返却されます。 4xx/5xx はすべてエラーです。
  4. 短時間に高速のリクエストを行うか、または応答データ量の大きいリクエストを複数回行った場合、 429 [Too Many Requests] が返却されます。応答完了後、5秒の wait を行うことを推奨します。
  5. パラメータの型に ? が付与されているものは任意値を表します。
  6. レスポンスにおける ? はその型が nullable であることを表します。ただし、string は常に nullable です。
  7. パラメータの型に [] が付与されているものは配列を表します。パラメータでは半角カンマ (,) 区切りで付与してください。例:?systemId=1,2,3
  8. DateTime 型は ISO8601 拡張形式 (2020-11-28T05:00:11+09:00) で記載すると確実に解釈します。+%2B でURLエンコードする必要があるかもしれません。タイムゾーンを省略した場合、原則として JST(+09:00) で認識されます。
  9. APIごとの Limit の記載は、API ごとの、1アクセスにおける最大応答件数の制限を示します。たとえば、2000が設定されている場合は最大でも2000件しか JSON 出力されません。
    要求条件によっては、出力されている以上の件数が実データとしては存在する場合があります。この場合、応答の totalCount には実データとして存在する件数、outputCount には JSON で出力した件数が設定されます。つまり totalCount > outputCount なら取得漏れを起こしています。
  10. パラメータに破壊的変更が入った場合は URL のバージョンを変更する予定です(保証はしません)。ただし、送受信いずれのパラメータも、項目追加は破壊的変更に含みません。新たな値が増える想定で実装することをおすすめします。

イベントIDの考え方

デレマスボーダーbotは、総合ランキングと中間ランキングを表現するため、独自の ID 体系(内部ID)を持っています。

【例】真実の強さを纏う公演 テイルズ オブ シンデリア2
モバゲーイベントID
(MobageEventId)
イベント基本ID
(EventInfoId)
イベント明細ID
(EventDetailId)
種別
1926 270 262 総合ランキング
263 中間ランキング

IDは「イベント情報」で取得してください。パラメータ指定時は、イベント基本IDまたはイベント明細IDでの問い合わせが必要な場合があります。

全量データを取得したい場合

この API には一度のデータ取得量に制約があるため、全量を一括ダウンロードして利用したい場合は、CSV が便利です。API と同様、定期的なアクセスを歓迎しています。

利用規定 (留意事項)

  1. Cinderella API を利用して公開サービスを作成・運用する場合は、その取得元がデレマスボーダーbot(@imcgborder)であることを明記してください。
  2. API の動作状況や送信内容にかかわらず、API を利用したサービスの利用者からの問い合わせがデレマスボーダーbotに直接送られることがないよう明示的に記載しなければなりません。問い合わせは必ず API を利用されるサービス側で集約し、必要に応じて Twitter:@imcgborder へ連絡をお願いします。
  3. 特定のプロデューサー・プロダクションの晒し上げや、特定アイドルを担当しているプロデューサーが不快になる可能性が考えられる用途において、データを利用することはご遠慮ください。
  4. 上記に記載のない内容は、デレマスボーダーbotの利用規定に準じます。

全API共通

全API共通フォーマット

すべてのAPIはこの共通フォーマットとともに提供されます。

レスポンスデータ

  • int statusCode 応答したステータスコード(APサーバ停止時はこのコードが返却されませんので、エラー判定には HTTP ヘッダの値を利用してください)
  • bool isSuccess データ取得処理の成功時にtrue
  • bool deprecated APIが非推奨、または非推奨となったパラメータが含まれる要求時にtrue
  • string message メッセージ(エラーメッセージなど)
  • int totalCount パラメータにマッチした件数
  • int outputCount contentで出力した件数(API の Limit によっては、totalCount より少ない場合があります)
  • object[] content 出力内容(各APIの個別仕様を参照してください)

デレマスボーダーbot 内部コード [GET] /api/v2/codes

Limit なし

API の要求・応答で用いるキーは、この API で説明を含めて提供しています。
以下のドキュメントで「コードカテゴリ」と記載している場合は、コード毎の意味がこの API に掲載されています。
ex. https://pink-check.school/api/v2/codes

レスポンスデータ

  • string categoryKey コードカテゴリ
  • string explanation コードカテゴリの説明
  • string parentCategoryKey 親コードカテゴリ
  • object[] detail コード明細
    • int codeValue コード値/数値キー。ほとんどの API の要求・応答ではこの値を用います。
    • string stringValue コード値/文字列キー。カードレアリティなど、一部のコードで用います。
    • string producerName プロデューサー名
    • int? parentCodeValue 親コード値
    • string shortExplanation 説明(短縮形)
    • string explanation 説明
    • string remarks 備考

備考

  • codeValue は、同一 categoryKey において一意 (unique) です。
  • stringValue は、同一 categoryKey において一意 (unique) です。

イベント関係 API

イベント情報 [GET] /api/v2/events/[eventInfoId?]

Limit なし

ex.
https://pink-check.school/api/v2/events/
https://pink-check.school/api/v2/events/279

パスパラメータ

  • int? eventInfoId イベント基本情報ID(mobageEventId/name と同時指定不可)

クエリパラメータ

  • int? mobageEventId モバゲーイベントID(eventInfoId/name と同時指定不可)
  • string? name イベント名(部分一致検索。eventInfoId/mobageEventId と同時指定不可)
  • int? eventTypeId イベント種別ID※
  • DateTime? time 指定された時間に開催中のイベントを取得

レスポンスデータ

  • int eventInfoId イベント基本情報ID
  • int mobageEventId モバゲーイベントID
  • string name イベント名
  • string shortName イベント名 (ボーダーbot内で使用されている省略表記版)
  • int eventTypeId イベント種別ID (コードカテゴリ:EventTypeId)
  • string eventTypeName イベント種別名
  • bool isReprint 復刻イベント
  • object[] detail イベント明細
    • int eventDetailId イベント明細ID
    • int sequence シーケンス
    • string eventDetailTypeId イベント明細種別ID (コードカテゴリ:EventDetailTypeId)
    • int explanation 明細説明
    • DateTime beginDateTime イベント開始日時
    • DateTime endDateTime イベント終了日時
    • DateTime finalRankingDateTime ランキング公開日時
    • string cardHash 上位報酬カードハッシュ
    • string cardName 上位報酬カード名
    • int take2CardRank 2枚取りの最低順位
    • int take1CardRank 1枚取りの最低順位
    • int orgRewardRankingTypeId 団体上位報酬の入賞種別 (コードカテゴリ:RankingTypeId)
    • int orgRewardBorderRank 団体入賞報酬がもらえる団体の順位
    • int orgRewardMembers 団体の最大構成人数
    • string remark 備考
  • object[] timeTable イベント明細
    • int eventTimeTypeId イベントタイムテーブル種別ID
    • DateTime begin 開始日時
    • DateTime end 終了日時
  • object[] abilityCard イベントパワー発揮カード
    • string cardHash カードハッシュ
    • string cardName カード名
    • decimal scale パワー倍率

備考

  • abilityCard は、EventInfoId が 279 以降にのみデータが存在します。

イベント順位情報 [GET] /api/v2/eventdetails/[eventDetailId]/rankings/points

Limit なし

ex. https://pink-check.school/api/v2/eventdetails/369/rankings/points
ex. https://pink-check.school/api/v2/eventdetails/369/rankings/points?rank=1,2,3,4,5&rankingTypeId=1

パスパラメータ

  • int eventDetailId イベント明細ID

クエリパラメータ

  • int[]? rank 取得対象順位(100件まで指定可能。all/targetId と同時指定不可)
  • bool? all 全順位取得(未指定または false 指定時は100位、200位、2000位などの基準順位のみ。rank/targetId と同時指定不可)
  • int[]? systemId 取得対象のモバゲーIDまたはプロダクションID(100件まで指定可能。rank/all と同時指定不可)
  • int? rankingTypeId イベント順位種別ID(コードカテゴリ:RankingTypeId。rank/targetId 指定時は必須)
  • DateTime? time 対象観測日時(毎時0分のみ指定可)

レスポンスデータ

  • DateTime time 日時
  • object[] ranking ランキング
    • int rankingTypeId イベント順位種別ID (コードカテゴリ:RankingTypeId)
    • int rank 順位
    • long point イベントpt
    • int? systemId モバゲーIDまたはプロダクションID(ミニチームの場合は null
    • string name ユーザ・プロダクション名
    • string leaderCardHash リーダーカードハッシュ

備考

  • パラメータで順位を指定しない場合、基準順位(個人200位、2000位など)のみを出力します。
  • all 指定時に time を指定していない場合、直近の0分の情報が取得されます。
  • イベント期間中は基準順位+個人2000位より上のプロデューサーのptを観測しています。イベント終了後に、最終結果の全順位を取得します。したがって、常にすべての順位を取得できるわけではありませんし、イベント最終時刻とそれ以前では取得可能な順位が異なります。
  • 更新されるタイミングは、基準順位は10分毎の更新後1分以内、それ以外の順位は6分以内が目処です。通常よりモバゲー側が応答に時間を要しているような場合は、基準順位以外の更新をしない(取得をやめる)ことがあります。
  • TBSなどの受取ptがあるイベントの場合、毎ラウンド最終時刻においては取得処理全体が20分遅延されます。
  • 中間・最終ランキングの種別にかかわらず、イベント終了時刻のスコア取得は最終ランキング公開日時に実行されます。また、プロデューサーおよびプロダクションの全順位はイベント終了後36時間後に取得されます。

プロデューサー関係 API

プロデューサー検索 [GET] /api/v2/producers/[mobageId?]

Limit 2000

ex. https://pink-check.school/api/v2/producers/62160821
ex. https://pink-check.school/api/v2/producers?producerName=C

パスパラメータ

  • int? mobageId モバゲーID(producerName/productionId との同時指定不可)

クエリパラメータ

  • string? producerName ユーザ名(前方一致。mobageId/productionId との同時指定不可)
  • int? productionId プロダクションID(mobageId/producerName との同時指定不可)
  • DateTime? beginUpdateTimestamp 更新日時(自) (endUpdateTimestampの指定必須)
  • DateTime? endUpdateTimestamp 更新日時(至) (beginUpdateTimestampの指定必須)

レスポンスデータ

  • int mobageId モバゲーID
  • int? productionId 所属プロダクションID
  • string productionName 所属プロダクション名
  • string unitName ユニット名
  • int? katagakiId 肩書ID
  • string producerName プロデューサー名
  • int producerRank プロデューサーランク (コードカテゴリ:Rank)
  • long fans ファン数
  • string leaderCardHash リーダーアイドルハッシュ
  • int? leaderIdolId リーダーアイドルID
  • string leaderCardName リーダーアイドル名
  • int level レベル
  • string classification 属性 (コードカテゴリ:Classification)
  • int battle LIVEバトル回数
  • int victory LIVEバトル勝利数
  • int album アルバム写真数
  • int shinaiMax 親愛度MAX人数
  • string favorite1CardHash ホシイモノ1カードハッシュ
  • string favorite1CardName ホシイモノ1カード名
  • string favorite2CardHash ホシイモノ2カードハッシュ
  • string favorite2CardName ホシイモノ2カード名
  • string favorite3CardHash ホシイモノ3カードハッシュ
  • string favorite3CardName ホシイモノ3カード名
  • DateTime updateTimestamp 更新日時

備考

  • mobageId/producerName/productionId/beginUpdateTimestamp いずれかは必須です。
  • このAPIで検索できるプロデューサー情報は、ボーダーbotが現在把握している最新情報のみです。プロデューサーごとの過去の明細は、プロデューサー明細情報を使用して取得してください。
  • ホシイモノ1~3は、設定されているものがアイドルの場合のみ表示されます。スタドリなどのアイテムの場合は空白またはnullとなります。

プロデューサー明細情報 [GET] /api/v2/producers/[mobageId]/details

Limit なし

ex. https://pink-check.school/api/v2/producers/62160821/details

パスパラメータ

  • int mobageId モバゲーID

レスポンスデータ

  • int eventDetailId イベント明細ID
  • int? mobageId モバゲーID
  • int? productionId 所属プロダクションID
  • string productionName 所属プロダクション名
  • string unitName ユニット名
  • int? katagakiId 肩書ID
  • string producerName プロデューサー名
  • int? producerRank プロデューサーランク (コードカテゴリ:Rank)
  • long fans ファン数
  • string leaderCardHash リーダーアイドルハッシュ
  • int? leaderIdolId リーダーアイドルID
  • string leaderCardName リーダーアイドル名
  • int level レベル
  • string classification 属性 (コードカテゴリ:Classification)
  • int battle LIVEバトル回数
  • int victory LIVEバトル勝利数
  • int album アルバム写真数
  • int shinaiMax 親愛度MAX人数
  • string favorite1CardHash ホシイモノ1カードハッシュ
  • string favorite1CardName ホシイモノ1カード名
  • string favorite2CardHash ホシイモノ2カードハッシュ
  • string favorite2CardName ホシイモノ2カード名
  • string favorite3CardHash ホシイモノ3カードハッシュ
  • string favorite3CardName ホシイモノ3カード名
  • int eventRank イベント最終順位
  • long eventPoint イベント最終pt

備考

  • 現在開催中の順位・スコアは表示されません。
  • ユーザが参加していないイベントの明細は表示されません。
  • ホシイモノ1~3は、設定されているものがアイドルの場合のみ表示されます。スタドリなどのアイテムの場合は空白/nullとなります。

プロダクション関係 API

プロダクション検索 [GET] /api/v2/productions/[productionId?]

Limit 2000

ex. https://pink-check.school/api/v2/productions/309761
ex. https://pink-check.school/api/v2/productions?producerName=A

パスパラメータ

  • int? productionId モバゲーID(producerName との同時指定不可)

クエリパラメータ

  • string? producerName プロダクション名(前方一致。productionId との同時指定不可)
  • DateTime? beginUpdateTimestamp 更新日時(自) (endUpdateTimestampの指定必須)
  • DateTime? endUpdateTimestamp 更新日時(至) (beginUpdateTimestampの指定必須)

レスポンスデータ

  • int productionId プロダクションID
  • string productionName プロダクション名
  • int? productionRank プロダクションランク (コードカテゴリ:Rank)
  • long fans ファン数
  • int level レベル
  • int development 発展度
  • long development 増資マニー
  • int representProducerId 代表プロデューサーID
  • string representProducerName 代表プロデューサー名
  • int members 社員数
  • bool esthe エステルーム
  • bool cafe カフェテラス
  • bool sauna サウナルーム
  • string comment コメント
  • DateTime updateTimestamp 更新日時

備考

  • productionId/productionName/beginUpdateTimestamp いずれかは必須です。
  • このAPIで検索できるプロダクション情報は、ボーダーbotが現在把握している最新情報のみです。プロダクションごとの過去の明細は、プロダクション明細情報を使用して取得してください。

プロダクション明細情報 [GET] /api/v2/productions/[productionId]/details

Limit なし

ex. https://pink-check.school/api/v2/productions/309761/details

パスパラメータ

  • int productionId プロダクションID

レスポンスデータ

  • int eventDetailId イベント明細ID
  • int? productionId プロダクションID
  • string productionName プロダクション名
  • int productionRank プロダクションランク (コードカテゴリ:Rank)
  • long fans ファン数
  • int level レベル
  • int development 発展度
  • long money 増資マニー
  • int? representProducerId 代表プロデューサーID
  • string representProducerName 代表プロデューサー名
  • int members 社員数
  • bool esthe エステルーム
  • bool cafe カフェテラス
  • bool sauna サウナルーム
  • string comment コメント
  • int eventRank イベント最終順位
  • long eventPoint イベント最終pt

備考

  • ミニチームイベント場合、このAPIでは情報が出力されません。
  • 所属しているプロダクションメンバーが1名も参加していない(=プロダクションのポイントが 0 の)イベントの明細は表示されません。

アイドル・カード関係 API

アイドル [GET] /api/v2/idols/[idolId?]

Limit なし

ex. https://pink-check.school/api/v2/idols

パスパラメータ

  • int? idolId アイドルID

レスポンスデータ

  • int idolId アイドルID (ボーダーbot内部ID)
  • string name アイドル名
  • string yomi 読み方(ひらがな)
  • string classification 属性 (コードカテゴリ:Classification)
  • int birthdayMonth 誕生日(月)
  • int birthdayDate 誕生日(日)
  • int age 年齢
  • string constellation 星座
  • string bloodGroup 血液型
  • string handedness 利き手
  • string originPlace 出生地
  • string hobby 趣味
  • string characterVoice 声優

カード [GET] /api/v2/cards/[cardHash?]

Limit なし

ex.https://pink-check.school/api/v2/cards
ex.https://pink-check.school/api/v2/cards/abbe52ff16730a445dd85e701907925c

パスパラメータ

  • string? cardHash カードハッシュ(32桁。cardMobageId/idolId との同時指定不可)

クエリパラメータ

  • int? cardMobageId カードモバゲーID (Mobage上でのカードID) (cardHash/idolId との同時指定不可)
  • int? idolId アイドルID(cardHash/cardMobageId との同時指定不可)

レスポンスデータ

  • string cardHash カードハッシュ
  • int cardMobageId カードモバゲーID (Mobage上でのカードID)
  • int idolId アイドルID (ボーダーbot内部ID)
  • string rality レアリティ (コードカテゴリ:Rality)
  • string name カード名
  • string aliasName カード別名(ex. [ルミナススター]北条加蓮(2020)における[ルミナススター]北条加蓮)
  • string prefix カードプレフィクス
  • bool isPlus 特訓後の場合 true
  • string height 身長
  • string weight 体重
  • string bustSize バストサイズ
  • string waistSize ウエストサイズ
  • string hipSize ヒップサイズ
  • int cost コスト
  • int defaultAttack 初期攻
  • int defaultDefence 初期守
  • string abilityName 特技名
  • object? abilityEffect 特技効果
  • object? doubleAbilityEffect ダブル特技効果
  • bool growIdol アイプロ育成アイドル
  • bool freeTradeLimited フリートレード制限中

備考

  • 登録直後のカードは取得できないことがあります。
  • 現在開催中のイベントの上位報酬SRは取得できません。配布後に登録されます。

道場関係 API

道場 [GET] /api/v2/dojos

Limit なし

ex. https://pink-check.school/api/v2/dojos

クエリパラメータ

  • int? minLevel 最低レベル(300~400)
  • int? maxLevel 最高レベル(300~400)
  • int? minRank 最低プロデューサーランク(コードカテゴリ:Rank)
  • int? maxRank 最高プロデューサーランク(コードカテゴリ:Rank)

レスポンスデータ

  • int mobageId モバゲーID
  • int dojoStatusId 道場ステータスID(営業中:10、休業:80、廃業:90
  • DateTime registDateTime 道場登録日時
  • DateTime lastUpdate 最終更新日時
  • int level レベル
  • int producerRank プロデューサーランク (コードカテゴリ:Rank)
  • string producerName プロデューサー名
  • int? productionId プロダクションID
  • string productionName プロダクション名
  • string leaderCardHash リーダーアイドルハッシュ
  • string leaderCardName リーダーアイドル名
  • int? defaultDefence リーダーアイドル初期守
  • string unitName ユニット名
  • string comment コメント

備考

  • レベル300未満の道場はボーダーbotでは取り扱いません。
  • 道場のクロール間隔期待値は通常18時間毎です。ただし、イベントの終了後(通常23時)からイベント最終結果発表の36時間後までの間は、最終結果取得処理を優先するためクロールが行われません。
  • dojoStatusIdは、ユニット名やコメントに「休業」「おやすみ」などの文言が含まれていると休業と判定されます。

フリートレード履歴関係 API

フリートレード履歴 [GET] /api/v2/trades/[cardHash?]

Limit 2000

ex.https://pink-check.school/api/v2/trades/3815832491e393399209a0b9ae0e56ef
ex.https://pink-check.school/api/v2/trades/?beginTime=2020-08-01T00:00:00+09:00&endTime=2020-08-04T12:00:00+09:00

パスパラメータ

  • string? cardHash トレード対象カード(32桁) ※送り元が宛先に送るカードを指します。

クエリパラメータ

  • DateTime? beginTime 検索対象のトレード日時(自) (endTimeの指定必須)
  • DateTime? endTime 検索対象のトレード日時(至) (beginTimeの指定必須)
  • string? sourceProducerName 送り元プロデューサー名
  • string? destProducerName 宛先プロデューサー名
  • int? eventCardAbility パワー持ちカード検索条件 (コードカテゴリ:CardAbilitySearchCondition)
  • int? eventInfoId パワー持ちカード検索対象イベント基本ID(eventCardAbilityの指定必須。省略時は開催中の最新のイベントになります)

レスポンスデータ

  • int mobageTradeHistoryDetailId モバゲーフリートレード明細ID
  • string cardHash トレード対象カードハッシュ
  • string cardName トレード対象カード名
  • DateTime tradeTime トレード日時
  • bool isPremium トレード対象カードがプレミアムサイン付か
  • string sourceProducerName 送り元プロデューサー名
  • string destProducerName 宛先プロデューサー名
  • object[] item トレードアイテム ※送り元がトレード希望内容として登録したものです。最大5件まで設定されます。
    • int sequence トレードアイテム設定番号
    • int itemTypeId アイテム種別ID (コードカテゴリ:ItemTypeId)
    • int? volume 取引量(アイテム数量、またはマニーの数)
    • string cardHash カードハッシュ
    • string cardName カード名

備考

  • eventInfoId は、279 以降を指定した場合のみ機能します。