v1 Janten Mahjong API

麻雀の計算と描画を、
URL 1 本で。

雀天の対局で動いている麻雀エンジンを、そのまま公開しています。向聴数・受け入れ・何切るの比較、手牌からの点数計算、記事に貼れる手牌画像まで。登録もキーも要りません。

  • 無料・商用可
  • 登録・キー不要
  • CORS 対応
  • OpenAPI 3.1
0計算で使う乱数・AI の推論(同じ入力なら同じ答え)
46点数計算で扱う役・ドラの id
5公開している API
GET/api/v1/analyze?tiles=2334m456p3478s55z6s
2334m456p3478s55z6s の手牌
200 OKapplication/json3m 切りで聴牌・8 枚
{
  "tiles": "2334m456p3478s55z6s",
  "phase": "discard",
  "shanten": {
    "value": 0,
    "standard": 0,
    "chiitoitsu": 4,
    "kokushi": 11
  },
  "discards": [
    {
      "discard": "3m",
      "shanten": 0,
      "ukeire": 8,
      "tiles": [
        { "tile": "2s", "remaining": 4 },
        { "tile": "5s", "remaining": 4 }
      ],
      "waits": [
        { "tile": "2s", "remaining": 4 },
        { "tile": "5s", "remaining": 4 }
      ]
    },
    {
      "discard": "3s",
      "shanten": 1,
      "ukeire": 39,
      "tiles": [
        { "tile": "1m", "remaining": 4 },
        { "tile": "2m", "remaining": 3 },
        { "tile": "3m", "remaining": 2 },
        { "tile": "4m", "remaining": 3 },
        { "tile": "5m", "remaining": 4 },
        { "tile": "2s", "remaining": 4 },
        { "tile": "3s", "remaining": 3 },
        { "tile": "4s", "remaining": 3 },
        { "tile": "5s", "remaining": 4 },
        { "tile": "6s", "remaining": 3 },
        { "tile": "9s", "remaining": 4 },
        { "tile": "5z", "remaining": 2 }
      ]
    }
  ]
}

応答の先頭 2 つの打牌だけを載せています(実際は全部の打牌を良い順に返します)。

できること

計算は JSON、画像は SVG。同じ牌の書き方(123m456p7z)で全部つながります。

ブラウザで試す

このサイトの API を実際に呼び出します。表示している数字は、いま返ってきた応答そのものです。

萬子
1
2
1
筒子
1
1
1
索子
1
1
1
1
1
字牌
2

副露の種類:pon(ポン)・chi(チー)・kan(大明槓)・kakan(加槓)・ankan(暗槓)

手牌を入力してください

GET /api/v1/analyze?tiles=2334m456p3478s55z6s

3 行で呼べる

JSON を返すので、どの言語からでも扱えます。CORS を許可しているので、ブラウザの JavaScript からも直接呼べます。

JavaScript
const res = await fetch(
  "https://janten.net/api/v1/score?tiles=234m567p23678s55s4s&win=4s&by=tsumo&riichi=true&seat=2z");
const { han, fu, points } = await res.json();
// han=4 fu=20 points.label="1300-2600"
Python
import requests

requests.get("https://janten.net/api/v1/analyze",
             params={"tiles": "2334m456p3478s55z6s"}).json()

設計の約束

外部から安心して組み込めるように、守ることを決めています。

同じ入力には同じ答え

答えは手牌と条件だけで決まります。乱数も AI の推論も使いません。点数のルールは応答の rules に書いて返します。

{
  "rules": {
    "kuitan": true,
    "kiriageMangan": true,
    "kazoeYakuman": false,
    "doubleYakuman": false,
    "compositeYakuman": true
  }
}

v1 は壊さない

項目を足すことはあっても、名前と意味は変えません。変えるときは v2 を別に出し、v1 も残します。役は名前ではなく固定の id(riichi など)で返します。

誤りは場所を指す

どのパラメータの何文字目が読めなかったかを、RFC 9457 の形で返します。画像の API は、誤りも画像で返すので記事の上で原因が見えます。

{
  "title": "パラメータが正しくありません",
  "detail": "tiles: 6 文字目の「x」は…",
  "param": "tiles",
  "position": 6
}

対局と同じエンジン

雀天の対局が使う麻雀エンジン(mahjong-core)をそのまま使います。対局で不具合を直すと、API の答えも直ります。

誤りの種類

計算の API は誤りを RFC 9457 の形で返します。type の URL はこの表の行を指します。

type状態いつ
https://janten.net/api#error-invalid-parameter400牌の書き方の誤り・知らないパラメータ・同じ牌 5 枚以上・枚数や副露の形の誤りなど。param と position で場所を示す
https://janten.net/api#error-not-winning-hand422点数計算で、和了の形になっていない(shanten に向聴数)
https://janten.net/api#error-no-yaku422点数計算で、和了の形だが役が無い(ドラだけ)
https://janten.net/api#error-inconsistent-situation422点数計算で、同時に成り立たない状況(鳴いた手の立直、ロンの嶺上開花など)
https://janten.net/api#error-rate-limited429IP ごとの 1 分あたりの回数か、重い計算(牌効率)の全体の 1 秒あたりの回数を超えた。Retry-After の秒数だけ待つ

利用条件

個人・企業・商用を問わず無料です。

  • 画像を載せるときは、雀天へのリンクを近くに置いてください(コードは各ページでコピーできます)
  • 計算の API は、アプリや README のどこかに「雀天 API」へのリンクをお願いします
  • 計算の API は、IP ごとに 1 分 60 回までです。牌効率は重い計算なので、全体でも 1 秒 5 回までにしています。超えると 429 と Retry-After を返します
  • v1 の仕様を変えるときは、30 日前にこのページでお知らせします
  • 障害や悪用への対応で、予告なく止めることがあります。計算の結果に誤りが無いことは保証しません
  • 答えに誤りを見つけたら、X(@janten_mahjong)で知らせてください