Contest

Use Contest to describe a contest and link the contest to the associated candidates and parties.

This document discusses Contest and its sub-entities:

• Contest
  • CandidateContest
  • PartyContest
  • BallotMeasureContest

Note: This entity is the same for pre-election data and election results feed types. It isn't used with officeholder feeds.

Contest

Contest is an abstract element with three types that get used based on the type of contest:

• CandidateContest: Use this type when a Contest involves one or more candidates for an office.
• PartyContest: Use this type when a Contest has a party list selection on the ballot.
• BallotMeasureContest: Use this type when a Contest involves one or more ballot measures.

As the results of an election are reported, you can update your feed to show different stages of the results, such as exit polls or estimates. Google provides guidance on which election stages and result types we expect. Google can ask for one or multiple stages. These stage-type values might change during election night. Set the initial feed value to the stage to start with. For more details, see ExternalIdentifiers in the Elements section.

Attributes

The following table describes the attributes for Contest:

Attribute	Required?	Type	Description
objectId	Required	ID	Unique internal identifier that's used by other elements to reference this element.

Elements

The following table describes the elements for Contest:

Element	Multiplicity	Type	Description
Abbreviation	0 or 1	string	Short name for the contest.
BallotSelection	0 or more	BallotSelection	Associates the selections on the ballot with the contest. The order of candidates or parties in Contest must be the same as they are in BallotSelection. If BallotSelection.SequenceOrder is present for every item, it's used as the default order for the selections.
BallotSubTitle	0 or 1	InternationalizedText	Subtitle of the contest, which must match how it appears on the voters' ballots.
BallotTitle	0 or 1	InternationalizedText	Title of the contest, which must match how it appears on the voters' ballots.
BallotTitle	0 or 1	InternationalizedText	Title of the contest, which must match how it appears on the voters' ballots.
ComposingContestIds	0 or more	IDREFS	Used to define a rollup contest. For example, in the US presidential general election, there's a national-level contest with composing contest IDs for each of the state-level elections. A ComposingContest needs to be on a smaller scope than its parent contest and must take place in the same round of an election.
ContestDateStatus	0 or 1	DateStatus	This element indicates scheduling updates for an election. The default value is confirmed. In most cases, it's best for the ContestDateStatus values to match the ElectionDateStatus of the Election that contains it.
ElectoralDistrictId	1	IDREF	Unique identifier for a GpUnit element. Associates the contest with a reporting unit that represents the geographical scope of the contest, such as a district. For example, for a specific contest, ElectoralDistrictId might reference a ReportingUnit that's defined for the district associated with the contest. Office also includes an optional reference that serves the same purpose. For example, for a national contest, you can reuse the same GpUnit that's defined for the country.
ExternalIdentifiers	1	ExternalIdentifiers	Associates an ID with the contest. A stable identifier is required. To provide the stage of the election results that's reported by your feed, set OtherType with a value from ContestStage.
HasRotation	0 or 1	boolean	Indicates whether the selections in the contest are rotated. If this element isn't present, the default value is false.
Name	1	string	Name of the contest as it's listed on the results report, not necessarily as it appears on the ballot.
SequenceOrder	0 or 1	integer	The default ordering of Contest elements for the purpose of displaying results. The contests are displayed according to the following rules: If two contests have identical values, they might be presented in an undefined order. All contests with a SequenceOrder are presented in that order, followed by all contests without a SequenceOrder value in an undefined order. SequenceOrder is used to order the displayed results. For example, 100 could indicate a regional contest, 200 could indicate a local contest, and so on. SequenceOrder isn't appropriate to use as the contest order on the ballot; contest order on each ballot can be preserved, however, using the BallotStyle entity, which associates ballot styles with their corresponding geopolitical units.
SubsequentContestId	0 or 1	IDREF	Used to point to a later contest in the same related set. In US elections for example, it usually points from a primary to its related general election. It can also point from a general election to a runoff election. A SubsequentContest usually has the same scope as its preceding contest.
SubUnitsReported	0 or 1	integer	The number of subunits, such as constituencies that have completed reporting votes for this contest.
SummaryCounts	0 or more	SummaryCounts	Provides a summary of miscellaneous counts associated with the contest. This includes the total number of ballots cast that contain the contest, and the total number of abstentions, overvotes, undervotes, or write-ins. The summary counts can be associated with the contest as a whole or with other lower-level reporting units through use of multiple occurrences of SummaryCounts.
TotalSubUnits	0 or 1	integer	The total number of subunits, such as constituencies that have this contest on the ballot.
VoteVariation	0 or 1	VoteVariation	The type of vote variation that's associated with the contest, such as n-of-m.
OtherVoteVariation	0 or 1	string	Used to provide a custom value when VoteVariation is other.
StartDate	0 or 1	PartialDate	The calendar start date of the contest. Use the date for when polling begins, such as 2022-11-08. The start date should only be set if the start and end date of the Contest differ from the start and end date of the Election. Note: If this attribute is set, the EndDate must also be set. Every StartDate must have a corresponding EndDate.
EndDate	0 or 1	PartialDate	The calendar end date of the contest. Use the date for when polling ends, such as 2022-11-08. The end date should only be set if the start and end date of the Contest differ from the start and end date of the Election. Note: If this attribute is set, the StartDate must also be set. Every EndDate must have a corresponding StartDate.
CountingDate	0 or 1	PartialDate	The post-voting date when counting happens for the election contest. This should only be included if the counting day is different from the last day of voting, for example the India Lok Sabha election. The common case is that counting happens on the same day as the last day of voting, that is the EndDate of the election. Note: If this attribute is set the date must be after the EndDate.

CandidateContest

Use CandidateContest to describe a contest that involves the selection of one or more candidates.

Note: This entity is the same for pre-election data and election results feed types. It isn't used with officeholder feeds.

This entity can optionally reference Office or Party by ID. We don’t support the representation of a ticket of candidates into the same contest; you can only reference one Office. So, as an example, for a President and Vice President ticket, you would need two Candidate contests. Each one would reference a different office.

Elements

The following table describes the elements for CandidateContest:

Element	Multiplicity	Type	Description
NumberElected	0 or 1	integer	The number of candidates that are elected in the contest, which is the n of an n-of-m contest. If NumberElected isn't present in the feed, a default value of 1 is used.
OfficeIds	1	IDREFS	Unique identifier for one or more Office elements. Associates an office description with the contest.
PrimaryPartyIds	0 or more	IDREFS	Unique identifier for one or more Party elements, which indicate that the Contest is part of a partisan primary. PrimaryPartyId is only meaningful in a primary election.
VotesAllowed	1	integer	The maximum number of votes or write-ins allowed per voter in this contest. If VotesAllowed isn't present in the feed, a default value of 1 is used.
Type	0 or more	ElectionType	The enumerated type of a contest, such as primary or general. The type of the Contest should only be set if it differs from the type of the Election.

Examples

XML

    <Contest xsi:type="CandidateContest" objectId="cc1-001">
      <Abbreviation>KENYAPRES</Abbreviation>
      <BallotSelection xsi:type="CandidateSelection" objectId="cs1-001-kenyatta">...</BallotSelection>
      <BallotSelection xsi:type="CandidateSelection" objectId="cs1-001-odinga">...</BallotSelection>
      <BallotSelection xsi:type="CandidateSelection" objectId="cs1-001-mudavadi">...</BallotSelection>
      <BallotSelection xsi:type="CandidateSelection" objectId="cs1-001-kenneth">...</BallotSelection>
      <BallotSelection xsi:type="CandidateSelection" objectId="cs1-001-dida">...</BallotSelection>
      <BallotSelection xsi:type="CandidateSelection" objectId="cs1-001-karua">...</BallotSelection>
      <BallotSelection xsi:type="CandidateSelection" objectId="cs1-001-kiyiapi">...</BallotSelection>
      <BallotSelection xsi:type="CandidateSelection" objectId="cs1-001-muite">...</BallotSelection>
      <BallotTitle>
        <Text language="en">President of Kenya</Text>
        <Text language="es">Presidente de Kenya</Text>
        <Text language="fr">Président du Kenya</Text>
        <Text language="id">Presiden Kenya</Text>
      </BallotTitle>
      <CountStatus>...</CountStatus>
      <CountingDate>2022-08-11</CountingDate>
      <ElectoralDistrictId>...</ElectoralDistrictId>
      <EndDate>2022-08-09</EndDate>
      <Name>President of Kenya</Name>
      <StartDate>2022-08-09</StartDate>
      <SubUnitsReported>48</SubUnitsReported>
      <SummaryCounts>...</SummaryCounts>
      <TotalSubUnits>48</TotalSubUnits>
      <VoteVariation>1-of-m</VoteVariation>
      <NumberElected>1</NumberElected>
      <OfficeIds>off9999a</OfficeIds>
      <VotesAllowed>1</VotesAllowed>
      <Type>general</Type>
    </Contest>

JSON

    "Contest": [
      {
        "@type": "CandidateContest",
        "objectId": "cc1-001",
        "Abbreviation": "KENYAPRES",
        "BallotSelection": [
          {
            "@type": "CandidateSelection",
            "objectId": "cs1-001-kenyatta",
            ...
          },
          {
            "@type": "CandidateSelection",
            "objectId": "cs1-001-odinga",
            ...
          },
          {
            "@type": "CandidateSelection",
            "objectId": "cs1-001-mudavadi",
            ...
          },
          {
            "@type": "CandidateSelection",
            "objectId": "cs1-001-kenneth",
            ...
          },
          {
            "@type": "CandidateSelection",
            "objectId": "cs1-001-dida",
            ...
          },
          {
            "@type": "CandidateSelection",
            "objectId": "cs1-001-karua",
            ...
          },
          {
            "@type": "CandidateSelection",
            "objectId": "cs1-001-kiyiapi",
            ...
          },
          {
            "@type": "CandidateSelection",
            "objectId": "cs1-001-muite",
            ...
          }
        ],
        "BallotTitle": {
          "Text": [
            {
              "value": "President and Vice-President of Kenya",
              "language": "en"
            },
            {
              "value": "Presidente y Vice-Presidente de Kenya",
              "language": "es"
            },
            {
              "value": "Président et vice-président du Kenya",
              "language": "fr"
            },
            {
              "value": "Presiden dan Wakil Presiden Kenya",
              "language": "id"
            },
            {
              "value": "राष्ट्रपति और केन्या के उपराष्ट्रपति",
              "language": "hi"
            },
            {
              "value": "Rais na Makamu wa Rais of Kenya",
              "language": "sw"
            }
          ]
        },
        "CountStatus": "...",
        "ElectoralDistrictId": "...",
        "Name": "President of Kenya",
        "SubUnitsReported": 48,
        "SummaryCounts": "...",
        "TotalSubUnits": 48,
        "VoteVariation": "1-of-m",
        "NumberElected": 1,
        "VotesAllowed": 1,
        "Type": "general"
      }
    ]

PartyContest

Use PartyContest for a contest that where voters choose a party on the ballot.

Note: This entity is the same for pre-election data and election results feed types. It isn't used with officeholder feeds.

Elements

The following table describes the elements for PartyContest:

Element	Multiplicity	Type	Description
TotalSubUnits	0 or 1	integer	The total number of associated subunits, such as precincts.
VoteVariation	0 or more	VoteVariation	The type of vote variations for the contest.
NumberElected	0 or 1	integer	The number of candidates that are elected in the contest, which is the n of a n-of-m contest. If NumberElected isn't present in the feed, a default value of 1 is used.
VotesAllowed	1	integer	The maximum number of votes or write-ins allowed per voter in this contest. If VotesAllowed isn't present in the feed, a default value of 1 is used.
OfficeIds	1	IDREFS	Unique identifier for one or more Office elements. Associates an office description with the contest.

Examples

XML

    <Contest objectId="pc20001" xsi:type="PartyContest">
      <BallotSelection objectId="ps10132" xsi:type="PartySelection">
        <PartyIds>par10132 par10133</PartyIds>
      </BallotSelection>
      <BallotTitle>
        <Text language="en">Constituency-level seat</Text>
      </BallotTitle>
      <Name>Constituency-level seat</Name>
    </Contest>

JSON

    "Contest": [
      {
        "@type": "PartyContest",
        "objectId": "pc20001",
        "BallotSelection": [
          {
            "@type": "PartySelection",
            "objectId": "ps10132",
            "PartyIds": [
              "par10132", "par10133"
            ]
          }
        ],
        "BallotTitle": {
          "Text": [
            {
              "value": "Constituency-level seat",
              "language": "en"
            }
          ]
        },
        "Name": "Constituency-level seat"
      }
    ]

BallotMeasureContest

Use BallotMeasureContest for a contest that involves ballot measures.

Note: This entity is the same for pre-election data and election results feed types. It isn't used with officeholder feeds.

Elements

The following table below describes the elements for BallotMeasureContest:

Element	Multiplicity	Type	Description
BallotTitle	1	InternationalizedText	The ballot's official title, such as Nevada Renewable Energy Standards Initiative. Make sure the BallotTitle is unique. Some referendums have a single collective title with multiple numbered questions. In these cases, the title can include the question number to distinguish between the BallotMeasureContest entities created for each question.
BallotSubTitle	0 or 1	InternationalizedText	The ballot's subtitle, if one exists.
BallotText	1	InternationalizedText	The text that appears on the ballot itself. For example: Shall Article 4 of the Nevada Constitution be amended to require, beginning in calendar year 2022, that all providers of electric utility services who sell electricity... in Nevada comes from renewable energy resources?
FullText	0 or 1	InternationalizedText	A copy of the full text of the ballot measure. Provide this element if there's additional text not included on the ballot itself. Limited to 30,000 characters. If the full text of the ballot measure is shorter than 30,000 characters and does not include any formatting that would be invalid in a feed file, include it in FullText. Also include InfoUri with an annotated URI of fulltext. Otherwise, only include the URI with a fulltext annotation.
InfoUri	0 or 1	AnnotatedUri	An annotated URI that accepts the following annotations, rather than the annotations listed elsewhere: wikipedia: A Wikipedia page about the ballot measure ballotpedia: A Ballotpedia page about the ballot measure. For example, https://ballotpedia.org/Nevada_Renewable_Energy_Standards_Initiative_(2020) official-website: The official website for the ballot measure fulltext: If there's more text than what's included on the ballot, such as a copy of the proposed law, this is a URI for the full additional text. The following is an example: https://www.nvsos.gov/sos/home/showdocument?id=5330 logo-uri: The image of the logo
SummaryText	0 or 1	InternationalizedText	A summary of the ballot measure. Consists of one to two short paragraphs and can be generated by the partner to summarize the full text of the ballot, like the following example: Requires utilities to acquire 50 percent of their electricity from renewable resources by 2030 Official Summary: EXPLANATION—This ballot measure proposes to amend Article 4 of the Nevada Constitution to require all providers of electric utility services that sell electricity to retail customers for consumption in Nevada to meet a Renewable Portfolio Standard (RPS) that would go into effect beginning in calendar year 2022 and increase gradually until the RPS reaches 50 percent in calendar year 2030. According to the Public Utilities Commission of Nevada, an RPS establishes the percentage of electricity sold by an electric utility to retail customers that must come from renewable sources.
ProStatement	0 or 1	InternationalizedText	A statement that explains what a Yes vote on this ballot measure means. It isn't an argument in favor of the measure. For example: A "yes" vote supports this initiative to require electric utilities to acquire 50 percent of their electricity from renewable resources by 2030.
ConStatement	0 or 1	InternationalizedText	A statement that explains what a No vote on this ballot measure means. It isn't an argument against the measure. For example: A "no" vote opposes this initiative, thus keeping the existing requirement that electric utilities acquire 25 percent of their electricity from renewable resources by 2025.
Type	0 or 1	BallotMeasureType	An enumerated type of a ballot measure. Select the value that best describes the ballot measure in its jurisdiction.

Examples

XML

     <Contest objectId="bmc0" xsi:type="BallotMeasureContest">
        <BallotSelection objectId="bms00" xsi:type="BallotMeasureSelection">
          <ExternalIdentifiers>
            <ExternalIdentifier>
              <Type>other</Type>
              <OtherType>stable</OtherType>
              <Value>bmc0_yes</Value>
            </ExternalIdentifier>
          </ExternalIdentifiers>
          <Selection>
            <Text language="en">Yes</Text>
          </Selection>
        </BallotSelection>
        <BallotSelection objectId="bms01" xsi:type="BallotMeasureSelection">
          <ExternalIdentifiers>
            <ExternalIdentifier>
              <Type>other</Type>
              <OtherType>stable</OtherType>
              <Value>bmc0_no</Value>
            </ExternalIdentifier>
          </ExternalIdentifiers>
          <Selection>
            <Text language="en">No</Text>
          </Selection>
        </BallotSelection>
        <BallotSubTitle>
          <Text language="en">Farm Animal Confinement Initiative</Text>
        </BallotSubTitle>
        <BallotTitle>
          <Text language="en">
            California Proposition 12, Farm Animal Confinement Initiative (2018)
          </Text>
        </BallotTitle>
        <ElectoralDistrictId>ru_ca_1</ElectoralDistrictId>
        <ExternalIdentifiers>
          <ExternalIdentifier>
            <Type>other</Type>
            <OtherType>stable</OtherType>
            <Value>bmc0</Value>
          </ExternalIdentifier>
        </ExternalIdentifiers>
        <Name>
          California Proposition 12, Farm Animal Confinement Initiative (2018)
        </Name>
        <BallotText>
          <Text language="en">
            Establishes minimum requirements for confining certain farm animals. Prohibits sales of meat and egg products from animals confined in noncomplying manner. Fiscal Impact: Potential decrease in state income tax revenues from farm businesses, likely not more than several million dollars annually. State costs up to $10 million annually to enforce the measure.
          </Text>
        </BallotText>
        <ConStatement>
          <Text language="en">No means the measure will not be enacted
          </Text>
        </ConStatement>
        <InfoUri Annotation="fulltext">
          https://example-government.gov/ballot-measures/California_Proposition_12_2018
        </InfoUri>
        <InfoUri Annotation="wikipedia">
          https://en.wikipedia.org/wiki/2018_California_Proposition_12
        </InfoUri>
        <ProStatement>
          <Text language="en">Yes means the measure will be enacted
          </Text>
        </ProStatement>
        <SummaryText>
          <Text language="en">
            The proposition establishes new minimum requirements on farmers to provide more space for egg-laying hens, breeding pigs, and calves raised for veal. California businesses will be banned from selling eggs or uncooked pork or veal that came from animals housed in ways that did not meet these requirements.
          </Text>
        </SummaryText>
        <Type>ballot-measure</Type>
      </Contest>

JSON

    "Contest": [
      {
        "@type": "BallotMeasureContest",
        "objectId": "bmc0",
        "BallotSelection": [
          {
            "@type": "BallotMeasureSelection",
            "objectId": "bms00",
            "ExternalIdentifiers": {
              "ExternalIdentifier" : [
                {
                  "Type": "other",
                  "OtherType": "stable",
                  "Value": "bmc0_yes"
                }
              ]
            }
          }
            "Text": [
              {
                "value": "Yes",
                "language": "en"
              },
            ]
        ],
        "BallotSelection": [
          {
            "@type": "BallotMeasureSelection",
            "objectId": "bms01",
            "ExternalIdentifiers": {
              "ExternalIdentifier" : [
                {
                  "Type": "other",
                  "OtherType": "stable",
                  "Value": "bmc0_no"
                }
              ]
            }
          }
            "Text": [
              {
                "value": "No",
                "language": "en"
              },
            ]
        ],
        "BallotSubTitle": {
          "Text": [
            {
              "value": "Farm Animal Confinement Initiative",
              "language": "en"
            }
          ]
        },
        "BallotTitle": {
          "Text": [
            {
              "value": "California Proposition 12, Farm Animal Confinement Initiative (2018)",
              "language": "en"
            }
          ]
        },
        "ElectoralDistrictId": "ru_ca_1"
        "ExternalIdentifiers": {
          "ExternalIdentifier" : [
            {
              "Type": "other",
              "OtherType": "stable",
              "Value": "bmc0"
            }
          ]
        },
        "Name": "California Proposition 12, Farm Animal Confinement Initiative (2018)",
        "BallotText": [
          "Text": [
            {
              "value": "Establishes minimum requirements for confining certain farm animals. Prohibits sales of meat and egg products from animals confined in noncomplying manner. Fiscal Impact: Potential decrease in state income tax revenues from farm businesses, likely not more than several million dollars annually. State costs up to $10 million annually to enforce the measure.",
              "language": "en"
            }
          ]
        ],
        "ConStatement": [
          "Text": [
            {
              "value": "No means the measure will not be enacted",
              "language": "en"
            }
          ]
        ],
        "InfoUri": [
          {
            "value": "https://example-government.gov/ballot-measures/California_Proposition_12_2018",
            "annotation": "fulltext"
          }
        ],
        "InfoUri": [
          {
            "value": "https://en.wikipedia.org/wiki/2018_California_Proposition_12",
            "annotation": "wikipedia"
          }
        ],
        "ProStatement": [
          "Text": [
            {
              "value": "Yes means the measure will be enacted",
              "language": "en"
            }
          ]
        ],
        "SummaryText": [
          "Text": [
            {
              "value": "The proposition establishes new minimum requirements on farmers to provide more space for egg-laying hens, breeding pigs, and calves raised for veal. California businesses will be banned from selling eggs or uncooked pork or veal that came from animals housed in ways that did not meet these requirements.",
              "language": "en"
            }
          ]
        ],
        "Type": "ballot-measure",
      }
    ]