____________________________________________________________

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

           *** Copyright BitMeister INC. 2010 ***
____________________________________________________________

□  目次

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

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

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

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


■利用規約（免責事項）--------------------------------------

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

　また、以下の規約に遵って本APIをご利用ください。
  ・プログラムによる大量アクセスは禁止いたします。
    1日につき2000件以上のリクエストが見込まれる場合は、
    以下のメールアドレスまで、事前にご相談ください。
    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=, address=
    日本国内の緯度経度、あるいは地名や住所などを指定することが出来ます。


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

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

  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=2010&month=8&day=30&lat=35.86&lng=139.64

  2. 住所を指定し、太陽と月の高度と方位角を計算
    http://labs.bitmeister.jp/ohakon/api/?mode=sun_moon_positions&year=2010&month=8&day=30&hour=16.75&address=埼玉県さいたま市

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

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


・計算結果XML例
  1. 緯度経度を指定し、日の出・日の入り、月の出・月の入り時刻を計算
    <?xml version="1.0" encoding="UTF-8" ?>
    <result>
    <version>2.0</version>
    <date>
    <year>2010</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.0</version>
    <date>
    <year>2010</year>
    <month>8</month>
    <day>30</day>
    <hour>16.75</hour>
    </date>
    <location>
    <address>埼玉県さいたま市</address>
    <coordinate>
    <lat>35.8617292</lat>
    <lng>139.6454822</lng>
    </coordinate>
    <google_maps>埼玉県さいたま市</google_maps>
    </location>
    <positions>
    <sun_azimuth>269.0</sun_azimuth>
    <sun_altitude>16.9</sun_altitude>
    <moon_azimuth>21.9</moon_azimuth>
    <moon_altitude>-33.4</moon_altitude>
    </positions>
    <moon_age>19.66</moon_age>
    <moon_phase>241.93</moon_phase>
    </result>

  3. 正午月齢を計算する
    <?xml version="1.0" encoding="UTF-8" ?>
    <result>
    <version>2.0</version>
    <date>
    <year>2010</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.0</version>
    <date>
    <year>2010</year>
    <month>8</month>
    <day>30</day>
    <hour>16.75</hour>
    </date>
    <moon_phase>241.93</moon_phase>
    </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="201">LOCATION_NOT_FOUND</error>
  リクエストで指定した地名や住所の位置情報検索に失敗しています。
  地名や住所の綴りを確認してください。
  もし正しければ、より詳細な地名や住所に変更してください。
  エラー例: address=四畳半島


・<error code="202">LOCATION_OVERLAP</error>
  リクエストで指定した地名や住所の位置情報を検索した結果、
  複数の情報がヒットしています。
  エラー例: address=おおしま


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


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


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

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


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


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