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.

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://www.avencia.com/Avencia.Cicero.WebService.v2/AuthenticationService.asmxand 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();
        }
    }
}

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://www.avencia.com/Avencia.Cicero.WebService.v2/GeocodingService.asmx" and "http://www.avencia.com/Avencia.Cicero.WebService.v2/ElectedOfficialQueryService.asmx". Name them "GeocodingService" and "ElectedOfficialService" respectively.

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:

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