All data are publicly available and free to use under the MIT license. We provide forecast data for the PollyVote and its components at the national and the state level. You may obtain the data through our API call generator, which allows you to specify your exact request via URL specification. Please do not scrape the data as it is updated multiple times per day but not necessarily regularly (i.e., hourly). Details and instructions can be found below.
Data description
Please read the page about combining forecasts first as it allows you to understand what kind of data we provide. Next, in order to retrieve the data, you need to specify various parameters, all of which are described here.
Time of data
The API allows you to obtain live data for the 2016 presidential election as well as historical data from past elections. However, historical data are only available for some components and not for all states. For an overview of availability, see the chart below. Live data is always limited: On the national level data up until a week ago is presented, on state level only data from today and the previous day is presented.
time = historical | current
That said, on the national level you can “travel back in time”. That is, you can specify the maximum age that you want data to be provided. In order to, for instance, retrieve not only the last week (i.e., 7 days) but the last three weeks (i.e., 21 days), specify a parameter displaydays and provide it with an appropriate number. Keep in mind, though, that this is limited to national-level data.
displaydays = 21
Data level
Starting with the 2016 presidential election, the PollyVote provides live data on both the national and state level. Historically, state-level data are only available for the 2012 election. This means that you can look at forecasts for the general presidential race but also at forecasts on the race in, say, Missouri. As not all states provide data for all components, forecast availability might vary.
level = national | state
Type of data
The PollyVote comprises several methods of gained knowledge from various sources of data. The forecast follows a two-step concept where similar methods are, first, aggregated into one component (e.g., all intention polls into one intention poll component). Second, all components are aggregated into the PollyVote forecast. You need to specify which data you want to receive at this point.
In addition to the PollyVote data, there is also some World Knowledge available, such as past elections’ outcomes, the candidates’ names, the number of electoral votes per state, the fact that a state is a swing state (for historical data, this is presumed post-hoc, for current/2016 data, this is based on Larry Sabato’s forecast on swing states).
type = pollyvote | polls | expectations | markets | experts | econ_models | index_models | world_knowledge
Data format
You can download the data as CSV or JSON, where the latter includes the request as object properties (i.e., time, level, and type) along the timestamp of the last update (in UNIX and ISO-8601 format) and a data property containing an array which depicts the data itself (which is exactly the same as the CSV depicts). For JSONP/JSON-P, proceed as you would do for JSON but include a callback parameter with the JavaScript function to call.
format = csv | json
API call generator
Select what you need and use the URL generated below. Basically, the URL consists of up to four _GET parameters ( time, level, type, and format) and returns the data on-the-fly. No key/authentication is necessary. Current data is updated irregularly but daily at least.
Data output
Depending on your chosen format (CSV or JSON), you’ll either get a table or an object containing a data array at position “data”. Both data collections, however, include the variables described below.
If you need JSONP/JSON-P, include a callback parameter to the JSON call (e.g., ?format=json&callback=myFunction).
Note that all variables within the datasets (i.e., the CSV and JSON files) are without any underscores. However, as this makes it harder to read, we split them for explanatory reasons in the following table.
| Variable | Description |
|---|---|
| PK_year_day_state_fc | Primary key (year, day, state, forecast) |
| PK_year_day | Primary key (year, day) |
| PK_year_day_state | Primary key (year, day, state) |
| FC_component | Component the forecast belongs to: intentions, expectations, prediction_markets, index models, econometric_models, comb_experts, comb_econometric_models, comb_index_models, comb_prediction_markets, comb_expectations, comb_intentions, PollyVote |
| Election_year | Year in which the election was held |
| Days_to_election | Number of days remaining to election day |
| FC_date | Date the forecast was published |
| State | Target area of the forecast, either national or state (indicated through two-digit abbreviation) |
| Forecast | Identifier for the forecast/source |
| n_fc_vs | Number of component forecasts in the combination |
| n_fc_win_prob | |
| n_fc_win_freq | |
| fc_ev_rep | |
| fc_ev_dem | |
| fc_winner | current winner according to forecast (R or D) |
| fc_winner_vs | current winner according to two-party vote share (R or D) |
| fc_winner_win_prob | |
| fc_winner_win_freq | |
| fc_winner_pollyvote_freq | |
| fc_rep_vs | two-party vote-share of the republican party |
| fc_dem_vs | two-party vote-share of the democratic party |
| fc_rep_win_prob | |
| fc_dem_win_prob | |
| fc_rep_win_freq | |
| fc_dem_win_freq | |
| fc_rep_win_pollyvote_freq | |
| fc_dem_win_pollyvote_freq | |
| FC_error | Forecast error (Forecast – Actual) |
| Absolute_FC_error | Absolute forecast error |
| FC_update | 1 if new or updated forecast available; otherwise 0 |
| Last_survey_day | Provides the first day a survey went into the field |
| First_survey_day | Provides the last day a survey was in the field |
| Inc_2party | Calculation of two-party incumbent vote |
| Resp_rep | Survey result for Republican candidate |
| Resp_dem | Survey result for Democratic candidate |
| Resp_oth | Survey result for other candidates |
| Resp_undecided | Survey result for respondents that indicate not to have decided yet |
| Released | Day the survey results were published |
| Sample | Sample size of survey |
| moe | margin of error |
| Question_txt | Exact wording of the question in the survey |
| Sample_desc | Information about the sample of respondents, where RV means “registered voters” and LV stands for “likely voters”. |
| Int_method | Interview method |
| Survey_org | Survey organization |
| Survey_sponsor | Survey Sponsor |
| Source_document_link | Link to the source document |
| matchup | For single forecasts which rely on direct candidate comparison (e.g., intention polls throughout the primaries), this column indicates for which candidates the values are representative for. |
Here is the same for the world knowledge results.
| Variable | Description |
|---|---|
| PK_year_state | Primary key (year, state) |
| election_year | Year of election |
| state | state (or National) |
| election_date | exact date of election |
| inc_party | party of the incumbant (D or R) |
| inc_person | name of the incumbant |
| inc_person_short | short name (nick name) of the incumbant |
| inc_image | link to an image of the incumbant which is free to use |
| inc_image_credit | credits to state under/near the image |
| inc_gender | incumbant candidate’s gender (m or f) |
| dem_person | name of the Democratic candidate |
| dem_person_short | short name (nick name) of the Democratic candidate |
| dem_image | link to an image of the Democrat which is free to use |
| dem_image_credit | credits to state under/near the image |
| dem_gender | Democrat candidate’s gender (m or f) |
| rep_person | name of the Republican candidate |
| rep_person_short | short name (nick name) of the Republican candidate |
| rep_image | link to an image of the Republican which is free to use |
| rep_image_credit | credits to state under/near the image |
| rep_gender | Republican candidate’s gender (m or f) |
| win_party | D or R, representing the winning party |
| dem_pop | popular vote of the Democrats |
| rep_pop | popular vote of the Republicans |
| dem_elecoral | electoral votes of the Democrats |
| rep_elecoral | electoral votes of the Republicans |
| dem_vs | two-party vote-share of the Democrats |
| rep_vs | two-party vote-share of the Republicans |
| swing_state | 1 if given state is a swing state (for historical data, this is presumed post-hoc, for current/2016 data, this is based on Larry Sabato’s forecast on swing states) |
| electoral_votes | total number of electoral votes for the given state in this year |
Data availability
As the PollyVote is based on other forecasts, data availability is largely dependent on other data sources. Hence, not all combinations of data types, geographical, and time dimensions are available. The following table shows a list of currently available combinations.
| Type of Data | Time of Data | National Level | State Level |
|---|---|---|---|
| PollyVote forecast | historical | yes | yes |
| 2016 | – | – | |
| PollyVote electoral votes | historical | – | yes |
| 2016 | – | – | |
| Combined Components | |||
| quantitative econometric models | historical | yes | yes |
| 2016 | yes | – | |
| quantitative index models | historical | yes | – |
| 2016 | yes | – | |
| expectation polls (citizen forecasts) | historical | yes | yes |
| 2016 | yes | – | |
| intention polls | historical | yes | yes |
| 2016 | yes | – | |
| experts | historical | yes | – |
| 2016 | yes | – | |
| prediction markets | historical | yes | yes |
| 2016 | yes | – | |
| Single Sources | |||
| quantitative econometric models | historical | yes | yes |
| 2016 | yes | – | |
| quantitative index models | historical | yes | – |
| 2016 | yes | – | |
| expectation polls | historical | yes | yes |
| 2016 | yes | – | |
| intention polls | historical | yes | yes |
| 2016 | yes | – | |
| experts | historical | – | – |
| 2016 | – | – | |
| prediction markets | historical | yes | – |
| 2016 | yes | – | |
| World Knowledge | |||
| world knowledge | historical | yes | yes |
| 2016 | yes | yes | |
The MIT License (MIT)
Copyright (c) 2015-2016 LMU Munich (Dr. Andreas Graefe, Mario Haim)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.