OpenElections logo

An Improved Metadata API

derekBy Derek Willis

It's not new, but it is improved. The Election Metadata API that we first released at the end of August has been revamped to make it easier to access specific objects and to provide more detail.

Rewritten using Tastypie, the API now provides a list of endpoints for individual states (for example, here is Maryland). That gives developers and users a roadmap for what kinds of information are available.

A common request could be for the elections in a given state. Continuing with Maryland, here are all the elections in the Old Line State contained in the OpenElections database. The responses include not only details about the elections but also about the source of the data (the organization in our parlance) and the state object itself.

While the initial release of the API provided the ability to filter elections by year, this updated version allows the use of specific dates to restrict the elections. For example, users can supply a date range in order to find elections held in Maryland in 2012. To drill down to only general elections, use the race_type filter. You can check out all of the possible filters at our GitHub repository.

For any request involving an object like election or organization or state, the response will include a meta object that includes the number of records returned.

The Metadata API is essentially dogfood for the project - it is mostly used to help other parts keep track of what we know about the availability and scope of election results. But if you find it useful, or have improvements you might like to see, let us know on GitHub, in our Google Group or on Twitter.