入札履歴・落札履歴の参照システム(XML版)の仕様です。
プロコン競技部門 履歴参照ＡＰＩ(XML版) 仕様
概要
プロコン競技部門「石垣工務店」の試合に関して、参照時点での出品一覧および各チームの入札履歴を提供するＡＰＩです。
通信にはＨＴＴＰを使用し、各チームに割り当てられた認識IDをGETリクエストで指定することにより、ＡＰＩを参照することが可能です。
通信に使用する書式フォーマットはXML形式とし、文字コードはUTF-8とします。
リクエストＵＲＬ
| http://【入札履歴提供サーバアドレス】/get_procon.php?id=【認識ID】 |
【入札履歴提供サーバアドレス】は大会初日前日の受付時に配布される資料に記載される予定です。
また【認識ＩＤ】は各チームごとに割り当てられるランダムな識別文字列で、これは８月末に各校に配布される資料に同封される予定です。(※同封されておりませんでした。後日電子メールでお知らせいたします。)
【入札履歴提供サーバアドレス】および【認識ID】は大会当日までに変更される可能性がありますので、変更に柔軟に対応できる形でシステムに組み込むよう心がけてください。
（たとえば設定ファイル等による指定や起動時に指定できるようにするなど）
競技開始後や開始直前に変更される事はありませんので、その点はご安心ください。
最低でも前日の受付時から変更する事はありません。
なお、システムやＯＳによるキャッシュを回避し、常に最新の情報を取得する方法を【使用上のアドバイス】に記載しています。
必ず目を通して頂きますように、よろしくお願いいたします。
例として、入札履歴提供サーバアドレスが192.168.1.35、IDがkosen0353の場合、アクセスするアドレスは
| http://192.168.1.35/get_procon.php?id=kosen0353 |
となります。
レスポンスフィールド
具体的なレスポンスに関しては次のサンプルを参考に以下の説明をご覧ください。
コメントつきXMLサンプル
（注意：試合時にはコメントは出力されません）
返されるレスポンスフィールドは<procon>フィールド以下に2つの大きなフィールドを持ちます。
| フィールド名 | 意味 |
|---|---|
| stock | 参照時点での在庫情報 |
| order_history | 参照時点での各チームの入札履歴 |
<stock>フィールドはＡＰＩ参照時の、最新の在庫状況を出力します。
<stock>フィールドは子フィールドとして、出品されている石ごとの<item>フィールドを持ちます。
<item>フィールドの中身は以下のようになります。
| フィールド名 | 意味 |
|---|---|
| stone_type | 石の名前。アルファベット一文字が使用されます。 |
| count | 参照時点でのその石の在庫数 |
| lowest_price | 最低入札価格。これ以下の金額での入札はできません。 |
<order_history>フィールドはＡＰＩ参照時の、各チームの入札履歴を出力します。
<order_history>フィールドは子フィールドとして、参加チーム分の<item>フィールドを持ちます。
また、各チームごとの<history>フィールド以下に各入札ごとの<item>フィールを持ちます。
（わかりにくい場合は上記の「コメント付きＸＭＬサンプル」を参照しながらご覧ください）
参加チームごとの<item>フィールドの中身は以下のようになります。
| フィールド名 | 意味 |
|---|---|
| name | チーム名。UTF-8で記載された日本語文字列。 |
| history | 履歴（以下に各入札ごとの<item>フィールド） |
| history/item/order_number | その試合での入札回（例：第３回入札の場合は「３」） |
| history/item/priority | 入札時の優先順位 |
| history/item/stone_type | 石の名前。アルファベット一文字が使用されます。 |
| history/item/price | 入札価格 |
| history/item/result | 開札結果。アルファベット大文字2文字で状態が表されます。 再入札時は落札が確定されるまで出力されません。 OK : 落札成功 |
実践サンプルとして、実際の試合時には以下のようなＡＰＩが出力される予定ですので参考にしてください。
アクセス制限
故意的にサーバに負荷をかける行為を禁止するため、1試合につき１ＩＤから100回までＡＰＩを呼び出すことができる事とします。
アクセス制限回数を超えてアクセスした場合は、内容は出力されません。
また、アクセス制限を超過した過度のリクエスト（目安として200回程度以上）を送信したチームは、競技進行を妨げたと判断して失格とする場合がありますので、ご注意ください。
※ アクセス制限の仕様が変更になりました。詳細は
競技部門追加情報5 をご参照ください。
使用上のアドバイス
ＨＴＴＰリクエストではＯＳ等のソフトウェア環境の影響でレスポンスに以前アクセスした時の内容（キャッシュ）が暗黙下で適応される場合があります。
その場合、最新の競技進行情報を得ることができず、場合によっては戦略に重大な支障を来たす恐れがあります。
そのためＵＲＬ指定時には以下のように乱数を含めるなどして、常にユニークなアドレスにアクセスし、最新の情報を取得するように注意してください。
(ユニークアクセスのためのＧＥＴ指定[rnd]フィールドの使用を認めています。)
| http://【入札履歴提供サーバアドレス】/get_procon.php?id=【認識ID】&rnd=【乱数】 |
なお、乱数はアクセス時点での時刻やシステムの起動時間などでも代用可能です。
（要はアクセスごとに毎回違ったアドレスになれば良いということです）
免責事項
本ＡＰＩによる提供サービスはベストエフォートとします。
何らかのアクシデントや競技会場の問題によりサービスに遅延が発生したり、最新情報が保たれなかったりした場合においても、実行委員会では責任を負いかねますのでご了承頂きますようよろしくお願いいたします。