SOLD OUT 2 API

本文書はSOLD OUT 2にて提供しているAPIについて記述したものです。

API利用条件

• SOLD OUT 2の利用規約に同意していること
• 各APIへのアクセス頻度を1時間に1回以内とすること
  • APIに別途アクセス頻度の指定がある場合はそちらを優先すること
  • 過去のデータを取得したい場合は初回に限り連続取得してもよい
• SOLD OUT 2を楽しむ為にのみ利用すること
• ローカル環境へ保存・蓄積して利用すること

注意事項

• 事前の予告等なく本文書は随時更新されます
• 事前の予告等なくAPIの仕様は随時更新されます
• 事前の予告等なくAPIの提供を終了する場合があります
• APIの利用方法等のサポートは行えません
  • 仕様に関するお問い合わせは 交流BBS ↗ までお願いします
• ゲーム内の情報が反映されるまでにタイムラグがあります

改定履歴

• 2017/10/18 アドレスのドメインが変更されました
  • 旧 so2.mutoys.com
  • 新 so2-api.mutoys.com
• 2017/10/18 利用条件および注意事項が追加されました（最後尾1件ずつ）
• 2017/10/18 ランキング、販売品、注文品、お店、住民情報のAPIが公開されました
• 2017/10/18 過去のデータの存在期間について記載されました
• 2017/10/18 注意事項へ仕様についてのお問い合わせ先が記載されました
• 2017/11/28 商品定義にセット上限数が追加されました
• 2017/12/14 利用条件に「過去データ取得例外」「ローカルへ保存」が追加されました
• 2018/03/18 レシピ商品定義が追加されました
• 2018/04/17 注文レポートと街情報が追加されました
• 2018/09/16 ランキング共通部門名リストへ「食堂」「魔王」が追加されました
• 2021/01/07 全お店リストに図鑑登録数と称号業種/職種のIDとレベル、街定義にアピール商品IDが追加されました（同日補足コメント追加）
• 2021/05/16 住民情報に流行(trend)が追加、同APIへのアクセス頻度制限が10分へ緩和されました
• 2021/07/12 商品定義とレシピ商品定義に「業種/職種」が追加されました

全API共通

• フォーマット JSON
• 文字コード UTF-8
• ”…” 同様の構造の繰り返しあり

商品定義

https://so2-api.mutoys.com/master/item.json

{
  商品ID(string): {
    "category": カテゴリー名(string),
    "class": 業種/職種名(string), // 複数の場合は '/' で連結された文字列
    "item_id": 商品ID(number),
    "limit": セット上限数(number)
    "name": 商品名(string),
    "scale": 数量単位(string),
    "sort": 並び順(number),
  },
  ...
}

レシピ商品定義

https://so2-api.mutoys.com/json/master/recipe_item.json

レシピ商品はレポート・販売品・注文品APIにおいて通常の商品と同等に扱われます。レシピ商品定義の商品 ID と商品定義のそれは重複しません。

{
  商品ID(string): {
    "category": カテゴリー名(string),
    "class": 業種/職種名(string),
    "item_id": 商品ID(number),
    "limit": セット上限数(number)
    "name": 商品名(string),
    "scale": 数量単位(string),
    "sort": 並び順(number),
  },
  ...
}

街定義

https://so2-api.mutoys.com/master/area.json

{
  街ID(string): {
    "area_id": 街ID(number),
    "desc": [
      街アピールコメント(string),
      ...
    ],
    "height": マップ縦マス数(number),
    "icon": アピール商品ID(number), // アピール商品が無い場合は0
    "name": 街名(string),
    "pos_x": マップX位置(number),
    "pos_y": マップY位置(number),
    "width": マップ横マス数(number),
  },
  ...
}

レポート

https://so2-api.mutoys.com/json/report/buy{YYYY}{MM}{DD}.json

• YYYY 対象日の西暦4桁
• MM 対象日の月2桁
• DD 対象日の日2桁
• 2017/5/7 以降のデータが存在します

{
  "system": { // 全街住民の購入レポート
    "item": {
      商品ID(string): {
        "count": 総取引件数(number),
        "unit": 総取引数量(number),
        "money": 総取引額(number),
        "price": 取引単価(number)
      },
      ...
    }
  },
  "user": { // 全街業者(店頭)の購入レポート
    "item": {
      商品ID(string): {
        "count": 総取引件数(number),
        "unit": 総取引数量(number),
        "money": 総取引額(number),
        "price": 取引単価(number)
      },
      ...
    }
  },
  "request": { // 全街業者(注文)の購入レポート
    "item": {
      商品ID(string): {
        "count": 総取引件数(number),
        "unit": 総取引数量(number),
        "money": 総取引額(number),
        "price": 取引単価(number)
      },
      ...
    }
  },
  "area": {
    街ID(string): { // 街別レポート
      "system": { // 街別住民の購入レポート
        "item": {
          商品ID(string): {
            "count": 総取引件数(number),
            "unit": 総取引数量(number),
            "money": 総取引額(number),
            "price": 取引単価(number)
          },
          ...
        }
      },
      "user": { // 街別業者(店頭)の購入レポート
        "item": {
          商品ID(string): {
            "count": 総取引件数(number),
            "unit": 総取引数量(number),
            "money": 総取引額(number),
            "price": 取引単価(number)
          },
          ...
        }
      },
      "request": { // 街別業者(注文)の購入レポート
        "item": {
          商品ID(string): {
            "count": 総取引件数(number),
            "unit": 総取引数量(number),
            "money": 総取引額(number),
            "price": 取引単価(number)
          },
          ...
        }
      },
    },
    ...
  }
}

ランキング

• 古いランキングデータには user_id や shop_id が含まれていない場合があります
• ランキング入賞者数が少ない場合は array も少なくなります
• 2017/5/7 以降のデータが存在します

ランキング共通部門名リスト

• ”point_total” 総合
• ”sale_total” 売上高
• ”exp_stock” 倉庫妖精
• ”exp_sale” 販売妖精
• ”exp_job” 作業妖精
• ”exp_trans” 輸送妖精
• ”exp_1” 薬屋
• ”exp_2” 道具屋
• ”exp_3” 武器屋
• ”exp_4” 防具屋
• ”exp_5” 本屋
• ”exp_6” 八百屋
• ”exp_7” 肉屋
• ”exp_8” 魚屋
• ”exp_9” パン屋
• ”exp_10” 商店
• ”exp_11” 資材屋
• ”exp_12” 食堂
• ”exp_51” 錬金術師
• ”exp_52” 狩人
• ”exp_53” 鉱夫
• ”exp_54” 作家
• ”exp_55” 漁師
• ”exp_56” 酪農家
• ”exp_57” 畜産家
• ”exp_58” 農家
• ”exp_59” 行商人
• ”exp_60” 鍛冶職人
• ”exp_61” 革細工師
• ”exp_62” 裁縫師
• ”exp_63” 勇者
• ”exp_64” 木工師
• ”exp_65” 細工師
• ”exp_66” 調理師
• ”exp_67” 石工師
• ”exp_68” 鋳物師
• ”exp_69” 木こり
• ”exp_70” 魔王

月間全部門トップ 3

https://so2-api.mutoys.com/json/ranking/{YYYY}-{MM}/summary.json

• YYYY 対象日の西暦4桁
• MM 対象日の月2桁

{
  部門名(string): [ // 1～3位
    {
      "top_10": デイリーランキングトップ10入賞回数(array), // デイリー1～10位獲得回数(number)
      "top1_total": トップ1獲得回数(number),
      "sort": メダル数(number),
      "user_id": オーナー番号(number),
      "shop_id": ショップ番号(number),
      "shop_name": ショップ名(string),
      "area_id": 街ID(number),
      "comment": キャッチコピー(string)
    },
    ...
  ],
  ...
}

月間部門別トップ 1000

https://so2-api.mutoys.com/json/ranking/{YYYY}-{MM}/{部門名}.json

• YYYY 対象日の西暦4桁
• MM 対象日の月2桁

[ // 1～1000位
  {
    "top_10": デイリーランキングトップ10入賞回数(array), // デイリー1～10位獲得回数(number)
    "top1_total": トップ1獲得回数(number),
    "sort": メダル数(number),
    "user_id": オーナー番号(number),
    "shop_id": ショップ番号(number),
    "shop_name": ショップ名(string),
    "area_id": 街ID(number),
    "comment": キャッチコピー(string)
  },
  ...
]

デイリートップ 1000

https://so2-api.mutoys.com/json/ranking/{YYYY}-{MM}-{DD}/{部門名}.json

• YYYY 対象日の西暦4桁
• MM 対象日の月2桁
• DD 対象日の日2桁

[ // 1～1000位
  {
    "user_id": オーナー番号(number),
    "shop_name": ショップ名(string),
    "comment": キャッチコピー(string),
    "shop_id": ショップ番号(number),
    "area_id": 街ID(number),
    "pos_x": X座標(number),
    "pos_y": Y座標(number),
    "point": ポイントもしくは売上高メダル数(number)
  },
  ...
]

販売品

https://so2-api.mutoys.com/json/sale/all.json

• 約10分間隔にて更新されます
• アクセス頻度は10分に1回以内としてください

[
  {
    "sale_serial": 販売通し番号(number),
    "area_id": 街ID(number),
    "pos_x": X座標(number),
    "pos_y": Y座標(number),
    "user_id": オーナー番号(number),
    "shop_id": ショップ番号(number),
    "shop_name": ショップ名(string),
    "item_id": 商品ID(number),
    "price": 販売単価(number),
    "unit": 販売在庫数(number),
    "bundle_sale": まとめ売り(number) // 0:ばら売り 1:まとめ売り
  },
  ...
]

注文品

https://so2-api.mutoys.com/json/request/all.json

• 約10分間隔にて更新されます
• アクセス頻度は10分に1回以内としてください

[
  {
    "trans_serial": 注文通し番号(number),
    "area_id": 街ID(number), //注文者の街
    "user_id": オーナー番号(number),
    "shop_id": ショップ番号(number),
    "shop_name": ショップ名(string),
    "item_id": 商品ID(number),
    "unit": 買い取り済み数量(number),
    "buy_unit": 買い付け希望数(number),
    "price": 注文単価(number),
    "request_area_id": 街ID(number) // 0:全域対象注文 1～:範囲対象街のID
  },
  ...
]

お店件数

https://so2-api.mutoys.com/json/shop/summary.json

[
  "total": 全店舗数(number),
  "areas": [ // 街別店舗数
    {
      "area_id": 街ID(string),
      "name": 街名(string),
      "count": 店舗数(number)
    },
    ...
  ]
]

全お店リスト

https://so2-api.mutoys.com/json/shop/all.json

業種 ID

• 1 薬屋
• 2 道具屋
• 3 武器屋
• 4 防具屋
• 5 本屋
• 6 八百屋
• 7 肉屋
• 8 魚屋
• 9 パン屋
• 10 商店
• 11 資材屋
• 12 食堂

職種 ID

• 51 錬金術師
• 52 狩人
• 53 鉱夫
• 54 作家
• 55 漁師
• 56 酪農家
• 57 畜産家
• 58 農家
• 59 行商人
• 60 鍛冶職人
• 61 革細工師
• 62 裁縫師
• 63 勇者
• 64 木工師
• 65 細工師
• 66 調理師
• 67 石工師
• 68 鋳物師
• 69 木こり
• 70 魔王

[
  {
    "user_id": オーナー番号(number),
    "shop_id": ショップ番号(number),
    "shop_name": ショップ名(string),
    "comment": キャッチコピー(string),
    "area_id": 街ID(number),
    "pos_x": X座標(number),
    "pos_y": Y座標(number),
    "shop_type": お店種類(string),
    "money": 資金(number),
    "title": 称号(string),
    "point": ポイント(number),
    "foundation_days": 創業日数(number),
    "so1_foundation_days": 元祖創業日数(number), //SO1データ引き継ぎをしていない場合は値自体が存在しません
    "item_book": 商品図鑑登録数(number),
    "high_class": [ 称号業種ID(number), 称号業種レベル(number) ], //該当データが無い場合は[0,0]
    "high_job": [ 称号職種ID(number), 称号職種レベル(number) ], //該当データが無い場合は[0,0]
  },
  ...
]

住民

https://so2-api.mutoys.com/json/people/all.json

• 約10分間隔にて更新されます
• アクセス頻度は10分に1回以内としてください

[ // 全街人口リスト
  {
    "area_id": 街ID(number),
    "unit": 街人口(number),
    "persons": { // 住民別人口
      住民ID(string): {
        "unit": 人口(number),
        "name": 住民名(string)
      },
      ...
    },
    "trend": [ // 流行情報（流行情報が無い時はnull）
      {
        "area_id": 街ID(number),
        "isPositive": ムード(boolean), // trueは上げムード、falseは下げムード
        "status": 状態(string), // 流行の状態
        "message": コメント(string), // 流行の内容
      },
      ...
    ]
  },
  ...
]

注文レポート

全注文

https://so2-api.mutoys.com/json/request/{YYYY}/{MM}/{DD}/all/{HH}.json

• YYYY 対象日の西暦4桁

• MM 対象日の月2桁

• DD 対象日の日2桁

• HH 対象時間帯の時2桁

• 特殊フォーマットです。先頭に ”[” を追加し、最後尾の ”,” を削除し、最後尾に ”]” を付けてご利用ください。

[
  売却側ショップ番号(number),
  売却側ショップ名(string),
  注文側ショップ番号(number),
  注文側ショップ名(string),
  商品ID(number),
  商品数量(number),
  注文単価(number),
  取引時刻(UNIX時間),
],
...

ショップ別注文

https://so2-api.mutoys.com/json/request/{YYYY}/{MM}/{DD}/shop/{ショップ番号}.json

• YYYY 対象日の西暦4桁

• MM 対象日の月2桁

• DD 対象日の日2桁

• ショップ番号 注文側のショップ番号

• 特殊フォーマットです。先頭に ”[” を追加し、最後尾の ”,” を削除し、最後尾に ”]” を付けてご利用ください。

[
  売却側ショップ番号(number),
  売却側ショップ名(string),
  注文側ショップ番号(number),
  注文側ショップ名(string),
  商品ID(number),
  商品数量(number),
  注文単価(number),
  取引時刻(UNIX時間),
],
...

街情報

https://so2-api.mutoys.com/json/area/summary.json

[
  {
    "area_id": 街ID(number),
    "point": 活気ポイント(number)
  },
  ...
]

特殊フォーマット parse 例

function get_parsed_json(api_response_text) {
  if (api_response_text == "" || api_response_text == null) {
    api_response_text = null;
  } else if (api_response_text.substr(-1, 1) == ",") {
    api_response_text =
      "[" + api_response_text.substr(0, api_response_text.length - 1) + "]";
  }
  return JSON.parse(api_response_text);
}