Cicero is a web service that provides electoral and school district information and their geographic boundaries.

Web services are agnostic about the systems which consume their services; they can be running Linux, Windows, Max OSX, anything. Also, web services are agnostic about the programming language that consumes them: C#, Java, PHP, ColdFusion, even Javascript.

This guide is designed to show how to get up and running using Cicero. Cicero was developed using C#, and the examples herein are written in that language. Even if you are not using C#, the examples should be clear enough that you will be able to translate the examples into code of whatever language you are using.

To use most Cicero services, first an authentication token must be obtained. This is done by requesting a token from the Cicero authentication service using your username and password.

If you are not already a Cicero user, you can obtain a free trial account here.  This account is limited to 250 credits worth of queries (generally one non-trivial call to Cicero expends one credit). The examples included here will work with the trial account.

Let us construct a basic console application to obtain a token from the service using Visual Studio 2005. Create a new console project. Right click on the project and select "Add Webreference..."

"At the "URL:" prompt enter, "http://cicero.avencia.com/avencia.Cicero.WebService.v2/AuthenticationService.asmx" and click on "go". This will cause Visual Studio to go to the WSDL description of the service and prepare to create proxy objects for you to use in programming. Give the webreference the name "AuthenticationService" and hit the "Add Reference" button.

Now we can access the proxy objects which talk to the webservice in our code. To obtain our token, we simply create an instance of the proxy object and invoke the "GetToken" method as shown below:

 

namespace ConsoleApplication1
{
 class Program
 {
 static void Main(string[] args)
 {
 string username = "YourName@YourCompany.com";
 string password = "YourPass";
 AuthenticationService.AuthenticationService auth;
 auth = new AuthenticationService.AuthenticationService();

 string token = auth.GetToken(username, password);
 Console.WriteLine("Token is: " token);
 Console.ReadKey();
 }
 }
}

 

The output is similar to the following:

 

Now that we have obtained a token from Cicero, we are now ready to use the service to obtain information. We will now demonstrate how to discover the local (city level) district ID of an address and output e-mail addresses of officials that represent that district.

Starting with our basic console application, we now need to add two more Cicero services as webreferences - the Geocoding Service and the Elected Official Query Service. Using the "Add Webreference..." dialog box viewable by right clicking on your console project, add references to the following two URLs: "http://cicero.avencia.com/avencia.Cicero.WebService.v2/GeocodingService.asmx" and "http://cicero.avencia.com/avencia.Cicero.WebService.v2/ElectedOfficialQueryService.asmx". Name them "GeocodingService" and "ElectedOfficialService" respectively.

Once the references have been added we add on to our original program as follows:

namespace ConsoleApplication1
{
    class Program
    {
        static void Main(string[] args)
        {
            string username = "YourName@YourCompany.com";
            string password = "YourPass";
            AuthenticationService.AuthenticationService auth;
            auth = new AuthenticationService.AuthenticationService();

            string token = auth.GetToken(username, password);
            Console.WriteLine("Token is: "   token);

            //Get DistrictInfo
            GeocodingService.GeocodingService gSvc;
            gSvc = new GeocodingService.GeocodingService();
            
            //Since its possible for an address to geocode to several different locations, 
            //GetDistrictsByAddress returns an array of DistrictInfo Objects
            GeocodingService.Location[] locs = 
               gSvc.GetDistrictsByAddress(token, "1234 Market St.", 
               "Philadelphia", "PA", "", "US", "LOCAL");

            //The best geocode is returned first. We will use that location.
            if (locs.Length > 0)
            {
                //It is possible for a single location to return multiple districts
                //But this usually not the case. We will only use the first district here.

                Console.WriteLine("DistrictID: "   locs[0].Districts[0].DistrictID);

                //Use the DistrictID to get the elected officials and their e-mail
                ElectedOfficialService.ElectedOfficialQueryService eSvc = 
                  new ElectedOfficialService.ElectedOfficialQueryService();
                ElectedOfficialService.ElectedOfficialInfo[] eoInfos;
                eoInfos = eSvc.GetOfficialsByDistrictIDList(token,
                   locs[0].Districts[0].DistrictID, "Philadelphia", "PA", "US", "LOCAL", false);

                foreach (ElectedOfficialService.ElectedOfficialInfo eoi in eoInfos)
                {
                    Console.WriteLine("Representative: "   
                     eoi.LastName   ", "   
                     eoi.FirstName   ": "   
                     eoi.EMail1);
                }
            }
            else
            {
                Console.WriteLine("No District Found!");
            }

            Console.ReadKey();
        }
    }
}

The program output is as follows:

Cicero has a variety of methods and objects beyond those shown in this sample. Some of the other important offerings that Cicero has are:

 

• School district information
• Legislative assembly information
• Elected official information (committee membership, address, website, etc.)
• District map image service
• District boundary information

 

For a general overview of all that Cicero offers, take a look at the object diagram. For a more detailed description of these objects and methods, the online documentation is the place to look.

 

If you have any further questions please feel free to contact us at info@cicero.com.