Using CiviCRM Cicero

Planning for CiviCRM Cicero

The CiviCRM Cicero application on PowerBase is designed to check addresses and determine which political districts the address falls into. It uses the Cicero online service product from a third party data provider, Azavea, to read the contact addresses that you specify and update them with the political district information that you select. This information is searchable via Advanced Search, which means that you can pull up a list of constituents from a council district and invite them to a community meeting with their elected representative.

It 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.

The Cicero product is a paid service. Your organization pays per look up. Some districting information requires two lookups: one for legislative district and another for non-legislative districts, such as local taxing districts. At this time, the price is about 3 cents an address lookup, and the price drops per lookup depending on volume. Cicero charges for every lookup, even if data is not returned (for example, if the address used is not well formed). If enough groups are interested in a joint buy, PTP will arrange a group purchase which can lower the price per lookup. There is also a discount offer for nonprofit groups available through This is the current charge table for Cicero updates as of this writing. Check with Azavea for current prices.

Credits Nonprofit Price Price Per Lookup
5,000 donation N/A
10,000 $348 .035
25,000 $578 .023
100,000 $1,498 .015
250,000 $2,498 .010
1,000,000 $7.948 .008

To make sure that the district information you require is available for your community, you can check addresses on the Azavea live demo.

Once you decide to go ahead with using the Cicero application, the first step is to set up an account. At the same time, if your organization qualifies, you might go ahead and set up an account with to get the discount.

This document describes all the steps with setting up and operating CiviCRM. If you have questions, contact the PowerBase Support team at

Setting Up CiviCRM Cicero on PowerBase

The general idea with the CiviCRM Cicero feature is that you will select a group of individuals to be updated and that you shouldn’t need to update a contact’s district information unless your area has been redistricted or if the contact has moved.

Additionally, you may choose to configure the software to automatically update all contacts when they are first created or when they are edited. This feature is useful if you are combining CiviCRM Cicero with the Petition Email extension that automatically allows signers to email their elected officials.

At the outset, you’ll put your API key or user name and password in. You’ll also need to create a linkage map that directs the module to where the Cicero district fields will appear in your database.

Field Mapping

PTP has settled on a basic set of fields to use for both district and voter history information. It’s a Custom Data group called "Voter Info". It will appear in the voter tab of your contact record. If you don’t see it there, you can enable the field group via the Administer>Customize Data and Screens>Custom Fields menu.

This is the list of fields that we currently ship with new installations of PowerBase.

Table 2 Voter Info Fields

Field Label Data Type Field Type
Party Registration Alphanumeric Radio
If other party... Alphanumeric Text
PrecinctName Alphanumeric Text
State Voter ID Number Text
State House District Alphanumeric Text
Precinct Alphanumeric Text
City District Alphanumeric Text
State Assembly District Alphanumeric Text
State Senate District Alphanumeric Text
School District Alphanumeric Text
County District Alphanumeric Text
Congressional District Alphanumeric Text
County Name Alphanumeric Select
Voter Registration Date Date Select Date
Elections 2011 Alphanumeric CheckBox
Elections 2010 Alphanumeric CheckBox
Elections 2009 Alphanumeric CheckBox
Elections 2008 Alphanumeric CheckBox
Elections 2007 Alphanumeric CheckBox
Elections 2006 Alphanumeric CheckBox
Elections 2005 Alphanumeric CheckBox
Date of Voter Data Date Select Date
DW ID Alphanumeric Text
Van ID Alphanumeric Text
State Voter File ID Alphanumeric Text
CountyFileID Alphanumeric Text

Because you can add or subtract fields to your site, you may see a different set of fields than what appears in this table, but the basic logic should be the same. Many of these fields refer to the individual’s voter information. The fields we are interested in are highlighted.

Entering your API key or User Name and Password

To link your PowerBase site to your Cicero account, you have to enter either your Cicero API key or your Cicero username and password. We strongly recommend using the API key.

On the Cicero site, login and then click the "Profile" link. You will see a field called "API Key."

To set the API key in Powerbase, visit: Substitute your organization’s PowerBase name for the word "SITE" in the link.

You can also get to it from the Administration link on the home page of your site. Go to Administration>Configuration>CiviCRM>CiviCRM Cicero. Select the Cicero account settings tab.

Figure 1 User Name and Password Entry

If you would like all new contacts to be automatically updated when they are created, place a check mark in the "Automatically sync when a new contact is added."

You can also have each contact updated when a contact is edited by placing a check in the box labeled "Automatically sync when a new contact is edited (only if matching fields are empty)?". If an existing contact already has a value stored in the Cicero fields configured to be updated, then no lookup will take place. It only happens if there are any missing values.

These two settings are required if you are using our Petition Email extension to automatically contact elected officials when a petition is filled out. However, remember: you are charged by Cicero for every lookup.

In the "Number of contacts to sync with Cicero per cron run?", you set how many contacts are done in a batch. The cron run happens every 20 minutes, so the number of minutes it will take to sync all the contacts in your batch is Number of contacts divided by the value of this setting times 20.

Figure 2 CiviCRM Parameter Settings

Use the "CiviCRM Last Updated field" to record the date of this update in the record of the individual that is being matched. In the "Date Last Updated field" you will link to the "Date of Voter Data" in the Voter Info Custom field group.

Selection of Address type is important. CiviCRM Cicero uses this address specified here when matching individuals to their districts. Typically, home address would be first.

Your contacts may have more than one address, or they may only have an address (like a Billing address) that you do not want used when determining their district. The CiviCRM Cicero module allows you to choose which address types you want to use when determining a contact's district information. If you type "Home", then only contacts with a Home address will be updated, and if a contact has more than one address, the Home address will be the one selected. If you enter Home, followed by Main, then contacts that have a Home address will be updated based on their Home address, while contacts without a Home address but who have a Main address will have their Main address selected. Contacts without either a Home or Main address will be skipped.

Moving down the page we see that there are two tabs:

  • Legislative Districts
  • Non Legislative Districts

Legislative Districts

Click on the heading and a group of fields will be exposed. Here you will match those fields to the ones in Voter Info Custom Field Group.

Figure 3 Legislative Districts

The yellow highlighted fields are the ones we are interested in.

City/local district (based on 2010 Census) is the local city council district after redistricting. Map it to either "Ward" or "City District"

National lower house district aka House of Representatives (based on 2010 Census) is the Congressional District after redistricting. Map it to Congressional District.

State Assembly/Lower House (based on 2010 Census) is the state house of representatives or state assembly district after redistricting. Map it to State Assembly District.

State Senate or Unicameral Body (based on 2010 Census) is the state senate after redistricting. Map it to State Senate District.

Figure 4 Map Legislative Fields

Non Legislative Districts

Click on the heading and a group of fields will be exposed. These are the so called Non Legislative Districts as defined by Cicero. What this means is that they do not connect to an elected official. Cicero will hit you up for an extra charge per address when you update these fields, so update them only if you need them.

Figure 5 Map Non Legislative Fields

With the exception of County, these fields are not currently defined in the default Voter Info Custom Data Group. You can add the fields if you need them. Once you have completed setting up the mapping, click on "Save settings" to store them.

Running the CiviCRM Cicero Application

To prepare to run the Cicero application, we recommend creating one or more groups of the contacts that you need updated. Initially, this may be all the people in your city or your state. To save costs, don’t bother updating people from outside your interest area. After your initial update, you could make a group of people whose address has changed since their last update.

Once you’ve determined which records are going to be updated, it’s a good idea to select a small subset of them to run in your first batch. This allows you an opportunity to be sure that the software functions the way that you expect.

The program runs as a job in the background and you can schedule it to run at a time when your PowerBase is not in heavy use. To initiate the process, go to You can also get to it from the Administration link on the home page of your site. Go to Administration>Configuration>CiviCRM>CiviCRM Cicero.

Figure 6 Scheduling the District Match

On this page you select the group you would like to have updated. Set the time you would like the program to run and click on "Schedule CiviCRM Cicero Contact Sync".

Scheduled job runs will appear at the top of the screen.

Good Addresses

Cicero works best on addresses formatted like the following:

  • Street Address: 2801 21st Ave S
  • Additional Address 1: Ste 132E
  • City: Minneapolis
  • State: MN
  • Zip: 55407

In preliminary testing, Cicero appears to work best on addresses where datapartment/unit numbers are in a separate field from street address.


If you have questions, contact the PowerBase Support team at

Admin Tasks
Customizing PowerBase
PowerBase - General