Thank you for applying to work at Democracy Works! This coding exercise is designed to show off your ability to program a small application that interacts with an API. You should spend no more than 2 hours on it and then turn it in to us. You may submit by zipping up the contents of your project's directory and emailing it to chris@democracy.works.
This is a basic "match users to their elections" app project. It is similar to the kinds of things you'd be working on at Democracy Works and uses one of our APIs.
A user is presented with an address form. When the user submits the form, your code will translate the address into some OCD-IDs (see below), query the Democracy Works Elections API for upcoming elections fo those OCD-IDs, and display to the user any elections returned.
We evaluate submissions according to the following criteria:
- The form submits
- State and place OCD-IDs are correctly generated
- The Democracy Works Elections API is called correctly
- Returned elections are displayed to the user
- The results are formatted for the user
- The code that generates OCD-IDs can be easily changed
- The project has documentation
- There are tests for some added functionality
- Functions/classes/methods are small and clearly scoped
- Names are clear
The goal is to see that you can get some working code that is readable to others. We do not expect you to complete everything on this list, nor is this list exhaustive of what would go into a "real" project (there is no consideration for failure cases, for example).
In order to reduce potential bias, your submission will be graded anonymously. To make that easier, please don't include any personally identifying information in your code or documentation.
Good addresses to use in documentation or tests include well-known places (like the White House or Disneyland) or the Democracy Works office in Brooklyn (20 Jay St, Brooklyn, NY 11201).
Project templates exist for Clojure, JavaScript, and Python. You may choose another language, or choose to not work from these templates. If you choose to not use a template, be sure to document how to run your project.
Pick a language that you're comfortable in. There are no bonus points for making a particular choice here.
The templates include some libraries for HTTP routing and HTML templating. You are encouraged to add dependencies as needed.
OCD-IDs are Open Civic Data division identifiers and they
look like this (for the state of Massachusetts):
ocd-division/country:us/state:ma
A given address can be associated with several OCD-IDs. For example, an address in Wayland, Massachusetts would be associated with the following OCD-IDs:
ocd-division/country:usocd-division/country:us/state:maocd-division/country:us/state:ma/cd:5ocd-division/country:us/state:ma/county:middlesexocd-division/country:us/state:ma/place:waylandocd-division/country:us/state:ma/sldl:13th_middlesexocd-division/country:us/state:ma/sldu:norfolk_bristol_and_middlesex
Not all of those are derivable from just the text of an address. For example, merely having an address in Wayland doesn't tell us what county it is in. But we can derive a basic set of state and place (i.e. city) OCD-IDs that will be a good starting point for this project. This entails...
- creating the state OCD-ID by lower-casing the state abbreviation and
appending it to
ocd-division/country:us/state: - creating a copy of the state OCD-ID
- appending
/place:to it - lower-casing the city value, replacing all spaces with underscores, and appending it to that
Then you should supply both OCD-IDs to your election API request, separated by a comma as shown in the example URL below.
https://api.turbovote.org/elections/upcoming?district-divisions=ocd-division/country:us/state:ma,ocd-division/country:us/state:ma/place:wayland
The upcoming elections API endpoint lives at
https://api.turbovote.org/elections/upcoming. You'll make GET
requests to it.
You'll need to supply a query string with a district-divisions
key. Its value should be comma-delimited OCD-IDs. See the example
above.
The response will be in the EDN format (commonly used in
Clojure) by default, but you can request JSON by setting your
request's Accept header to application/json if you prefer.
The API is not configured for CORS, so you won't be able to make requests from the user's browser. You'll have to have a server process to make those requests. The provided templates have you covered.
Depending on the time of year and whether it's an odd or even-numbered year, the number of elections in the system can vary wildly. We maintain an up-to-date list of OCD-IDs that will return an election until the dates they are listed under. Please refer to that for example OCD-IDs that will return an election to your app.