NOTICE: This draft proposal is unlikely to ever be implemented. There is a new CCS REST interface proposal and JSON event feed in progress that has supplanted this draft as the new direction.
The Event Feed is an externally-accessible XML feed of contest data supplied by a Contest Control System. The event feed is the primary way that external clients can get the state of a running contest.
Getting the feed
Connect to port 4713 and the entire feed for the contest will be sent to you. When the contest is finalized, the contest tag will be closed and the connection closed.
Connect to port 4714 and the entire feed for the contest will be sent to you, with the exception that no judgement information will be sent for runs submitted during the last hour. When the contest is finalized, the contest tag will be closed and the connection closed (but you will still not get judgements for runs submitted the last hour).
CCSs will typically send all configuration elements, followed by a set of events.
Under some circumstances configuration or event elements may be resent. These circumstances include but are not limited to:
- Changing some contest configuration, such as the start time
- Rejudgements of runs
- Fixing typos in names
Under some circumstances the connection may be dropped. These circumstances include but are not limited to:
- Removal (or reinsertion) of a time interval
When reconnecting, all elements will
If a client reconnects to the event feed it will get all configuration and events from the beginning. The client cannot assume that it will see the exact same elements after a reconnect and should discard any state constructed from the event feed prior to reconnecting.
Top level structure
The event feed is an XML document within the root element <contest>.
Within the contest element are a number of configuration items and events, each of which are separate top-level elements:
Event types & tags:
|info||contest information and updates||Configuration|
|language||submission language information||Configuration|
|clar-response||clarification (answers to clarification requests) or broadcast messages||Event|
|submission||submission from a team||Event|
|submission-judgement||result of submission from a team||Event|
|run||judgement of individual input file for a run||Event|
|finalized||the contest standings/medals are assigned, contest is over||Event|
Other elements beyond what is documented here may also be sent, these should be ignored. This applies both at the top level and within the top-level elements.
- All child-elements are required unless otherwise documented.
- All contest-time elements are in decimal seconds.
- All timestamp elements are in decimal seconds since the Unix epoch, Jan 1st, 1970 00:00:00 UTC.
Configuration elements will be sent in the beginning of the feed. The exception to this rule is if the data in a configuration element is changed in which case it will be resent
|length||Length of contest||xsd:string HH:MM:SS|
|scoreboard-freeze-length||Length of time at the end of the contest when scoreboard is frozen||xsd:string HH:MM:SS|
|penalty-amount||Penalty time||xsd:int minutes|
|start-time||Wall-clock start time of the contest||xsd:decimal seconds (timestamp)|
Any new info element overrides earlier elements.
<info> <title>The 2010 World Finals of the ACM International Collegiate Programming Contest</title> <length>05:00:00</length> <scoreboard-freeze-length>01:00:00</scoreboard-freeze-length> <penalty-amount>20</penalty> <start-time>1265335138.26</start-time> </info>
<language> <name>C++</name> </language>
|name||Group name from groups.tsv||xsd:string|
<group> <name>Europe</name> </group>
|name||Judgement full name||xsd:string|
|penalty||True if this judgement is a failure that causes penalty time to be added||xsd:boolean|
<judgement> <acronym>WA</acronym> <name>Wrong Answer</name> <penalty>true</penalty> </judgement>
|label||Problem label, typically a single upper case letter||element||xsd:string|
A problem element is identified by it's label. If a problem element with the same label as an earlier element arrives the latter overrides the former.
<problem> <label>A</label> <name>APL Lives!</name> </problem>
|icpc-id||ID from ICPC registration system. Used to match this team to other resources, such as university logos or team pictures||optional xsd:int|
|nationality||Country code, ISO 3166-1 alpha-3||xsd:string|
|group||Group name, must match some name given in a group element||optional xsd:string|
- WF CCS must include icpc-id and group. This requirement should be put in CCS document
A team element is identified by it's team number. If a team element with the same team number as an earlier element arrives the latter overwrites the former.
<team> <n>1</n> <icpc-id>23412</icpc-id> <name>American University of Beirut</name> <nationality>LBN</nationality> <university>American University of Beirut</university> <group>Europe</group> </team>
The clar-request event is sent when a team submits a clarification request.
|id||Clarification Request ID||xsd:int|
|question||A question, typically from a team||xsd:string|
|contest-time||Contest-time when the clarification was submitted||xsd:decimal|
|timestamp||Wall-clock time when the clarification was submitted||xsd:decimal|
<clar-request> <id>1</id> <team-number>0</team-number> <question>What is the upper limit on the number of pieces of chocolate requested by the friends?</question> <category>Problem C</category> <contest-time>118.48</contest-time> <timestamp>1265335256.74</timestamp> </clar-request>
The clar response event is sent when a clar request has been answered.
|clar-request-id||Clarification Request ID||xsd:int|
|question||A question, typically from a team||xsd:string|
|answer||Judge's answer to the question||xsd:string|
|to-all||True if the response was sent to all teams||xsd:boolean|
|contest-time||Contest time when the response was submitted||xsd:decimal|
|timestamp||Wall-clock time when the response was submitted||xsd:decimal|
<clar-response> <clar-request-id>1</clar-request-id> <question>What is the upper limit on the number of pieces of chocolate requested by the friends?</question> <answer>The number of pieces will fit in a signed 32-bit integer.</answer> <to-all>true</to-all> <contest-time>118.48</contest-time> <timestamp>1265335256.74</timestamp> </clar-response>
An event sent whenever a team makes a submission.
|contest-time||Contest time when the run was submitted||xsd:decimal|
|timestamp||Wall-clock time when the submission was made||xsd:decimal|
<submission> <id>1410</id> <team-number>74</team-number> <problem-label>D</problem-label> <language>C++</language> <contest-time>17960.74</contest-time> <timestamp>1265353100.29</timestamp> </submission>
A run judgement event is sent whenever a judgement has been assigned to a run.
|contest-time||Contest time when the judgement was assigned||xsd:decimal|
|timestamp||Wall-clock time when the judgement was assigned||xsd:decimal|
|scoreboard-update||Information about scoreboard row updated as a result of this judgement||element|
Format of element scoreboard-update:
|sort-key||Sort key that represents the scoreboard in descending order. I.e. the row with the highest sort key represents the team currently in the lead. Sort keys are equal if and only if position is tied. Sort key for rows not yet seen (i.e. representing teams with no judgements so far) is zero.||xsd:integer|
|team||Team number. Must always be the same as the team number for the submission event with submission id as in the parent element. Is repeated here for simplicity for clients||xsd:int|
|solved-count||Number of solved problems||xsd:int|
|time||Total penalty time||xsd:int|
|problem||Scoreboard data for a problem||element|
Format of element problem:
|label||Problem label, typically a single upper case letter. Must match label given in some earlier problem element. Only problems where information is not false and zeroes must be listed. A label may only occur once in a given scoreboard-update||xsd:string|
|solved||Is problem with associated label solved by associated team||xsd:boolean|
|subs||Number of submissions on problem by team||xsd:string|
|time||Total penalty time on problem||xsd:string|
<submission-judgement> <submission-id>1410</submission-id> <judgement>WA</judgement> <contest-time>179.74</contest-time> <timestamp>1265353100.29</timestamp> <scoreboard-update> <sort-key>12345</sort-key> <team>23</team> <solved-count>9</solved-count> <time>825</time> <problem> <label>A</label><solved>true</solved><subs>3</subs><time>123</time> </problem> <problem> <label>B</label><solved>true</solved><subs>3</subs><time>123</time> </problem> <problem> <label>C</label><solved>true</solved><subs>3</subs><time>123</time> </problem> <problem> <label>D</label><solved>true</solved><subs>3</subs><time>123</time> </problem> <problem> <label>E</label><solved>true</solved><subs>3</subs><time>123</time> </problem> </scoreboard-update> </submission-judgement>
A run event is sent when a submission is judged against an input file.
|submission-id||Submission ID of submission that this run is part of||attribute||xsd:int|
|idx||Input file index (1-based)||attribute||xsd:int|
|count||Total number of input files||attribute||xsd:int|
|judgement||Judgement acronym. Must match an acronym given in some earlier judgement element||element||xsd:string|
|contest-time||Contest time when the test was judged||element||xsd:decimal|
|timestamp||Wall-clock time when the test was judged||element||xsd:decimal|
<run> <submission-id>1</run-id> <idx>1</idx> <judgement>WA</judgement> <count>1</count> <time>939.751724958</time> <timestamp>1265336078.01</timestamp> </run>
The finalized event is sent when the contest is finalized.
|timestamp||Wall-clock time when the contest was finalized||xsd:decimal seconds|
|last-gold||The last place to receive a gold (should always be 4 for a compliant system)||xsd:int|
|last-silver||The last place to receive a silver (should always be 8 for a compliant system)||xsd:int|
|last-bronze||The last place to receive a bronze (should often be 12 but could very possibly be something else)||xsd:int|
|comment||A comment provided during the finalization||xsd:string|
<finalized> <timestamp>1265336078.01</timestamp> <last-gold>4</last-gold> <last-silver>8</last-silver> <last-bronze>12</last-bronze> <comment>Finalized by John Doe and Jane Doe</comment> </finalized>
The following is a list of behavioural changes from the 2014 event feed:
- Removed <started> boolean from <info>
- Removed <id> from <language>
- Renamed <run> to <submission>
- Renamed <testcase> to <run>