AP VoteCast Result Files

AP VoteCast subscribers who receive VoteCast data via Elections API will receive results as separate files for each state and the national survey. The files are provided in the JSON format, using a standard file name convention. Each state survey and the national file use the same overall JSON schema. Each file has a header section that includes details on the file’s survey results, the state where each survey was conducted, how many interviews are in the survey and more.

File Name Convention

Summary_{state postal code}_{Election Code}_{Stage}_{month}_{day}_{two-digit year}_{time}.json

Where:

State postal code includes party in primary and caucus elections; for example, "IA_GOP."
Election Codes and their descriptions are listed in the table below.
Effective 2024 GE, the time is in the 24-hour format instead of the 12-hour format.

Election Codes

Code	Description
A	Democratic Primary Test
B	GOP Primary Test
C	General Election Test
D	Democratic Primary Production
G	General Election Production
O	General Election Run Off Production
R	GOP Primary Production
Q	General Election Run Off Test

Primary/Caucus Example

Summary_IA_GOP_R_1_01_15_24_0400PM.json

(2024 Iowa GOP Survey, Republican Primary Production Data, Stage 1)

General Election Examples

Summary_IA_G_1_11_03_20_0400PM.json

(2020 GE Iowa Survey, Production Data, Stage 1)

Summary_IA_G_1_11_05_24_1600.json

(2024 GE Iowa Survey, Production Data, Stage 1)

JSON Schema

Header Section

Data Element	Description
state	(String) Two-letter abbreviation followed by "_DEM" or "_GOP" in primary elections.
stage	(String) "Stage X." Ad hoc deliveries can include an additional letter; for example, "Stage 3A."
stage_description	(String) The "Stage X" description.
numberInterviews_lv	(String) The total number of interviews for voter data.
numberInterviews_nlv	(String) The total number of interviews for nonvoter data.
elecDate	The election date in YYYYMMDD format.
jTypeCode	The value is "SW" for statewide.
jNum	The value is always "0."
MarginsOfError	(Collection) Contains margins of error for all cases:
moeLikelyVoters	(Numeric) The margin of error for all cases among likely voters.
moeNonVoters	(Numeric) The margin of error for all cases among nonvoters.
raceSummaries	(Collection) Contains the information from the Summary tab:
summaryRaceID	(String) Corresponds to the AP vote count raceID.
summaryRaceType	(String) Describes the type of race; for example, "Senate General Election."
elecTypeCode	(String) Corresponds to the AP vote count raceTypeID; for example, "G" for General.
officeCode	(String) Corresponds to the AP vote count officeID.
raceCandidates	(Collection) Contains information about candidates in the race.
candidateID	(String) Corresponds to the candidate’s NPID.
candidateName	(String) Includes the first and last name, or "Another Candidate."
candidatePartyID	(String) The single-digit code for the party.
candidatePartyName	(String) The label for the party.

Detail Section

Data Element	Description
questions	(Collection) Contains the main response data:
variable	(String) The variable (question) name.
questionText	(String) The actual question text for this variable.
category	(Numeric) The type of variable.
categoryText	(String) Describes the type of variable; for example, "Demographic" or "Election Issue."
order	(Numeric) The order the variables appear in the file; used for sorting purposes.
results	(Collection) Contains one item for each summary type (horizontal/vertical) and voter/nonvoter:
raceID	(String) The race identifier.
voterType	(String) Indicates whether this collection contains voters or nonvoters.
summaryType	(String) Horizontal or vertical (sums up to 100%).
n	(Numeric) The number of completed interviews for that question/type.
catValues	(Collection) Contains the possible categories.
catValue	(Numeric) The numeric value of the response option/code/grouping.
catValueText	(String) Describes catValue.
catResponseCount	(Numeric) N size for that subgroup; horizontal crosstabs only.
candidateValues	(Collection) Contains the candidates and the data points.
candidateValue	(String) The code for the candidate; "0" for total and "444444" for no vote choice.
summaryValue	(Numeric) The data (percentage); it equals "ND" if the subgroup N<100.

Example

This example shows an extract from a sample VoteCast JSON result file for the 2024-01-15 Republican Presidential Primary in Iowa:

...