____________________________________________________________

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

           *** Copyright BitMeister INC. 2015 ***
____________________________________________________________

□  目次

  はじめに
  利用規約
  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日分の計算結果をまとめて取得することができ、
    計算結果に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


・リクエスト送信先
  http://labs.bitmeister.jp/ohakon/api


・リクエスト例
  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.1</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.1</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.1</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.1</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.1</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>


・計算結果の項目について
  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メートルとして計算しています。
  山や建物などの障害物は計算に考慮していません。
  精度に関する保証はいたしませんので、あらかじめご了承ください。


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

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


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


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


・<error code="102">NOT_SUPPORTED_MODE</error>
  指定された計算モードに対応していません。


・<error code="203">OUTSIDE_OF_SUPPORTED_REGION</error>
  日本の東西南北端の外側にある場所を指定しています。


・<error code="301">CALCULATION_ERROR</error>
  計算に失敗しました。


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

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


・JSON版やcrossdomain.xmlの設置について
  ご要望をいただければ、検討の上、対応いたします。


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