HuTime Web APIを使って和暦と西暦を変換する

## はじめに
![きょうみくん](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3538635/dbf652b4-4dff-f7cf-809f-7c7265d05e04.png)
ぼくはきょうみくんと申します。IT機器の総合サポートサービスを行っている[日本ＰＣサービス株式会社](https://www.j-pcs.jp/)でマスコットキャラクターをしています。

ぼくは管理者として便利ツール集サイトを運営していて、便利ツールの1つとして[和暦西暦変換ツール](https://toools.jp/jp-ce-conversion.php)を提供しています。このツールは[HuTime Web API- Calendar Calculation](https://ap.hutime.org/cal/)とJavaScriptで制作しています。

![和暦西暦変換ツール](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3538635/2d4b4a45-e6cc-ff4a-072e-b338b2d6b3cc.png)

今回はHuTime Web APIを利用して和暦と西暦を変換するコードを紹介します。

## HuTimeとは？
HuTimeとは、時間に基づいて情報の可視や解析を行う時間情報解析ソフトウェアです。HuTime Web API - Calendar Calculationは、暦法の変換や暦法に基づく期間の計算を行えるAPIです。

## ライセンス
執筆時点ではCreative Commons Attribution 4.0 International Licenseです。最新の情報は下記ページで確認してください。

https://www.hutime.org/about/license.html

## HuTime Web API - Calendar Calculationの使い方
今回はGETメソッドでリクエストしてJSON形式で受け取ります。JSON-RPCで利用することも可能です。 

※ライブラリにjQuery v3.3.1を使用しています。
※最低限のコードなので失敗時などの処理は追加してください。

### 例1）令和5年を西暦に変換する
#outputに2023年が表示されます。

```javascript
let ajaxData = {
    method: 'conv', // 処理の種類
    out   : 'json', // 出力形式
    ical  : '1001.1', // 変換元の暦法の暦法ID。1001.1は和暦（南朝）
    ocal  : '101.1', // 変換先の暦法の暦法ID。101.1はユリウス/グレゴリオ暦（1582年に改暦）
    itype : 'year', // 暦日等の型
    ival  : '令和5年' // 暦日等を表す文字列
};

$.ajax({
    type   : 'GET',
    url    : 'https://ap.hutime.org/cal/',
    data   : ajaxData,
    timeout: 5000
}).done((data) => {
    if (data[0] !== null) {
        $.each(data, (key, val) => {
            // C.E. 2023の形式になっているので2023年の表記になるように置換した上で、先頭の0を置換
            $('#output').text(val.text.replace('C.E. ', '').replace(/^0/, '') + '年');
        });
    }
});
```
:::note info
リクエストURL
[https://ap.hutime.org/cal/?method=conv&out=json&ical=1001.1&ocal=101.1&itype=year&ival=%E4%BB%A4%E5%92%8C5%E5%B9%B4](https://ap.hutime.org/cal/?method=conv&out=json&ical=1001.1&ocal=101.1&itype=year&ival=%E4%BB%A4%E5%92%8C5%E5%B9%B4)
:::

取得する文字列がC.E. 2023の形式になっているので2023年の表記になるように置換して最後に年を追加しています。また、3桁の場合はゼロ埋めで4桁になるので先頭の0を置換しています。

例）大化1年→C.E. 0645→645年

紀元前の場合は先頭の文字列はC.E.ではなくB.C.E.です。提供しているツールでは紀元前には対応していないため、C.E.のみ置換しています。

サンプルコードでは変換元の暦法を和暦（南朝）にしていますが、北朝の和暦にする場合は1001.2を指定します。変換先の暦法を1752年改暦のユリウス/グレゴリオ暦にする場合は101.2を指定します。

### icalとocalに指定する暦法の一覧
| 暦ID | 暦名 |
|:-|:-|
| 1.1 | ユリウス通日 |
| 2.1 | 先発グレゴリオ暦 |
| 101.1 | ユリウス/グレゴリオ暦（1582年改暦） |
| 101.2 | ユリウス/グレゴリオ暦（1752年改暦） |
| 102.1 | ユリウス暦 |
| 103.1 | イスラム暦 |
| 104.1 | ユダヤ暦 |
| 1001.1 | 和暦（南朝） |
| 1001.2 | 和暦（北朝） |
| 1002.2 | 和暦（明治以降の旧暦） |
| 1003.1 | タイ仏暦 |
| 1004.1 | 民国暦 |

参考：[Calendar List](https://datetime.hutime.org/calendar/)

### itypeに指定する暦日等の型
| 指定子 | 暦日等の型 |
|:-|:-|
| date | 暦日 |
| month | 暦月 |
| year | 暦年 |
| era | 年号 |
| 10y<br>100y<br>1000y | ～年代<br>（それぞれ、10, 100, 1000年間を示す） |
| century<br>millennium | 世紀、および、千年紀<br>（グレゴリオ暦とユリウス暦に由来する暦法でのみ指定可） |

参考：[（２）変数による指定](https://ap.hutime.org/cal/#chapter2-2-2)

各パラメーターの詳細は公式ドキュメントを見てください。

https://ap.hutime.org/cal/

### 例2）2023年8月1日を和暦に変換する
#outputに令和5年8月1日が表示されます。
```javascript
let ajaxData = {
    method: 'conv', // 処理の種類
    out   : 'json', // 出力形式
    ical  : '101.1', //変換先の暦法の暦法ID。101.1はユリウス/グレゴリオ暦（1582年に改暦）
    ocal  : '1001.1', //変換元の暦法の暦法ID。1001.1は和暦（南朝）
    itype : 'date', // 暦日等の型
    ival  : '2023年8月1日' // 暦日等を表す文字列
};

$.ajax({
    type   : 'GET',
    url    : 'https://ap.hutime.org/cal/',
    data   : ajaxData,
    timeout: 5000
}).done((data) => {
    if (data[0] !== null) {
        $.each(data, (key, val) => {
            // ○○1年を元年の表記になるように置換
            $output.text(val.text.replace(/^(\D+)1年/, '$1元年'));
        });
    }
});
```
:::note info
リクエストURL
[https://ap.hutime.org/cal/?method=conv&out=json&ical=101.1&ocal=1001.1&itype=date&ival=2023%E5%B9%B48%E6%9C%881%E6%97%A5](https://ap.hutime.org/cal/?method=conv&out=json&ical=101.1&ocal=1001.1&itype=date&ival=2023%E5%B9%B48%E6%9C%881%E6%97%A5)
:::

2019年8月1日のように和暦で1年になる場合は、1年を元年に置換しています。
例）令和1年→令和元年

暦日等を表す文字列は2023年8月1日、2023-08-01、2023/08/01、2023_ August_01など様々な書式に対応しています。

書式の詳細は公式ドキュメントを見てください。

http://datetime.hutime.org/date/2460177.5?out=html

## 暦変換サービスについて
ぼくが作った和暦西暦変換ツールとAPIを使った簡単な変換方法を紹介しましたが、Web上で暦を変換したいならHuTimeの公式サービスがあります。特に不都合がないなら公式サービスが多機能で便利です。

https://www.hutime.jp/basicdata/calendar/form.html

## 最後に
ぼくは諸事情によりjQueryを使用してコードを書いていますが、今はもうネイティブのJavaScriptで書いて良いと思います。

公式ドキュメントには他にも様々な利用方法が掲載されています。利用に際しての注意事項も記載されているので、利用する前に確認してください。

https://ap.hutime.org/cal/