Jump to content

XML format

The XML feed is recommended as an alternative to the standard IPTC7901 wire message format. Delivery is by FTP Pull from the Press Association’s servers.

To apply email customer.services@pressassociation.com, giving the IP address from which you are connecting.

Live and test message folders

To access the XML generated from real election events you will need to use the LIVE FTP account provided by customer services. The messages will appear in the following folders:

nominations
results

To access the test XML generated during scheduled election tests, according to the test rota advisories, please use the TEST FTP account provided by customer services. The test account will offer the same two folders, but they will be populated with test files.

Polling the folders for new files

It is necessary to poll the above folders on a regular basis for new files, by keeping track of the current list of files or most recent timestamp to see what is new. However since this is not the most efficient way to do this, a 'timestamp' file will be created or updated in each of the folders whenever a new XML file is deposited. The timestamp file is called:

.timestamp

This file contains the number of seconds since the epoch, with millisecond accuracy, such as "1405942919.30267". By regulary polling this file and using its modification time, or the epoch value within, a consumer can decide when to fully scan the folder for new XML files. When the timestamp file has been updated, new files should be looked for. It would be prudent to still scan the folder for new files periodically, but not as frequently as the pollng of the timestamp file.

Message types available

In general elections, Scottish Parliament, Welsh Assembly and European elections, the following types of data are available in XML:

  • Nominations (FPTP or Top-up)
  • Rushes (FPTP or Top-up)
  • Results (FPTP or Top-up)
  • Recount notifications
  • State of parties, including forecasts

All of the following types of data are available in XML for Northern Ireland Assembly elections:

  • Nominations
  • Rushes
  • Results
  • State of parties, including forecasts
  • Recount notification

For local council elections, the following message types are available:

  • Nominations (as numbers of seats per party across the council – we do not record the names of individual candidates or wards)
  • Results (in the same style as the nominations)
  • State of parties

For police commissioner polls and mayoral elections in London and other cities, the following message types are available:

  • Nominations
  • Results

For referendum elections, the following message types are available:

  • Rushes
  • Results
  • Recounts
  • Running totals

W3C schemas

All message types are specified by a set of W3C schema files.

Click here to download a ZIP file, which contains the following files:

  1. DataTypes.xsd – essential prerequisite for the other schema files
  2. FirstPastThePostNominations.xsd – the schema for nominations in General Elections and to first-past-the-post constituencies in the Scottish Parliament, Welsh Assembly and London Assembly
  3. TopUpNominations.xsd – the schema for nominations to top-up constituencies in the Scottish Parliament, Welsh Assembly and London Assembly
  4. FirstPastThePostRush.xsd – the schema for rush messages in General Elections and in first-past-the-post constituencies in the Scottish Parliament, Welsh Assembly and London Assembly
  5. FirstPastThePostResult.xsd – the schema for results in General Elections and in first-past-the-post constituencies in the Scottish Parliament, Welsh Assembly and London Assembly
  6. TopUpRush.xsd – the schema for rush messages in top-up constituencies in the Scottish Parliament, Welsh Assembly and London Assembly
  7. TopUpResult.xsd – the schema for results in top-up constituencies in the Scottish Parliament, Welsh Assembly and London Assembly
  8. FirstPastThePostStateOfParties.xsd – the schema for state of parties messages in General Elections and in first-past-the-post constituencies in the Scottish Parliament, Welsh Assembly and London Assembly
  9. Recount.xsd – the schema for messages announcing a recount in a constituency of a General Election or a a Scottish Parliament, Welsh Assembly or London Assembly election
  10. LocalNominations.xsd – the schema for local council nominations
  11. LocalResult.xsd – the schema for local council results
  12. LocalStateOfParties.xsd – the schema for local council state-of-parties messages
  13. ReferendumRush.xsd – the schema for referendum rushes
  14. ReferendumResult.xsd – the schema for referendum results
  15. ReferendumRecount.xsd – the schema for messages announcing a recount in a voting area in a referendum. Note that the root element is now ReferendumRecount, no longer the same as for assembly recount messages, which use Recount.
  16. ReferendumRunningTotals.xsd – the schema for running totals in a referendum
  17. STVNominations.xsd – the schema for nominations in an election which uses Single Transferable Vote or a variation thereof, which includes mayoral elections in London and other English cities, Northern Ireland Assembly elections, and elections for the heads of police forces
  18. STVResults.xsd – the schema for results in an election which uses Single Transferable Vote or a variation thereof (see above for the list of elections to which this relates)

Filenames

Elections XML messages generally follow a filename pattern that provides the election name, the message type, the constituency or area, and possibly a revision number e.g.

General_Election_result_Witney_1.xml

Messages generated in tests, where a test election has been used as a source, will have the word Test prefixed or suffixed to the election name.

Nominations for first-past-the-post and proportional representation elections

To prepare your systems for FPTP or PR elections, you will probably want to download the nominations files first from our server. There is a nominations file for each constituency or voting area, giving the details of the constituency and all the candidates standing for election there.

There may also be some additional PR Top-up seats for a mainly FPTP elections, which will be handled using the appropriate XML messages

Each nominations message has a revision number, which is present in both the filename and the message itself. Whenever nominations for a constituency are updated, a new message with a higher revision number will be made available on the server. Note that a higher revision number does not necessarily mean that the nominations have actually changed, however.

Occasionally corrections to nominations come to light only during the results operation, where suddenly we learn that there is an extra candidate, or that one has dropped out, or that a name was incorrect. In such a case, a revised nominations file for the affected constituency will automatically be made available, before the results.

Results for FPTP and PR elections

Each first-past-the-post result message gives the full details of the results in a constituency, with the numbers of votes, turnout, party shares and changes in party shares since the last election. Corrections may be sent to results messages, and these are indicated by increased revision numbers. The first version of any result has the revision number 1.

A first-past-the-post result is preceded by a rush message, which lists the candidates (corresponding to the nominations message for that constituency) and states which one has been elected. The rush message also contains the piece of text which goes out on the wire. Each rush message also has a revision number, which is the same as the number of the result message associated with it. When a correction is made to a result, a new rush message is only generated if the winning party in the correction differs from that originally announced.

Both nominations and results messages also contain a summary of the previous election results in the constituency.

Further details and message examples for FPTP and PR Top-up elections can be found here.

Making use of ‘PA IDs’ of candidates and parties

The XML message feed contains an enhancement which is not available in the other feed formats, namely unique ID numbers for each candidate and party. These can be relied upon to match candidates from nominations messages to results messages, and to uniquely identify different independent candidates. They cannot be used to match candidates between elections, though: due to the complexity of identifying that candidate J. Smith standing in constituency X in 2007 is the same J. Smith standing in constituency Y in 2011, PA’s software does not attempt to make that link, so the candidate IDs will actually be different in the two elections. For similar reasons, party IDs are also different between different elections.

Mayoral and Police Commissioner (STV) results

The results of the various police and mayoral elections, including London, come out on a per-round basis using the single transferable vote system. The results message for each numbered round includes a revision number both in its body and in its filename. Any corrections to earlier messages will be indicated by a new message appearing with a higher revision number.

Any previous rounds’ results are included in each results message, so every message should be fully usable in itself without having to archive the data from previous ones.

How the local elections messages work

A more detailed description of the local election XML can be found here.

A set of XML ‘nominations’ files will be made available on the server ahead of the election results operation. PA does not collect the names of individual candidates in local council elections, so by ‘nominations’ we only mean the numbers of seats held, seats offered, unopposed returns and candidates standing for each party. This information can be used to prepare systems in anticipation of the results coming out.

In case of any corrections, results messages contain a revision number, both in the message content (as an attribute to the root element) and in the filenames.

Sometimes corrections to nominations may come to light only during the results operation, due to incorrect information having been provided to PA by local authorities. When this occurs, a revised nominations file for the affected council should appear on the FTP server. It will have an up-to-date timestamp, but currently nominations files do not contain a revision number.

State-of-parties messages are transmitted at irregular intervals, whenever the PA elections editorial team decides to send them. The number of a state-of-parties message is included in its filename as well as in the message itself.

Referendum messages notes

A more detailed description of the referendum XML can be found here.

A referendum may consist of one or more propositions, each of which has two or more answers that may receive votes. For each area covered in a referendum event, the messages supply the chosen answers and their votes for each proposition.

The referendum rush message simply conveys the winning answer(s) for each proposition, for a given area. At this point the votes and majority are not known, so the XML simply supplies the winning answer text in the winningAnswerText attribute of the Proposition element. In the case of a tie between two or more answers, this value will be "Tied". The enclosed Answer elements also contain a 'winning' attribute that is set to true if that answer has been declared as having the most votes. In the case of a tie there will be two or more answers having this value set to true.

The referendum results messages follow the same rules as above except that the votes and majority values are also supplied. In the case of a tie the votes counts will clearly be seen to be equal for two or more answers.

The results messages always supersede the rush messages, and should be used in preference once received. Should there be a change to the winning answers or votes for an answer, the rush and results messages will be repeated but with an incremented revision number (the last part of the XML filename and also a revision attribute in the root element).

Any test XML produced by PA referendum tests, will have the suffix "Test" added to the shortText attribute of the Answer elements in both the rushes and results. You may need to configured your system to expect this suffix when parsing the XML, to help identify each answer. Messages produced for a live event will not have this suffix, and you should configure your system to expect this accordingly.

The referendum running totals message conveys the votes share and percentage gained by each answer in a proposition. It also provides a running total of areas that have voted for that answer to win. In the case of a tie break over two or more answers, the 'win' count of areas will not be incremented against those answers, although the votes and percentage figures will still be increased (since they were still gained). Instead a "Tied" element will appear within the proposition, providing the number of areas that have tied. The sum of areas that are voted for each answer to win, and those tied, will be equal to the number of results received so far.

Test XML

Please visit the example xml page to find examples of XML elections data. This includes historical data from previous elections as well as the data from previous and current tests.

Queries and comments

If you have any technical queries or comments relating to the XML message feed, please contact Press Association Customer Services, and they will quickly pass on the message to the relevant person.

Top of page