API


Register

Before users are allowed to use the API, they first have to register with a valid E-mail, then confirm it.

Once users have confirmed their email address, they have a limited number of API calls they can make in a day. Users are advised to store API results locally so they wont have to keep consuming the API each time they needed data.

Generate API

Once a user confirms their email, they can immediately start to use the API.
To reduce the chances of URL/API errors, users can Login to their account, then click on the second tab Generate API

When you start typing into the County, State text box to get the specific county and state you want, then choose the type of election you want. The URL is automatically generated for you.

A typical URL looks like this:

API URL Attributes

https://electionsbycounty.com/ Website Domain
api -
v1.0 API Version
xxxxxxxxxxxxxxxxxxxx Unique 20 character API Code
elections -
IN US State abbreviation
Wayne County name
President Type of Election

Successful API calls returns a JSON response. A typical response comprises of the following:

JSON Result Attributes

TypeOfElection
String
This is the type of Election you requested for. President, Senate, Governorship...
State
String
2 Char abbreviation of US State for the County data you requested. IN, IL, TX
Date
String
Date on which an election was held. YearMonthDay. No separators. Only digits 20121106
AreaName
String
Name of the county data you requested. Wayne, Washington, Jefferson, Loving
AreaType
String
Name of the administrative divisions. Counties, Boroughs, Parishes, Ward.....
TotalVotes
Integer
This is the summation of all recorded votes of a type of election for a specific county.
RepublicanVotes
Integer
Total number of Republican party votes
RepublicanCand
String
Name of the Republican candidate
DemocraticVotes
Integer
Total number of Democratic party votes
DemocraticCand
String
Name of the Democratic party candidate
ThirdParty
String
Name of the front running third party
ThirdPartyVotes
Integer
Total number of third party votes
ThirdPartyCand
String
Name of the Third party candidate
OtherVotes
Integer
Total number of ALL other votes that are NOT Republican, Democrat or Third party

API Usage

C#
PHP
Python
R

Error Messages

All error messages are returned as

Maximum API calls

Once an account has reached it's maximum number of API calls in a day, if they try to make further requests, error message displayed is

Invalid API Code

After email confirmation, each user is issued a unique 20 character long alphanumeric API Code. This code is used as part of the API call. If this code is malformed in anyway i.e. one or more characters short or too many, your request will return

Data Unavailable

You get this error when you request for data that is not available in the database. This happens when you attempt to generate API URL without using the utility function in your Account Dashboard:

Incorrect Version Number

This application uses version number as part of it's API URL string, we currently are running version v1.0. If this exact version number is missing or not in correct order, you get the following error message:

Unconfirmed Email

Users who registered an account should confirm their email before they attempt to use the API service. If they try to use the API before confirming, they get this error message: