Announcing Pollster API v2

[Adam Hooper]

This change affects all API and CSV users. All API calls must change by August 2017.

Here's the new API: https://elections.huffingtonpost.com/pollster/api/v2. That explains the basics and points you to https://app.swaggerhub.com/api/huffpostdata/pollster-api/2.0.0, which lists all the API methods.

The old API still exists, and it hasn't changed. It is scheduled for deletion August 2017.

Main Changes In Pollster API v2

• We guarantee API stability. In other words, if you make a request this week and then make the same request next week and the values aren't the same, it's because A) Pollster editors edited the database; or B) you found a bug. We have nixed the possibility C) the quirky rules that govern Pollster charts have changed. Just A and B. Never C. That makes life simpler.
• We organize by "Question" and prefer "Question" to "Chart". Each "Chart" we display on the website is an amalgamation of A) a "Question", and B) Filters and other presentation parameters. The filters are proprietary as far as the API is concerned; suffice it to say, Pollster "Charts" hide lots of polling data from the user. ("Charts" also hide entire columns of data sometimes.) With the old API, there was no way to read those other data points. Now, we recommend you read them all: query the Question, not the Chart.
• We publish "raw" data (alongside our usual "Pollster-derived" data). For instance, the raw data might count "Jill Stein" where Pollster would count "Other"; or the raw data might count "Hillary Clinton, the Democrat" where Pollster would count "Clinton". Another example: the "Chart" API describes not only Pollster's estimates, but the algorithm Pollster used to generate them.
• Spreadsheets are TSV, and they're great. TSV is like CSV, except it's simpler to parse (because cells are never quoted). We have four spreadsheet endpoints, and we've documented them all. One replaces the old Chart "estimates_by_date"; the other three give various levels of detail on polling results.
• Pagination doesn't skip polls. Adding "?page=2" to URLs won't work any more. Now each response page comes with a "next_cursor" value; you should add "?cursor=[next_cursor]" to your requests, instead.

Find more details and rationale here: https://docs.google.com/document/d/1mhZklfeSDdkjTYOcd_NWTI-iGywrqBZZdxZ8OW15DXc/edit?usp=sharing

Updated Clients

Of course, what's an API without libraries? We've rewritten official Pollster clients from scratch:

• The new Ruby client mimics the API documentation very closely -- down to the method names. The TSV methods return Enumerables of Structs.
• The new Python client mimics the API documentation very closely, too. (It's eerily similar to the Ruby one.) The TSV methods return pandas.DataFrame objects. So cool.

I'm keen to help API users and API-client developers migrate to v2. Please contact me about it!

Moving Forward

Our goal is to dismantle the original API by August 2017, so our jobs become easier. Please help by migrating your code to the new API.

As always, questions and comments are welcome here!

Enjoy life,

Adam

--

Adam Hooper

adam....@huffingtonpost.com

+1-929-332-3503