HuTime Web API - Calendar Calculation

English

中国暦（試行版）については こちら　

１．概要

HuTime Web API (Calendar Calculation) は、暦法の変換や暦法に基づく期間の計算を行う機能を提供する。暦日だけでなく、年号、暦年、暦月など、暦法に基づいて定められるさまざまな期間（以下、「暦日等」）を対象とした操作が可能である。

２．共通事項

ここでは、Web APIの利用について、各処理に共通する事項を説明する。各処理に固有の事項は「各処理の詳細」を参照のこと。

２－１．基本的な使い方

各変数に必要な値を設定し、以下のURLにPOSTまたはGETメソッドで要求する。

http://ap.hutime.org/cal/

（例） グレゴリオ暦の暦日を和暦の暦日に変換する(GETメソッド)。

http://ap.hutime.org/cal/?method=conv&ical=101.1&itype=date&ival=2017-11-16&ocal=1001.1

APIをJSON-RPC 2.0に則って利用することもできる。この場合、POSTメソッドのみ利用可能であり、リクエストヘッダの content-type を application/json とする必要がある。

（例） グレゴリオ暦の暦日を和暦の暦日に変換する。

リクエスト
{"jsonrpc":"2.0","method":"conv","params":{"ocal":"1001.1","ical":"101.1","itype":"date","ival":"2017-11-17"},"id":42}
レスポンス
{"jsonrpc":"2.0","result":[{"text":"平成29年11月17日"}],"id":42}

２－２．暦日等の指定

入力データとしての暦日等は、（１）暦に関するLinked Dataの暦リソース指定するか、または、（２）変数に必要な情報を設定することより指定する。なお、処理によっては下記の変数に加えて、iuri2 または ical2, itype2, ical2, iform2 の各変数に値を設定する。

（１）暦リソースによる指定

変数iuriに暦リソース設定する。

（例） グレゴリオ暦の暦日、2017年11月17日を指定する場合（いずれも同じ暦日を指定）。

（２）変数による指定

暦日等の暦法と型、および、暦日等を表す値または文字列をそれぞれ以下の変数に設定する。

ical
必須
暦法を暦IDで指定する。
itype
必須
暦日等の型を以下の指定子を使って指定する。
指定子暦日等の型
date暦日
month暦月
year暦年
era年号
10y
100y
1000y
～年代
（それぞれ、10, 100, 1000年間を示す）
century
millennium		世紀、および、千年紀
（グレゴリオ暦とユリウス暦に由来する暦法でのみ指定可）
ival
必須
暦日等を表す文字列（日付文字列）、または、時間範囲の始点を示すユリウス通日。
iform
任意
日付文字列の書式指定。iform が設定されていない場合は、暦法ごとの既定の書式が適用される。

（例） グレゴリオ暦の暦日、2017年11月17日を指定する場合。

  • ical=101.1&itype=date&ival=2017_November_17
  • ical=101.1&itype=date&ival=2017-11-17
  • ical=101.1&itype=date&ival=2458074.5

（３）複数の暦日等の指定

複数の暦日等を入力し、それらを一括して処理することが可能である。暦リソースによる指定では、それぞれのURIを改行（CRLF）で区切ってiuriに設定し、変数による指定では、ivalに設定するそれぞれの値を改行で区切る。暦リソースによる指定では、暦法および型の情報がそれぞれのURIに含まれるが、変数による指定ではicalおよびitypeに1つの値しか設定できない。このため、前者では暦法や型の異なる複数の暦日等を指定することができるが、後者では、icalおよびitypeに設定した暦法と型に限定される。

（例） 和暦の年号、大正、昭和、平成を指定する場合。改行は"\r\n"で表す。

暦リソースによる指定
iuri=http://datetime.hutime.org/calendar/1001.1/era/大正\r\n http://datetime.hutime.org/calendar/1001.1/era/昭和\r\n http://datetime.hutime.org/calendar/1001.1/era/平成
変数による指定
ical=1001.1&itype=era&ival=大正\r\n昭和\r\n平成

２－３．暦日等の情報

暦日等に関する情報は、下記の指定子を変数opropに設定する。設定が省略された場合は、暦日等を表す文字列が出力される。複数の項目を出力することも可能であり、それぞれの指定子を";"で区切る。この場合、出力形式（変数out）がtextまたはtsvの場合は、タブ区切りで、csvの場合は、カンマ区切で複数の項目が出力される。また、出力形式（変数out）がjsonの場合は、指定子を変数名とする変数に値が収容される。

分類指定子型出力内容
日付文字列text
val		文字列暦日等を表す文字列（既定値）
（変数oformで書式指定可能）
時間範囲begin暦日等期間の始点を表す暦日等
end暦日等期間の終点を表す暦日等
jdBegin数値範囲の始点を表すユリウス通日
jdEnd数値範囲の終点を表すユリウス通日
前後関係previous暦日等前の暦日等
next暦日等次の暦日等
階層関係ofEra暦日等属する年号
ofYear暦日等属する暦年
ofMonth暦日等属する暦月
暦リソースuri
url
iri		文字列暦リソースのURI
label文字列暦リソースのラベル
その他dayDuration数値期間の長さ（日数）
calendarDuration文字列期間の長さ（+年数-月数-日数）
isLeap真偽値閏であるかの正否

出力される項目の型が暦日等である場合、その出力に対して再帰的に出力項目を指定することができる。たとえば、暦日のnext（つまり、翌日）は当然暦日であり、これに対する出力項目を指定して、「翌日の暦リソースのURI」を出力することができる。この場合、指定子を"."で繋ぎ、"next.uri"となる。さらに"next.next.uri"とすれば「翌々日の暦リソースのURI」を出力することもできるが、サーバへの負担を軽減するため、繋げられる指定子の数は3つまでに制限されている。

２－４．結果の出力

出力形式は変数outに以下の指定子を設定する。いずれも、出力されるデータの文字コードはUTF-8である。

分類 指定子 内容
テキスト text
 生のテキスト（既定値）
入力データ（暦日等）ごとに、改行（CRLF）で区切られる。複数の出力項目を指定した場合は、タブで区切られる。tsvと同じだが、項目行はない。
csv カンマ区切りテキストファイル（CSVファイル）
入力データ（暦日等）ごとに、レコードが生成される。1行目は項目行。
tsv タブ区切りテキストファイル（TSVファイル）
入力データ（暦日等）ごとに、レコードが生成される。1行目は項目行。
json JSONデータファイル
入力データ（暦日等）ごとに、オブジェクトが生成され、配列として返される。各オブジェクトは、出力項目の指定子を変数名とする変数を持ち、それぞれに値が収容される。
RDF rdf リクエストのcontent-typeにより異なる
application/json： JSON形式のRDFデータファイル（rdf/json）
それ以外： XML形式のRDFデータファイル（rdf/xml）
rdf/xml XML形式のRDFデータファイル
rdf/turtle turtle形式のRDFデータファイル
rdf/json JSON形式のRDFデータファイル
rdf/ntriple N3形式のRDFデータファイル

出力形式の設定が省略された場合は、リクエストヘッダのcontent-typeの設定値により、以下のとおりとなる。

  • application/json： JSONデータファイル（json）
  • それ以外： 生のテキストデータ（text）

２－５．エラーの処理

入力データに問題があるなどで正常な処理できなかった場合、HTTPステータスコードにより以下のとおりエラー内容が返される。JSON-RPCの場合は、全て正常なHTTPレスポンスとして返され（HTTPステータスコードは200）、エラーの内容はJSON-RPCの規約に沿ってJSON形式で返される。

ステータスコードエラー内容
401 必須の変数が設定されていない、または、値が不正である。
404 該当する暦日等が無い（指定が不正である）。
413 POSTメソッドによるアクセス時に、ボディの長さが制限を超えている。

３．各処理の詳細

３－１．暦日等に関する情報の取得

変数opropの設定に基づいて、暦日等を表す文字列（日付文字列）、期間、前後関係や階層関係、閏の有無などの情報を取得する。

変数

method
必須
処理の種類。"info" を設定。
iuri または ical, itype, ival, iform
必須
情報を取得する暦日等。詳細は暦日等の指定を参照。
oprop
省略可
出力項目。詳細は暦日等の情報を参照。
out
省略可
出力形式。詳細は結果の出力を参照。

結果

変数opropで指定した項目の内容。

使用例

ivalに改行で区切られた3つの暦年を表す文字列が入力されており、これらは一括で処理される。出力される文字列の書式は変数 oformに設定されており、バラバラな書式で表された3つの暦年が算用数字の暦年と干支を組み合わせた書式に統一される。

各変数の値
method = info
ical = 1001.1
itype = year
ival = 延宝八年\r\n元禄15年\r\n宝永己丑
oform = gy年yE
結果
延宝8年庚申\r\n元禄15年壬午\r\n宝永6年己丑

３－２．暦法の変換

暦日等を異なる暦法の暦日等に変換する。

変数

method
必須
処理の種類。"conv" を設定。
iuri または ical, itype, ival, iform
必須
変換元の暦日等。詳細は暦日等の指定を参照。
ocal
省略可
変換先の暦法を暦法IDにより指定する。省略され場合は、変換元の暦法と同じ暦法が用いられる。
ep
省略可
暦法変換時に変換元の始点・終点のいずれを基準にするかを指定する。省略された場合は、始点（"b"）が用いられる。
epの設定値変換の基準となる端点
b始点（既定値）
e終点
be
eb		始点と終点
両者の結果が改行（CRLF）で区切られて返される。beとebでは出力の順番が変わる。
otype
省略可
変換先の暦日等の型を指定する。詳細は暦日等の指定を参照。省略された場合は、変換元と同じ型に変換される。
oprop
省略可
変換された暦日等に関する出力項目。詳細は暦日等の情報を参照。
out
省略可
出力形式。詳細は結果の出力を参照。

結果

変換された暦日等に関して、変数opropで指定した項目の内容。

使用例

「元禄年間」に対応する西暦年を得る。変換の基準になる端点は，始点と終点の両方が指定されているため（変数 ep）， それぞれに対応する2つの西暦年が改行で区切られて出力される

各変数の値
method = conv
ep = be
iuri = http://datetime.hutime.org/calendar/1001.1/era/元禄
ocal = 101.1
otype = year
結果
C.E. 1688\r\nC.E. 1704

３－３．暦日等への期間の加算

「元禄14 年3 月14 日の22 か月後」など、暦日等に期間を加算し、その結果の暦日等を得る。起点または加算する期間のいずれかを複数指定できる。両方を複数指定した場合は、起点の最初の暦日等に対して複数の期間が加算される。

変数

method
必須
処理の種類。加算する期間を日数で表す場合は、"addDays"、年数＋月数＋日数で表す場合は、"addCal"を設定。
iuri または ical, itype, ival, iform
必須
加算の起点となる暦日等。詳細は暦日等の指定を参照。
ical2
省略可
加算する期間を年数＋月数＋日数で表す場合に、年数、月数を計算する暦法を暦法IDにより指定する。省略され場合は、起点の暦日等の暦法と同じ暦法が用いられる。
ival2
必須
加算する期間
日数で表す場合：日数を表す数値。負の値を指定した場合は～日前を表す。
年月日数で表す場合：[符号][年数]-[月数]-[日数]で表す（例：+42-09-21 － 42年9か月21日後）。符号が負（"-"）の場合は、前に遡る（例：-42-09-21 － 42年9か月21日前）。複数指定する場合は、改行で区切る。
ep
省略可
期間の加算にどの端点を使用するかを指定する。省略された場合は、起点の始点～対象点の始点（"bb"）で計算される。
epの設定値変換の基準となる端点
bb起点の始点～対象点の始点（既定値）
ee起点の終点～対象点の終点
be起点の始点～対象点の終点
eb起点の終点～対象点の始点
otype
省略可
出力される暦日等の型を指定する。詳細は暦日等の指定を参照。省略された場合は、起点と同じ型の暦日等が出力される。
oprop
省略可
出力項目。詳細は暦日等の情報を参照。
out
省略可
出力形式。詳細は結果の出力を参照。

結果

期間を加算された暦日等に関して、変数opropで指定した項目の内容。

使用例

元禄14年3月14日の22か月後の暦日を得る。加算される期間は和暦に基づいており（変数ical2）、22か月間は、年数、月数、日数の順で、"+0-22-0"と表現される（変数 ival2）。閏月（元禄15年閏8月）を含めた月数が計算される。

各変数の値
method = addCal
ep = bb
ical = 1001.1
itype = date
ival = 元禄14年3月14日
ical2 = 1001.1
ival2 = +0-22-0
結果
元禄15年12月14日

３－４．二つの暦日等の間の期間の長さの取得

寛文7年8月11日と元禄14年3月14日の間は和暦で数えて何年何か月と何日」など、二つの暦日等（起点～対象点）の間の期間の長さを得る。起点または対象点のいずれかを複数指定できる。両者を複数指定した場合は、最初の起点と複数の対称点の間の期間について長さを計算する。

変数

method
必須
処理の種類。取得する期間を日数で表す場合は、"durDays"、年数＋月数＋日数で表す場合は、"durCal"を設定。
iuri または ical, itype, ival, iform
必須
求める期間の起点となる暦日等。詳細は暦日等の指定を参照。
iuri2 または ical2, itype2, ival2, iform2
一部省略可
求める期間の対象点となる暦日等。詳細は暦日等の指定を参照。ical2とitype2は省略可能であり、省略された場合は、それぞれ起点と同じ暦法および型が用いられる。
ocal
省略可
取得する期間を年数＋月数＋日数など暦法に基づいて表す場合、年数、月数を計算する暦法を暦法IDにより指定する。省略された場合は、起点と同じ暦法が用いられる。
ep
省略可
期間の計算にどの端点を使用するかを指定する。省略された場合は、起点の始点～対象点の始点（"bb"）が使用される。
epの設定値計測に使用する端点
bb起点の始点～対象点の始点（規定値）
ee起点の終点～対象点の終点
be起点の始点～対象点の終点
eb起点の終点～対象点の始点
odur
省略可
取得する期間を年数＋月数＋日数など暦法に基づいて表す場合に、期間を表す型を指定する。省略された場合は、年月日数（"ymd"）が使用される。
odurの設定値期間を表す型
ymd±[年数]-[月数]-[日数]（規定値）
md±0-[月数]-[日数]
yd±[年数]-0-[日数]
d±0-0-[日数]
out
省略可
出力形式。詳細は結果の出力を参照。

結果

起点と対象点の間の期間。期間を日数で表す場合（method = durDays）は、その数値が、年月日数で表す場合（method = durCal）は、odurの設定にしたがって期間を表す文字列が返される。計算に用いた対象点の端点が起点の端点よりも前の場合は、符号はマイナスとなる。

使用例

徳川綱吉の将軍在位期間を計算する（延宝8年7月18日～宝永6年1月10日）。出力される期間は、28年5か月23日間を示す。在位期間を求めるため、端点は始点から終点が指定されている。

各変数の値
method = durCal
ep = be
ical = 1001.1
itype = date
ival = 延宝8年7月18日
ical2 = 1001.1
itype2 = date
ival2 = 宝永6年1月10日
結果
+28-5-23

３－５．二つの暦日等の相対関係の取得

二つの暦日等の時間軸上の相対関係をAllen’s Time Interval Algebra に基づいて取得する。下図のA、Bいずれかについて、複数の暦日等を入力することが可能である。両者を複数入力した場合は、最初のAの暦日等について、複数のBの暦日等が比較される。

Allen's Time Interval Algebra
Allen's Time Interval Algebra, Allen (1983)より

変数

method
必須
処理の種類。"comp" を設定。
iuri または ical, itype, ival, iform
必須
比較の起点となる暦日等。上図のAに相当。詳細は暦日等の指定を参照。
iuri2 または ical2, itype2, ival2, iform2
一部省略可
比較の対象点となる暦日等。上図のBに相当。詳細は暦日等の指定を参照。ical2とitype2は省略可能であり、省略された場合は、それぞれ起点と同じ暦法および型が用いられる。
out
省略可
出力形式。詳細は結果の出力を参照。

結果

二つの暦日等の時間軸上の相対関係。Allen's Time Interval Algebra に基づいて結果が返される。

使用例

和暦の元禄年間(1688-1704)とグレゴリオ暦の17世紀の相対関係を得る。結果のOverlappedByは、17世紀が先に始まり、両者が時間的に重なる部分を経て、元禄年間が後に終わることを示す。

各変数の値
method = comp
ical = 1001.1
itype = era
ival = 元禄
ical2 = 101.1
itype2 = century
ival2 = 17
結果
OverlappedBy

４．利用に際しての注意事項

５．参考文献