____________________________________________________________

               ビットラボ
              日の出・日の入り時刻計算 Web API
                     おはこん番地は!?
                        Version 2.2
                         取扱説明

           *** Copyright BitMeister INC. 2021 ***
____________________________________________________________

□  目次

  はじめに
  利用規約
  APIの仕様について
  エラーメッセージについて
  その他

============================================================

■はじめに -------------------------------------------------

  おはこん番地は!? Web API(以下本API)は、入力された日付と場所から、
  太陽と月の出没時刻、方位角、高度、正午月齢、月相を計算し、
  結果をXMLで出力します。
  本APIは無料でご利用いただけます。


■利用規約(免責事項)--------------------------------------

  ビットラボ利用規約に準じます。
  http://labs.bitmeister.jp/term.html

 また、以下の規約に遵って本APIをご利用ください。
  ・プログラムによる大量アクセスは禁止いたします。
    同一クエリの多発が見込まれる場合、計算結果を
    キャッシュして利用するなどの対策をお願いします。
    1時間あたり1000件以上のリクエスト、または
    1日あたり3000件以上のリクエストが見込まれる場合は
    以下のメールアドレスまで事前にご相談ください。
    E-Mail: info@bitmeister.jp
    (メールアドレスの@は半角@に変更の上、送信してください。)


■APIの仕様について ----------------------------------------

・パラメータの種類
  1. 計算モード: mode=
    以下のモードを指定してください。
      sun_rise_set       : 日の出・日の入り時刻を計算します。
      moon_rise_set      : 月の出・月の入り時刻を計算します。
      sun_moon_rise_set  : 日の出・日の入り、月の出・月の入り時刻を計算します。
      sun_positions      : 太陽の方位角・高度を計算します。
      moon_positions     : 月の方位角・高度を計算します。
      sun_moon_positions : 太陽と月の方位角・高度を計算します。
      moon_age           : 正午月齢を計算します。
      moon_phase         : 月相を計算します。
      このパラメータを指定しない場合、日の出・日の入り時刻を計算します。

  2. 日付情報: year=, month=, day=
    西暦で日付を指定してください。
    2000年1月1日から2030年12月31日までの計算に対応します。

  3. 時刻情報: hour=
    時刻は小数点以下を指定することで、分単位の指定が可能です。
    例. 午後4時45分   => hour=16.75

  4. 位置情報: lat=, lng=
    日本国内の緯度経度を指定することが出来ます。

  5. 複数日一括計算: days=
    このパラメータの指定は任意です。
    1から31までの整数を指定してください。
    最大14日分の計算結果をまとめて取得することができ、
    JSONでは計算結果が配列に格納され、
    XMLでは計算結果にdate_off属性が追加されます。
    date_offにはAPIに指定した日付からのオフセットを示し、
    0から30までの整数が入ります。

・各計算モードが要求するパラメータ
  1. sun_rise_set, moon_rise_set, sun_moon_rise_set
    日付情報: year, month, day
    位置情報: lat, lng

  2. sun_positions, moon_positions, sun_moon_positions
    日付情報: year, month, day, hour
    時刻情報: hour
    位置情報: lat, lng

  3. moon_age
    日付情報: year, month, day

  4. moon_phase
    日付情報: year, month, day
    時刻情報: hour

・XMLリクエスト送信先
  https://labs.bitmeister.jp/ohakon/api
  http://labs.bitmeister.jp/ohakon/api
    HTTP(Non-SSL)は非推奨です。

・XMLリクエスト例
  1. 日の出・日の入り、月の出・月の入り時刻を計算
    http://labs.bitmeister.jp/ohakon/api/?mode=sun_moon_rise_set&year=2015&month=8&day=30&lat=35.8554&lng=139.6512

  2. 太陽と月の高度と方位角を計算
    http://labs.bitmeister.jp/ohakon/api/?mode=sun_moon_positions&year=2015&month=8&day=30&hour=16.75&lat=35.8554&lng=139.6512

  3. 正午月齢を計算
    http://labs.bitmeister.jp/ohakon/api/?mode=moon_age&year=2015&month=8&day=30

  4. 月相を計算
    http://labs.bitmeister.jp/ohakon/api/?mode=moon_phase&year=2015&month=8&day=30&hour=16.75

  5. 3日分の正午月齢を計算
    http://labs.bitmeister.jp/ohakon/api/?mode=moon_age&year=2015&month=8&day=30&days=3


・計算結果XML例
  1. 日の出・日の入り、月の出・月の入り時刻
    <?xml version="1.0" encoding="UTF-8" ?>
    <result>
    <version>2.2</version>
    <date>
    <year>2015</year>
    <month>8</month>
    <day>30</day>
    </date>
    <location>
    <coordinate>
    <lat>35.86</lat>
    <lng>139.64</lng>
    </coordinate>
    </location>
    <rise_and_set>
    <sunrise>5.187</sunrise>
    <sunset>18.211</sunset>
    <sunrise_hm>5:11</sunrise_hm>
    <sunset_hm>18:12</sunset_hm>
    <moonrise>20.638</moonrise>
    <moonset>10.103</moonset>
    <moonrise_hm>20:38</moonrise_hm>
    <moonset_hm>10:06</moonset_hm>
    </rise_and_set>
    <moon_age>19.66</moon_age>
    </result>

  2. 太陽と月の高度と方位角
    <?xml version="1.0" encoding="UTF-8" ?>
    <result>
    <version>2.2</version>
    <date>
    <year>2015</year>
    <month>8</month>
    <day>30</day>
    <hour>16.75</hour>
    </date>
    <location>
    <coordinate>
    <lat>35.8554</lat>
    <lng>139.6512</lng>
    </coordinate>
    </location>
    <positions>
    <sun_azimuth>269.0</sun_azimuth>
    <sun_altitude>16.8</sun_altitude>
    <moon_azimuth>213.7</moon_azimuth>
    <moon_altitude>36.4</moon_altitude>
    </positions>
    <moon_age>4.53</moon_age>
    <moon_phase>52.53</moon_phase>
    </result>

  3. 正午月齢
    <?xml version="1.0" encoding="UTF-8" ?>
    <result>
    <version>2.2</version>
    <date>
    <year>2015</year>
    <month>8</month>
    <day>30</day>
    </date>
    <moon_age>19.66</moon_age>
    </result>

  4. 月相
    <?xml version="1.0" encoding="UTF-8" ?>
    <result>
    <version>2.2</version>
    <date>
    <year>2015</year>
    <month>8</month>
    <day>30</day>
    <hour>16.75</hour>
    </date>
    <moon_phase>241.93</moon_phase>
    </result>

   5. 3日分の正午月齢
    <?xml version="1.0" encoding="UTF-8" ?>
    <result>
    <version>2.2</version>
    <date>
    <year>2015</year>
    <month>8</month>
    <day>30</day>
    </date>
    <moon_age date_off="0">4.53</moon_age>
    <moon_age date_off="1">5.53</moon_age>
    <moon_age date_off="2">6.53</moon_age>
    </result>

・JSONリクエスト送信先
  https://labs.bitmeister.jp/ohakon/json
  http://labs.bitmeister.jp/ohakon/json
    HTTP(Non-SSL)は非推奨です。

・JSONリクエスト例
  1. 日の出・日の入り、月の出・月の入り時刻を計算
    http://labs.bitmeister.jp/ohakon/json/?mode=sun_moon_rise_set&year=2021&month=9&day=3&lat=35.8554&lng=139.6512

  2. 太陽と月の高度と方位角を計算
    http://labs.bitmeister.jp/ohakon/json/?mode=sun_moon_positions&year=2021&month=9&day=3&hour=16.75&lat=35.8554&lng=139.6512

  3. 正午月齢を計算
    http://labs.bitmeister.jp/ohakon/json/?mode=moon_age&year=2021&month=9&day=3

  4. 月相を計算
    http://labs.bitmeister.jp/ohakon/json/?mode=moon_phase&year=2021&month=9&day=3&hour=16.75

  5. 3日分の正午月齢を計算
    http://labs.bitmeister.jp/ohakon/json/?mode=moon_age&year=2021&month=9&day=3&days=3

・計算結果JSON例
  1. 日の出・日の入り、月の出・月の入り時刻
   {
      "date":{
         "day":"3",
         "month":"9",
         "year":"2021"
      },
      "location":{
         "coordinate":{
            "lat":"35.8554",
            "lng":"139.6512"
         }
      },
      "moon_age":25.55,
      "rise_and_set":{
         "moonrise":0.863,
         "moonrise_hm":"0:52",
         "moonset":15.984,
         "moonset_hm":"15:59",
         "sunrise":5.241,
         "sunrise_hm":"5:14",
         "sunset":18.109,
         "sunset_hm":"18:07"
      },
      "version":"2.2"
   } 

  2. 太陽と月の高度と方位角
   {
      "date":{
         "day":"3",
         "hour":"16.75",
         "month":"9",
         "year":"2021"
      },
      "location":{
         "coordinate":{
            "lat":"35.8554",
            "lng":"139.6512"
         }
      },
      "moon_age":25.55,
      "moon_phase":314.65,
      "positions":{
         "moon_altitude":-8.2,
         "moon_azimuth":307.7,
         "sun_altitude":15.7,
         "sun_azimuth":267.9
      },
      "version":"2.2"
   }

  3. 正午月齢
   {
      "date":{
         "day":"3",
         "month":"9",
         "year":"2021"
      },
      "moon_age":25.55,
      "version":"2.2"
   }

  4. 月相
   {
      "date":{
         "day":"3",
         "hour":"16.75",
         "month":"9",
         "year":"2021"
      },
      "moon_phase":314.65,
      "version":"2.2"
   }

  5. 3日分の正午月齢
   {
      "date":{
         "day":"3",
         "days":"3",
         "month":"9",
         "year":"2021"
      },
      "moon_age":[
         25.55,
         26.55,
         27.55
      ],
      "version":"2.2"
   }

・計算結果の項目について
  1. lat, lng
    計算に使用した緯度経度です。

  2. sunrise, sunset
    日の出・日の入り時刻の計算結果です。
    小数点以下は10進数です。

  3. sunrise_hm, sunset_hm
    時間:分 形式に変換した日の出・日の入り時刻の計算結果です。
    分の値が1桁の場合、先頭に0を詰めます。

  4. moonrise, moonset
    月の出・月の入り時刻の計算結果です。
    小数点以下は10進数です。
    月の出、または月の入りが発生しない場合、負の値を返します。

  5. moonrise_hm;, moonset_hm
    時間:分 形式に変換した月の出・月の入り時刻の計算結果です。
    分の値が1桁の場合、先頭に0を詰めます。
    月の出、または月の入りが発生しない場合、"--:--"を返します。

  6. sun_azimuth, sun_altitude
    太陽の方位角、高度の計算結果です。
    共に単位は角度です。
    太陽が地平線よりも下にある場合、高度は負の値を取ります。

  7. moonn_azimuth, moon_altitude
    月の方位角、高度の計算結果です。
    共に単位は角度です。
    月が地平線よりも下にある場合、高度は負の値を取ります。

  8. moon_age
    正午月齢の計算結果です。

  9. moon_phase
    月相の計算結果です。
    単位は角度です。


・文字コード
  リクエスト、計算結果XMLともにUTF-8を使用します。
  必要に応じて、URLエンコードを行ってください。


・計算精度について
  時刻は日本標準時です。
  標高0メートルとして計算しています。
  山や建物などの障害物は計算に考慮していません。
  精度に関する保証はいたしませんので、あらかじめご了承ください。


■エラーメッセージについて ---------------------------------

・Code "001" - MISSING_ARGUMENT
  引数が足りません。
  指定したモードに必要な引数を確認してください。


・Code "002" - UNSUPPORTED_CHARACTER_ENCODING
  APIの対応しない文字コードがリクエストに含まれています。
  文字コードはUTF-8を使用してください。


・Code "101" - INVALID_DATE
  存在しない日付をリクエストで指定しているか、
  2000年1月1日から2030年12月までの範囲外で日付を指定しています。


・Code "102" - UNKNOWN_MODE
  指定された計算モードに対応していません。


・Code "203" - OUT_OF_SUPPORTED_REGION
  日本の東西南北端の外側にある場所を指定しています。


・Code "301" - CALCULATION_ERROR
  計算に失敗しました。


■その他 ---------------------------------------------------

・ご意見、ご要望がございましたら以下のメールアドレスまでご連絡ください
  E-Mail: info@bitmeister.jp
  (メールアドレスの@は半角@に変更の上、送信してください。)


・追加機能のご要望をいただければ、検討の上、対応いたします。


============================================================