The Electoral API Extension on Powerbase is designed to automatically send one or more addresses in your database to a third party service and receive in return the electoral district information for that address. This district info is then inserted into the contact record, allowing you to search for contacts based on which electoral districts they reside in.
The Electoral API Extension does not provide individual voter registration information. It simply looks up an address and matches it to the districts in its database. The person at the address need not be a registered voter. Along with updating the election districts for your entire database, the extension can also be used in the online petitions module so petition signers can send emails to the elected officials that represent them. More here on that option.
Screen cast on using the Electoral feature and Petitions Demo
You can find the screen cast here.
Get a third party account
Before you can use the electoral extension, you must register with a third party account that will provide the address lookups.
You have a few options: Open States, Cicero and Google:
Open States
Open States is free! The only downside is that you can only lookup state legislative districts. Please try out their free online lookup with a few of your addresses to make sure they have reliable data for your state. If you are satisfied, you can sign up for a free account.
Once you have created an account, you should see an API key listed in our account settings:
Record the API key (it will be needed later on).
Cicero
Cicero charges a small amount per lookup, but has the most reliable data for both state senators, state representatives and city council members. Note: Before buying any credits, be sure to test a few of your addresses using Cicero's online demo. They have generally good data, but do not have 100% coverage of city council.
The Cicero product is a paid service. Your organization pays per look up. At this time, the price is about 3 - 4 cents an address lookup, and the price drops per lookup depending on volume. For current prices, see the "API credits" section on the Cicero Pricing page. The previous discount offer for nonprofit groups available through TechSoup is unfortunately discontinued.
Once you decide to go ahead with using the Cicero application, the first step is to set up an account. Once you have an account you should be issued an "API Key", which is a long, random, password. To find your key, first click "My Profile":
Then, look for the "API Key" field.
Google Civic is also free, but the data is less reliable then Cicero and, maybe Google has enough of our data already?
Install the Electoral API Extension
If the Electoral API Extension is installed, you should see a menu item under Administer -> System Settings -> Electoral API. If you do not see that menu item, it will need to be installed. To install the extension, go to Administer -> Administration Console -> Manage Extensions. On the list of potential extensions, find the one called "Electoral API". Click on Install to add it to your system. If you encounter a problem, please contact support to have the extension installed.
Once installed, the extension must be configured before you can use it.
You can configure it by going to Administer -> System Settings -> Electoral API.
Here's an example of a filled out configuration:
- Data Providers and API Keys - Only select the ones you have a key for. You should only have one provider unless you are doing something very complicated.
- Districts to Lookup - Only choose the ones you need. With Cicero, in addition to the geographic districts (State, City, Country) you also have non-geographic districts like voting, judicial, police. Do not select these unless you really need them because they require an additional lookup per address which costs an additional credit. In other words, if you select "Country, State, City" - it will cost one credit per address. If you add "judicial" it will cost 2 credits per address. If you add "judicial" and "police" it will cost three credits per address.
- Include Future Districts - Only available via Cicero - if you select this options then each value inserted into your database will have a time frame associated with it to indicate when it is active.
- Address Location For District Lookup - If a contact has multiple addresses, which one should be used for the lookup? Important: If your addresses are not uniformly coded as "Home" addresses (e.g. you have some coded as Main) then you may want to choose "Primary" for this option to ensure that an address is looked up. Otherwise, if a contact does not have a "Home" address their district info will not be looked up.
- Countries, States, Counties, and Cities - Use these options to limit the lookups. This will save you credits - if you only care about district information in a single city, setting that city and state will ensure that other addresses are not looked up.
- District lookup on address update - You can automate the lookup of district info by checking this box. Every time a new contact is added (assuming they have an address) their district info will be added. The alternative is to manually scedule a job to lookup all contacts in your database whenever you need them.
- Create Official On District Lookup - Optionally, you can create a contact in your database for every official that is matched with one of your contacts.
The extension is installed and configured. How do I test it?
You can create a scheduled job that runs once an hour and slowly makes its way through all your contacts until you have coded all of them.
You can see a list of your scheduled jobs by going to: Administer menu -> System Settings -> Scheduled Jobs. You will see a default job called "Electoral API - Districts Lookup" - you should leave that one alone. It's a reference point for how to setup your own.
You can setup your own by clicking the "Add new scheduled job" button. Be sure to choose "Electoral" from the drop down list and then type: districts in the action field.
While adding the job, you can optionally set the parameters limit, update, or groups for example:
Note: If you leave the "Active" checkbox un-checked, it will not run automatically, but you can still run it manually.
The settings are:
- Limit indicates how many contacts to look up districts for in a single run. Default: 100
- Update set to false will not look up district data for contacts that already have it. Update set to true will include contacts that have already been looked up and overwrite their existing district data. Default: false
- groups will restrict look ups to contacts in the matching pipe (|) separated list of group names.
A good place to start is to create a group with just you in it. Then, make note of the Group Title. Be sure to use limit to 1 to ensure you are the only one coded.
Then, you can manually execute the job from the Scheduled Job listings page. Simply click the "..." menu and select "Execute Now".
Did it work? How do I see the results?
Once you have run a job, you can check to see if the contacts you specified have their district information filled in.
The simplest way is to lookup a contact and then click the "Electoral Districts" tab on the side. You should see results similar to these:
You can also use advanced search to find contacts matching a given district. Click Search -> Advanced Search. Then, expand the "Custom Fields" accordian followed by the "Electoral Districts" accordian.
A search like the following would find every contact who is in the state assembly district 25.
Coding all your contacts
Once you are satisfied that it is working, you can code a larger group of contacts. However, we advise against running it manually. Instead, you can schedule a daily job. You simply have to check the "Enabled" check box. Then, set it. And, the next day check the results. You may want to disable it the next day as well. (ALthough if you forget and if "update" is set to false (or not included) it will not try to re-code existing addresses.)