|
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:
...
|
|