{
  "openapi": "3.1.0",
  "info": {
    "title": "シルギア 漢字API",
    "version": "1.0.0",
    "description": "登録不要・無料の漢字API。漢字1字について、常用漢字か（音訓・康熙字典体・許容字体）、学年別漢字配当表の学年、人名用漢字か（表(一)・表(二)）を返します。出典は常用漢字表（平成22年内閣告示第2号）・学年別漢字配当表（平成29年文部科学省告示第63号）・戸籍法施行規則 別表第三（令和8年法務省令第43号による改正まで）。画数は入れていません。説明: https://api.shirugear.com/kanji/ 。v1 の中では項目を足すことはあっても、名前や意味は変えません（知らない項目は無視してください）。",
    "termsOfService": "https://api.shirugear.com/terms/",
    "contact": {
      "name": "アナライズギア株式会社（シルギア）",
      "url": "https://shirugear.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://api.shirugear.com"
    }
  ],
  "paths": {
    "/kanji/v1/{kanji}.json": {
      "get": {
        "summary": "漢字1字の情報（常用漢字・学年・人名用漢字）",
        "operationId": "getKanji",
        "parameters": [
          {
            "name": "kanji",
            "in": "path",
            "required": true,
            "description": "漢字1字（UTF-8 でURLエンコードする。例: 漢 → %E6%BC%A2）。常用漢字2136字・人名用漢字864字のどれか",
            "schema": {
              "type": "string",
              "minLength": 1,
              "examples": [
                "漢"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "その字の情報",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KanjiResponse"
                }
              }
            }
          },
          "400": {
            "description": "漢字1字ではない（invalid_kanji）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "常用漢字でも人名用漢字でもない（kanji_not_found）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "GET / HEAD 以外（method_not_allowed）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/kanji/v1/grade/{grade}.json": {
      "get": {
        "summary": "学年別漢字配当表の、その学年の字の一覧",
        "operationId": "getKanjiGrade",
        "parameters": [
          {
            "name": "grade",
            "in": "path",
            "required": true,
            "description": "学年（1〜6）",
            "schema": {
              "type": "string",
              "enum": [
                "1",
                "2",
                "3",
                "4",
                "5",
                "6"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "その学年の字",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GradeResponse"
                }
              }
            }
          },
          "404": {
            "description": "1〜6 以外（not_found）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/kanji/v1/joyo.json": {
      "get": {
        "summary": "常用漢字2136字の一覧（学年・康熙字典体・音訓）",
        "operationId": "getKanjiJoyoList",
        "responses": {
          "200": {
            "description": "常用漢字の一覧",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JoyoListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/kanji/v1/jinmei.json": {
      "get": {
        "summary": "人名用漢字864字の一覧（表(一)・表(二)）",
        "operationId": "getKanjiJinmeiList",
        "responses": {
          "200": {
            "description": "人名用漢字の一覧",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JinmeiListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/kanji/v1/meta.json": {
      "get": {
        "summary": "データの版・出典・件数",
        "operationId": "getKanjiMeta",
        "responses": {
          "200": {
            "description": "データの版など",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KanjiMetaResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Reading": {
        "type": "object",
        "required": [
          "reading",
          "type",
          "special",
          "stage",
          "examples"
        ],
        "description": "常用漢字表の音訓（1つ分）",
        "properties": {
          "reading": {
            "type": "string",
            "description": "音訓。音は片仮名、訓は平仮名"
          },
          "type": {
            "type": "string",
            "description": "on＝音 / kun＝訓",
            "enum": [
              "on",
              "kun"
            ]
          },
          "special": {
            "type": "boolean",
            "description": "常用漢字表で1字下げの音訓（特別なものか、又は用法のごく狭いもの）"
          },
          "stage": {
            "type": "string",
            "description": "習う学校段階の目安（音訓の小・中・高等学校段階別割り振り表）",
            "enum": [
              "小",
              "中",
              "高"
            ]
          },
          "okurigana": {
            "type": [
              "string",
              "null"
            ],
            "description": "訓だけにある項目。送り仮名（\"ゆだねる\" なら \"ねる\"）。送り仮名が無ければ \"\"。常用漢字表の例欄から決められないものは null"
          },
          "examples": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "常用漢字表の例欄の語。無ければ []"
          }
        }
      },
      "JoyoInfo": {
        "type": "object",
        "description": "常用漢字としての情報（常用漢字表 平成22年内閣告示第2号）",
        "required": [
          "order",
          "kyujitai",
          "allowed_form",
          "on",
          "kun",
          "readings",
          "jinmei_variants"
        ],
        "properties": {
          "order": {
            "type": "integer",
            "description": "常用漢字表の並び順（1〜2136）",
            "minimum": 1,
            "maximum": 2136
          },
          "kyujitai": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "表の丸括弧の字（いわゆる康熙字典体）。無ければ []。互換漢字（U+F900〜）のことがある"
          },
          "allowed_form": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "辶",
              "飠",
              null
            ],
            "description": "許容字体の違う部分（遡・遜・謎・餌・餅の5字だけ）。Unicode では通用字体と同じ文字コード"
          },
          "on": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "音の一覧（表の順）"
          },
          "kun": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "訓の一覧（表の順）"
          },
          "readings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Reading"
            }
          },
          "jinmei_variants": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "この字を括弧内に掲げる人名用漢字 表(二) の字（例: 亜 → [\"亞\"]）"
          }
        }
      },
      "JinmeiInfo": {
        "type": "object",
        "description": "人名用漢字としての情報（戸籍法施行規則 別表第三）",
        "required": [
          "table",
          "same_as",
          "joyo_form"
        ],
        "properties": {
          "table": {
            "type": "integer",
            "description": "1＝表(一)、2＝表(二)（常用漢字の異体字）",
            "enum": [
              1,
              2
            ]
          },
          "same_as": {
            "type": [
              "string",
              "null"
            ],
            "description": "表(一) で「―」で結ばれた同じ字種の字。無ければ null"
          },
          "joyo_form": {
            "type": [
              "string",
              "null"
            ],
            "description": "表(二) の括弧内の常用漢字。表(一) では null"
          }
        }
      },
      "KanjiResponse": {
        "type": "object",
        "required": [
          "kanji",
          "codepoint",
          "joyo",
          "grade",
          "school",
          "name_ok",
          "jinmei",
          "data_version"
        ],
        "properties": {
          "kanji": {
            "type": "string",
            "description": "字（1文字）"
          },
          "codepoint": {
            "type": "string",
            "description": "Unicode のコードポイント",
            "pattern": "^U\\+[0-9A-F]{4,5}$",
            "examples": [
              "U+6F22"
            ]
          },
          "joyo": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/JoyoInfo"
              },
              {
                "type": "null"
              }
            ]
          },
          "grade": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "maximum": 6,
            "description": "学年別漢字配当表の学年。配当外は null"
          },
          "school": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "小学校",
              "中学校",
              null
            ],
            "description": "小学校＝学年別漢字配当表の字、中学校＝それ以外の常用漢字、人名用漢字は null"
          },
          "name_ok": {
            "type": "boolean",
            "description": "子の名前に使える字か（このAPIが返す字はすべて true）"
          },
          "jinmei": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/JinmeiInfo"
              },
              {
                "type": "null"
              }
            ]
          },
          "data_version": {
            "type": "string"
          }
        }
      },
      "GradeResponse": {
        "type": "object",
        "required": [
          "grade",
          "count",
          "kanji",
          "data_version"
        ],
        "properties": {
          "grade": {
            "type": "integer",
            "minimum": 1,
            "maximum": 6
          },
          "count": {
            "type": "integer"
          },
          "kanji": {
            "type": "array",
            "description": "常用漢字表の順",
            "items": {
              "type": "object",
              "required": [
                "kanji",
                "codepoint",
                "on",
                "kun"
              ],
              "properties": {
                "kanji": {
                  "type": "string"
                },
                "codepoint": {
                  "type": "string"
                },
                "on": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "kun": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "data_version": {
            "type": "string"
          }
        }
      },
      "JoyoListResponse": {
        "type": "object",
        "required": [
          "count",
          "kanji",
          "data_version"
        ],
        "properties": {
          "count": {
            "type": "integer"
          },
          "kanji": {
            "type": "array",
            "description": "常用漢字表の順（2136件）",
            "items": {
              "type": "object",
              "required": [
                "kanji",
                "codepoint",
                "grade",
                "school",
                "kyujitai",
                "on",
                "kun"
              ],
              "properties": {
                "kanji": {
                  "type": "string"
                },
                "codepoint": {
                  "type": "string"
                },
                "grade": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "minimum": 1,
                  "maximum": 6,
                  "description": "学年別漢字配当表の学年。配当外は null"
                },
                "school": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "enum": [
                    "小学校",
                    "中学校",
                    null
                  ],
                  "description": "小学校＝学年別漢字配当表の字、中学校＝それ以外の常用漢字、人名用漢字は null"
                },
                "kyujitai": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "on": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "kun": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "data_version": {
            "type": "string"
          }
        }
      },
      "JinmeiListResponse": {
        "type": "object",
        "required": [
          "count",
          "kanji",
          "data_version"
        ],
        "properties": {
          "count": {
            "type": "integer"
          },
          "kanji": {
            "type": "array",
            "description": "別表第三の順（表(一) 652件・表(二) 212件）",
            "items": {
              "type": "object",
              "required": [
                "kanji",
                "codepoint",
                "table",
                "same_as",
                "joyo_form"
              ],
              "properties": {
                "kanji": {
                  "type": "string"
                },
                "codepoint": {
                  "type": "string"
                },
                "table": {
                  "type": "integer",
                  "enum": [
                    1,
                    2
                  ]
                },
                "same_as": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "joyo_form": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          },
          "data_version": {
            "type": "string"
          }
        }
      },
      "Source": {
        "type": "object",
        "required": [
          "title",
          "law",
          "url"
        ],
        "properties": {
          "title": {
            "type": "string"
          },
          "law": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "note": {
            "type": "string"
          }
        }
      },
      "KanjiMetaResponse": {
        "type": "object",
        "required": [
          "data_version",
          "sources",
          "counts"
        ],
        "properties": {
          "data_version": {
            "type": "string",
            "description": "データの版（元の告示・法令の表が変わった日付）"
          },
          "sources": {
            "type": "object",
            "required": [
              "joyo",
              "grade",
              "stage",
              "jinmei"
            ],
            "properties": {
              "joyo": {
                "$ref": "#/components/schemas/Source"
              },
              "grade": {
                "$ref": "#/components/schemas/Source"
              },
              "stage": {
                "$ref": "#/components/schemas/Source"
              },
              "jinmei": {
                "$ref": "#/components/schemas/Source"
              }
            }
          },
          "counts": {
            "type": "object",
            "description": "件数（常用2136・音2352・訓2036・学年1026・中学校1110・人名用864＝表(一)652＋表(二)212）",
            "additionalProperties": true
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "status",
              "code",
              "message"
            ],
            "properties": {
              "status": {
                "type": "integer",
                "enum": [
                  400,
                  404,
                  405
                ]
              },
              "code": {
                "type": "string",
                "description": "エラーの種類（固定の値）",
                "enum": [
                  "invalid_kanji",
                  "kanji_not_found",
                  "not_found",
                  "method_not_allowed"
                ]
              },
              "message": {
                "type": "string",
                "description": "説明文（言い回しは変わることがある）"
              }
            }
          }
        }
      }
    }
  }
}