Local Councils XML

This document describes XML messages that are used for local council election events that use the first-past-the-post (FPTP) system. The nomination and results coverage is focused on each party standing and the seats they have won out of the seats being offered up for election, at the entire council level rather than individual wards. The messages do not supply individual named nominations.

Message types available

For local council elections, the following types of data are available in XML:

  • Nominations
  • Results
  • State of parties

All message types are specified by a set of W3C schema files, downloadable from here.

Councils participating in an election belong to a single given type from the following set:

  • Unitary
  • Metro
  • Non-met
  • London
  • England (County council)
  • Scotland
  • Wales

The type of each council is set accordingly for the election, such that a mixture of all types maybe in use

Also, a council may be offering all, half or a third of its seats for election. The results messages provide the total and offered seats in these cases. If the council is subject to a boundary change this will be indicated, and a different number of seats will be offered than before.

Test data vs live data

When the PA is conducting local election tests, the same election entity is used as on the night. Therefore the paIdattributes for the election id, in all the XML, will be the same as on the night. The same can be said for council and party ids.

However local election test files will always start with a “Local_Test_” prefix, whilst live data files simply have a “Local_” prefix.


To prepare your systems for elections, first use the nominations files from our FTP server. There is a nominations file for each council, giving the details of the council, and all the parties standing for election.

Nominations files follow the following format:

Local_nominations_{Council name}.xml

If the election is data is from a test the filename format is:

Local_Test_nominations_{Council name}.xml

Occasionally corrections to nominations come to light before or during the results operation. In such a case, a revised nominations file for the affected constituency will automatically be made available, with the same filename.

The nominations for a council are provided in a message with an LocalElectionNominations root element, adhering to the LocalNominations.xsd

Here is an example of a nominations message for Amber Valley from the 2015 Council elections, with the filename Local_nominations_Amber_Valley.xml:

<?xml version="1.0" encoding="UTF-8"?>
  <Election date="2015-05-07" paId="49">
    <Council name="Amber Valley" paId="2915" type="Non-Met" proportion="third">
      <Party name="Conservative" abbreviation="C" paId="280" seatsHeld="22" seatsOffered="12" unopposedReturns="0" candidates="15" />
      <Party name="Labour" abbreviation="Lab" paId="281" seatsHeld="23" seatsOffered="3" unopposedReturns="0" candidates="14" />
      <Party name="Green Party" abbreviation="Green" paId="283" seatsHeld="0" seatsOffered="0" unopposedReturns="0" candidates="15" />
      <Party name="Independent/Other" abbreviation="Ind" paId="288" seatsHeld="0" seatsOffered="0" unopposedReturns="0" candidates="1" />
      <Party name="United Kingdom Independence Party" abbreviation="UKIP" paId="292" seatsHeld="0" seatsOffered="0" unopposedReturns="0" candidates="10" />
      <Party name="Liberal Democrat" abbreviation="LD" paId="282" seatsHeld="0" seatsOffered="0" unopposedReturns="0" candidates="9" />

Notes on the above example:

  1. The Election element date and paId attributes uniquely identify the election. The paId is strictly an internal PA id and will remain constant for the election event. We use the same id in tests and live data.
  2. The Council name and/or paId uniquely identifies the council, though council ids will not remain constant across separate elections.
  3. The Council type attribute indicates the council authority type as follows:
    • Unitary
    • Metro
    • Non-Met
    • London
    • England (County council)
    • Scotland
    • Wales
  4. The Council proportion element indicates the proportion of seats offered e.g. All up, Halves, Thirds. Should the council be subject to a boundary change, this is indicated by a boundaryChange attribute
  5. The Party element provides the name and paId of the party nomination, with attributes that provide the seats currently held by the party, the seats offered for election, the number of unopposed returning candidates, and the total number of candidates standing.


Results messages are sent as soon as the number of seats won by each nominated party is known, and summarise the structure of the council after these changes. Most importantly they reveal which party has held or gained control.

Live results messages for local councils follow the following filename pattern:

Local_result_{Council name}_{Revision}.xml

Whereas test messages follow the pattern:

Local_Test_result_{Council name}_{Revision}.xml

The revision number in the filename is incremented whenever a correction is made to the result, and starts from 1.

A result for a council uses a LocalElectionResult root element and adheres to the LocalResult.xsd

Here is an example of a result message from the 2015 Councils Election, using the filenameLocal_result_Amber_Valley_1.xml:

<?xml version="1.0" encoding="UTF-8"?>
<LocalElectionResult revision="1">
  <Election date="2015-05-07" paId="49">
    <Council name="Amber Valley" paId="2915" type="Non-Met" proportion="third" winningParty="C" gainOrHold="gain" sittingParty="Lab">
        <Party name="C" paId="280" seats="14" />
        <Party name="Lab" paId="281" seats="1" />
        <Party name="C" paId="280" change="+2" />
        <Party name="Lab" paId="281" change="-2" />
        <Party name="C" paId="280" seats="24" />
        <Party name="Lab" paId="281" seats="21" />

The results message repeats some of the information seen in the nominations message, but uses a new structure to convey the seats won by each party and new structure of the council. If there have been corrections to the result, the revision attribute in the root element will be incremented.

Notes on this message:

  1. The Council element provides the same details as per nominations, but also provides attributes for the winning party, gain/hold control status, and the current sitting party.
  2. The ElectedCouncillors elements provides a list of Party elements, for those parties that have won seats for their candidates. Each Party element provides the seats won figure.
  3. The Changes element also offers a list of parties, detailing the seats change for each one via the Party change attribute.
  4. Finally, the NewCouncil element provides a list of PartyElements that summarises the final structure of the council, with each Party element providing the total seats held by that party.

State of parties

At regular intervals a State of parties (SOP) message is generated, that summarises the council control gained, held and lost by the parties and the changes in seat totals. Each SOP message is generated for the number of results in so far, which is indicated by the SOP filename and within the message.

The SOP message may be generated for all councils (National), or just for councils in England, Scotland or Wales. The use of these types of regional SOP depends on the councils taking part in the election.

SOP messages for all councils follow the following filename pattern, where the ‘results total’ is the number of results so far, for all councils or a region:

Local_SOP_{Results total}.xml

Regional SOP messages follow a similar pattern, with the region of England, Scotland or Wales added e.g.

Local_SOP_England_{Results total}.xml

Whereas for a test the file format will be:

Local_Test_SOP_{Results total}.xml


Local_Test_SOP_England_{Results total}.xml

A SOP message uses the LocalStateOfParties root element and adheres to the LocalStateOfParties.xsd

Here is an example of a SOP message from the 2015 local council election, using the filename Local_SOP_279.xml:

<?xml version="1.0" encoding="UTF-8"?>
<LocalStateOfParties region="All" numberOfResults="279" totalNumberOfCouncils="279">
  <Election date="2015-05-07" paId="49" />
    <Party paId="280" name="Conservative" abbreviation="C" totalCouncils="163" changeInControl="+31" seatsWon="5530" netChangeInSeats="+570" />
    <Party paId="281" name="Labour" abbreviation="Lab" totalCouncils="74" changeInControl="-2" seatsWon="2279" netChangeInSeats="-168" />
    <Party paId="282" name="Liberal Democrat" abbreviation="LD" totalCouncils="4" changeInControl="-4" seatsWon="657" netChangeInSeats="-385" />
    <Party paId="283" name="Green Party" abbreviation="Green" totalCouncils="0" changeInControl="0" seatsWon="86" netChangeInSeats="+4" />
    <Party paId="284" name="Ratepayers or Residents" abbreviation="R" totalCouncils="1" changeInControl="0" seatsWon="65" netChangeInSeats="+2" />
    <Party paId="285" name="Liberal" abbreviation="Lib" totalCouncils="0" changeInControl="0" seatsWon="6" netChangeInSeats="-4" />
    <Party paId="286" name="British National Party" abbreviation="BNP" totalCouncils="0" changeInControl="0" seatsWon="0" netChangeInSeats="-1" />
    <Party paId="289" name="Independent Community and Health Concern and Residents" abbreviation="Ind CHC" totalCouncils="0" changeInControl="0" seatsWon="2" netChangeInSeats="-5" />
    <Party paId="288" name="Independent/Other" abbreviation="Ind" totalCouncils="0" changeInControl="-1" seatsWon="490" netChangeInSeats="-387" />
    <Party paId="290" name="Respect - The Unity Coalition" abbreviation="Respect" totalCouncils="0" changeInControl="0" seatsWon="0" netChangeInSeats="-1" />
    <Party paId="292" name="United Kingdom Independence Party" abbreviation="UKIP" totalCouncils="1" changeInControl="+1" seatsWon="206" netChangeInSeats="+87" />
    <Party paId="293" name="Vacant" abbreviation="Vacant" totalCouncils="0" changeInControl="0" seatsWon="14" netChangeInSeats="0" />
    <Party paId="294" name="English Democrats" abbreviation="Eng Dem" totalCouncils="0" changeInControl="0" seatsWon="0" netChangeInSeats="-4" />
    <Party name="No Overall Control" abbreviation="NOC" totalCouncils="36" changeInControl="-25" seatsWon="0" netChangeInSeats="0" />
    <Council name="Allerdale" paId="2914" type="Non-Met" proportion="all" />
    <Council name="Amber Valley" paId="2915" type="Non-Met" proportion="third" />
    <Council name="Arun" paId="2916" type="Non-Met" proportion="all" />
    <Council name="Ashfield" paId="2917" type="Non-Met" proportion="all" />
    <Council name="Ashford" paId="2918" type="Non-Met" proportion="all" />
    <Council name="Aylesbury Vale" paId="2919" type="Non-Met" proportion="all" />

Notes on this message:

  1. The root LocalStateOfParties element provides the number of results so far out of a total number of councils.
  2. Within the Parties element, the list of Party elements summarises the control and seats held by each party so far. Each Party element provides the total councils controlled by that party, the change in that control, the seats won so far and the change in seats.
  3. Within the CouncilsIncluded element, a list of Council elements provides the councils for which there is a result so far. This has been shortened in the example above.
  4. In SOP messages for all (National) councils the root LocalStateOfParties element will now have a region=”All” attribute. If this is not present, such as in older data, the assumption is that the SOP message is for all councils. Regional SOP messages will have a region attribute set to “England”, “Scotland” or “Wales” and will consider only those regional councils.

Making use of ‘PA IDs’ for elections, councils and parties

The XML message feed contains an enhancement which is not available in the other feed formats, namely unique ID numbers for each election, council and party. These can be relied upon to match data from nominations messages to results messages, and to uniquely identify different entities within a message. They cannot be used to match entities between elections though. Elections, councils and parties will have different PA ids between different elections.

However where the same parties are standing across different elections they are likely to have the same full name and abbreviation. Likewise, councils will have the same names unless changes have been necessary.