Zip Codes - Tutorial

So you are interested and would like to integrate Zip Codes web service into your application. This tutorial will give all the necessary information about how to use Zip Codes web service. There are three types of data that Zip Codes web service provide: zip code, city and area code. There are number of possible uses of the Zip Codes web service:
- Find zip codes or cities within specified distance from any zip code or city
- Find user-defined locations (such as offices or stores) around zip code or city
- Find zip codes that cover a specific city or find a cities that specific zip code covers
- Find distance between 2 zip codes or cities
- Retrieve zip code or city coordinates
- Find area codes that cover a zip code or a city
To get started go through the following 5 step tutorial:

Connecting to Zip Codes web service
In order to use a web service you need to know its WSDL definition. Zip Codes web service WSDL is here http://codebump.com/services/placelookup.asmx?wsdl
For users who orignially implemented the older version of the service there's a WSDL for backward compatibility (only use it if you already developed against the older version and don't want to upgrade) http://codebump.com/services/zipcodelookup.asmx?wsdl
URLs above return a standard WSDL 1.1 that can be plugged in directly into your SOAP toolkit. For instructions on how to do it with your particular toolkit follow to step 4.

List of functions
+ Current Interface (click to expand/collapse)

+ GetPlacesWithin (place, state, distance, placeTypeToFind) - proximity search for zip codes, cities, area codes and FSAs (Forward Sorting Areas aka 3-digit zip codes).

Parameters:

place - place name (65 char max)
state - 2 letter state code (not required for zip codes)
distance - distance in miles
placeTypeToFind - type of place to look for: ZipCode, City (including any villages, towns, etc),
		AreaCode or ThreeDigitZipCode (unique 3-digit zip codes)

Example:

GetPlacesWithin ("90210", "", 20, "City")
GetPlacesWithin ("Beverly Hills", "CA", 20, "ZipCode")

+ GetPlacesWithinFiltered (place, state, distance, placeTypeToFind, filter, filterType) - proximity search and filter for zip codes, cities and FSAs.

Parameters:

place - place name (65 char max)
state - 2 letter state code (not required for zip codes)
distance - distance in miles
placeTypeToFind - type of place to look for: ZipCode, City (including any villages, towns, etc),
		AreaCode or ThreeDigitZipCode (unique 3-digit zip codes)
filter - string to filter results
filterType - type of filter (StartsWith, EndsWith, Anywhere, None)

Example:

GetPlacesWithinFiltered ("90210", "", 20, "City", "hills", "Anywhere")
GetPlacesWithinFiltered ("Beverly Hills", "CA", 20, "ZipCode", "90", "StartsWith")

+ GetPlacesInside (place, state) - find all places (cities, villages, etc.) covered by a zip code or all zip codes covering a place. If zip code is passed in then cities with that zip code are returned. If a city/state is passed in then zip codes in that city are returned.

Parameters:

place - place name (65 char max)
state - 2 letter state code (not required for zip codes)

Example:

GetPlacesInside ("90210", "")
GetPlacesInside ("Beverly Hills", "CA")

+ GetDistanceBetweenPlaces (place1, state1, place2, state2) - find distance between 2 places.

Parameters:

place1 - place name (65 char max)
state1 - 2 letter state code (not required for zip codes)
place2 - place name (65 char max)
state2 - 2 letter state code (not required for zip codes)

Example:

GetDistanceBetweenPlaces ("90210", "", "Los Angeles", "CA")
GetDistanceBetweenPlaces ("Beverly Hills", "CA", "90012", "")

+ GetPlacesDetails (place, state) - returns place details such as name, type, state and coordinates.

Parameters:

place - place name (65 char max)
state - 2 letter state code (not required for zip codes)

Example:

GetPlacesDetails ("90210", "")
GetPlacesDetails ("Beverly Hills", "CA")

+ GetUserPlacesWithin (place, state, distance, category) - proximity search for user-defined places.

Parameters:

place - place name (65 char max)
state - 2 letter state code (not required for zip codes)
distance - distance in miles
category - category of user-defined places to return 
	(can be anything: office, stores, HomeDepot, etc)
	User-defined places must be first uploaded through 
	this web site or SaveUserPlaces function (see below)

Example:

GetUserPlacesWithin ("90210", "", 20, "HomeDepot")
GetUserPlacesWithin ("Beverly Hills", "CA", 20, "MyOffices")

+ FindPlacesAroundAreaCode (areaCode, distance, placeTypeToFind) - proximity search for area codes.

Parameters:

areaCode - area code
distance - distance in miles
placeTypeToFind - type of place to look for: ZipCode, City (including any villages, towns, etc)
		or ThreeDigitZipCode (unique 3-digit zip codes)

Example:

FindPlacesAroundAreaCode (929, 20, "ZipCode")

+ FindPlacesAroundAreaCodeFiltered (areaCode, distance, placeTypeToFind, filter, filterType) - proximity search and filter for area codes.

Parameters:

areaCode - area code
distance - distance in miles
placeTypeToFind - type of place to look for: ZipCode, City (including any villages, towns, etc)
		or ThreeDigitZipCode (unique 3-digit zip codes)
filter - string to filter results
filterType - type of filter (StartsWith, EndsWith, Anywhere, None)

Example:

FindPlacesAroundAreaCodeFiltered (929, 20, "City", "hills", "Anywhere")

+ SaveUserPlaces (places) - uploads and saves user-defined places.

Parameters:

places - an array of user-defined places UserPlaceDetail.
	UserPlaceDetail is an object describing a user place, it has following properties:
		Id - read-only number assigned by the database
		Name - string describing the place ("Head Office", "LA Location", etc), required
		Address - street address
		City - city name, required if ZipCode is not supplied
		State - 2 letter state code, required if City is supplied
		ZipCode - 5 digit zip code or Canadian postal code, required if City is not supplied
		Category - user assigned category, it allows to maintain different sets of locations
		Data - can be used to store extra data
		LatDegrees - latitude in degrees
		LonDegrees - longitude in degrees
		LatRadians - latitude in radians
		LonRadians - longitude in radians
		Distance - not used for this function
	Each UserPlaceDetail must have a set of coordinates, if City and State or ZipCode are supplied
	then coordinates will automatically be calculated from them. If City, State and ZipCode are
	empty then LatDegrees/LonDegrees or LatRadians/LonRadians must be filled in

Example:

UserPlaceDetail[] places = new UserPlaceDetail[0];
places[0].Name = "Head office";
places[0].City = "Beverly Hills";
places[0].State = "CA";
SaveUserPlaces (places);

+ GetAllUserPlaces () - returns an array of all user-defined places.

Parameters:

none

Example:

GetAllUserPlaces ()

+ Older interface (click to expand/collapse)

+ GetZipCodesWithin (zip, distance) - proximity search for zip codes.

Parameters:

zip - 5 digit US zip code or Canadian postal code (M3H, M3H 6A7)
distance - distance in miles

Example:

GetZipCodesWithin ("90210", 20)
GetZipCodesWithing ("M3H 6A7", 20)

+ GetZipCodesWithinFiltered (zip, distance, filter, filterType) - proximity search for zip codes and filter results at the same time.

Parameters:

zip - 5 digit zip code or Canadian postal code (M3H, M3H 6A7)
distance - distance in miles
filter - string to filter results
filterType - type of filter (StartsWith, EndsWith, Anywhere, None)

Example:

GetZipCodesWithinFiltered ("90210", 20, "9", "StartsWith")
GetZipCodesWithing ("M3H 6A7", 20, "6A", "Anywhere")

+ GetThreeDigitZipCodesWithin (zip, distance) - proximity search for FSAs (Forward Sortation Areas aka 3-digit zip codes).

Parameters:

zip - 3 digit zip code or Canadian postal code (M3H, M3H 6A7)
distance - distance in miles

Example:

GetThreeDigitZipCodesWithin ("902", 20)
GetThreeDigitZipCodesWithin ("M3H", 20)

+ GetPlacesInside (zip) - find all places (cities, villages, etc.) covered by a zip code.

Parameters:

zip - 5 digit zip code or Canadian postal code (M3H)

Example:

GetPlacesInside ("90210")
GetPlacesInside ("M3H 6A7")

+ GetDistanceBetweenZipCodes (zip1, zip2) - find distance between 2 zip codes.

Parameters:

zip1 - 5 digit zip code or Canadian postal code 
zip2 - 5 digit zip code or Canadian postal code

Example:

GetDistanceBetweenZipCodes ("90210", "90012")

+ GetZipCodeCoordinates (zip) - returns zip code coordinates.

Parameters:

zip - 5 digit zip code or Canadian postal code

Example:

GetZipCodeCoordinates ("90210")

+ GetUserPlacesWithin (zip, distance, category) - proximity search for user-defined places.

Parameters:

zip - digit zip code or Canadian postal code
distance - distance in miles
category - category of user-defined places to return 
	(can be anything: office, stores, HomeDepot, etc)
	User-defined places must be first uploaded through 
	this web site or SaveUserPlaces function (see below)

Example:

GetUserPlacesWithin ("90210", "", 20, "HomeDepot")
GetUserPlacesWithin ("Beverly Hills", "CA", 20, "MyOffices")

+ SaveUserPlaces (places) - uploads and saves user-defined places.

Parameters:

places - an array of user-defined places UserPlaceDetail.
	UserPlaceDetail is an object describing a user place, it has following properties:
		Id - read-only number assigned by the database
		Name - string describing the place ("Head Office", "LA Location", etc), required
		Address - street address
		City - city name, required if ZipCode is not supplied
		State - 2 letter state code, required if City is supplied
		ZipCode - 5 digit zip code or Canadian postal code, required if City is not supplied
		Category - user assigned category, it allows to maintain different sets of locations
		Data - can be used to store extra data
		LatDegrees - latitude in degrees
		LonDegrees - longitude in degrees
		LatRadians - latitude in radians
		LonRadians - longitude in radians
		Distance - not used for this function
	Each UserPlaceDetail must have a set of coordinates, if City and State or ZipCode are supplied
	then coordinates will automatically be calculated from them. If City, State and ZipCode are
	empty then LatDegrees/LonDegrees or LatRadians/LonRadians must be filled in

Example:

UserPlaceDetail[] places = new UserPlaceDetail[0];
places[0].Name = "Head office";
places[0].City = "Beverly Hills";
places[0].State = "CA";
SaveUserPlaces (places);

+ GetAllUserPlaces () - returns an array of all user-defined places.

Parameters:

none

Example:

GetAllUserPlaces ()

How to subscribe
If you are ready to start using Zip Codes web service you will need a subscription. Even if you're just evaluating you will still need to subscribe. Several subscription options are available including free evaluation plan.
Subscription options:
- Yearly Plan - $32.00 per year
- Monthly Plan - $3.00 per month
- Free Plan - some restrictions apply
Create a subscription by clicking Buy on the top menu. You will be given a unique subscription ID that will allow you to use Zip Codes web service. This unique ID is very important, you must submit it on every call to the web service. See Step 4 for more information.

How to use it
If you reached this step you should already known basic functions and have a subscription. Now the fun part - integration. Web services are relatively easy to integrate. There are 2 ways to access Zip Codes web service: SOAP over HTTP POST and plain HTTP GET. SOAP over HTTP POST is the widely accepted method of calling web services and should be supported by your favorite SOAP toolkit. In case your environment does not support SOAP you can use HTTP GET by generating URLs and parsing resulting XML.
+ Using SOAP (click to expand/collapse)

SOAP protocol uses XML to wrap data into envelopes. In this case these envelopes are sent over HTTP between the server (me) and the client (you). Here's an example of what a simple request and response might look like. Note the SOAP header that is used to pass your Unique ID to the server (YOUR_UNIQUE_ID).

REQUEST:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
			xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
			xmlns:tns="http://skats.net/services/" 
			xmlns:types="http://skats.net/services/encodedTypes" 
			xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
			xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<soap:Header> 
		<tns:AuthenticationHeader id="h_id1">
			<SessionID xsi:type="xsd:string">YOUR_UNIQUE_ID</SessionID> 
		</tns:AuthenticationHeader>
	</soap:Header>
	<soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> 
		<tns:GetPlacesWithin>
			<place xsi:type="xsd:string">90210</place>
			<state xsi:type="xsd:string" />
			<distance xsi:type="xsd:float">4</distance> 
			<placeTypeToFind xsi:type="tns:GeoPlaceType">ZipCode</placeTypeToFind> 
		</tns:GetPlacesWithin>
	</soap:Body>
</soap:Envelope>

RESPONSE:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
			xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
			xmlns:tns="http://skats.net/services/" xmlns:types="http://skats.net/services/" 
			xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
			xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> 
		<types:GetPlacesWithinResponse>
			<GetPlacesWithinResult href="#id1" />
		</types:GetPlacesWithinResponse>
		<soapenc:Array id="id1" soapenc:arrayType="types:GeoPlaceDistance[4]">
			<Item href="#id2" /> 
			<Item href="#id3" /> 
			<Item href="#id4" /> 
			<Item href="#id5" /> 
		</soapenc:Array> 
		<types:GeoPlaceDistance id="id2" xsi:type="types:GeoPlaceDistance"> 
			<ToPlace xsi:type="xsd:string">90209</ToPlace>
			<ToState xsi:type="xsd:string">CA</ToState> 
			<Distance xsi:type="xsd:float">1.55116558</Distance> 
		</types:GeoPlaceDistance>
		<types:GeoPlaceDistance id="id3" xsi:type="types:GeoPlaceDistance">
			<ToPlace xsi:type="xsd:string">90069</ToPlace> 
			<ToState xsi:type="xsd:string">CA</ToState> 
			<Distance xsi:type="xsd:float">1.73732829</Distance> 
		</types:GeoPlaceDistance> 
		<types:GeoPlaceDistance id="id4" xsi:type="types:GeoPlaceDistance"> 
			<ToPlace xsi:type="xsd:string">90212</ToPlace> 
			<ToState xsi:type="xsd:string">CA</ToState> 
			<Distance xsi:type="xsd:float">1.85797</Distance> 
		</types:GeoPlaceDistance> 
		<types:GeoPlaceDistance id="id5" xsi:type="types:GeoPlaceDistance"> 
			<ToPlace xsi:type="xsd:string">90067</ToPlace> 
			<ToState xsi:type="xsd:string">CA</ToState> 
			<Distance xsi:type="xsd:float">1.99505162</Distance> 
		</types:GeoPlaceDistance> 
	</soap:Body> 
</soap:Envelope>

The Unique ID can be passed in using either SOAP header or HTTP header. SOAP header is called AuthenticationHeader with SessionID property. HTTP header is called AuthenticationHeader.

You can use your favorite SOAP toolkit to generate proxies. Unfortunately I can only tell you about .NET since that's what I use.

To use web service from Visual Studio.NET:
Create or open a project. In Solution Explorer right click on References node under the project node. Select "Add Web Reference..." from the pop-up menu. Type in one of URLs from step 1 and click Go. You should see one web service in the "Web service found at this URL" box. Click "Add Reference" button.

To use web service with .NET using command line tools:
Open command line prompt. Go to your .NET SDK folder unless you have that folder in your PATH environment variable. Type in one of the following commands:

wsdl.exe http://codebump.com/services/zipcodelookup.asmx?wsdl 
	/l:cs /n:YourProjects.Services

wsdl.exe http://codebump.com/services/geoplaces.asmx?wsdl
	/l:cs /n:YourProjects.Services

wsdl.exe will connect to the web service and generate a proxy class based on WSDL.
/l sets the language (CS, VB, JS)
/n sets a namespace for new class, can be anything.
For more options run wsdl.exe /?

And finally here's the code to call the web service using the proxy created above (substitute your unique ID for YOUR_SUBSCRIPTION_ID):

GeoPlaces g = new GeoPlaces();
AuthenticationHeader authHeader = new AuthenticationHeader();
authHeader.SessionID = YOUR_SUBSCRIPTION_ID;
g.AuthenticationHeaderValue = authHeader;

GeoPlaceDistance[] places = g.GetPlacesWithin("Los Angeles",
			"CA", 10, GeoPlaceType.ZipCode);
for (int i=0; i<places.Length; i++)
{
	GeoPlaceDistance place = places[i];
	Console.Write("Zip: {0}, State: {1}, Distance: {2}", 
		place.ToPlace, place.ToState, place.Distance);
}

ZipCodes g = new ZipCodes();
AuthenticationHeader authHeader = new AuthenticationHeader();
authHeader.SessionID = YOUR_SUBSCRIPTION_ID;
g.AuthenticationHeaderValue = authHeader;

ZipCodeDistances[] zipCodes = g.GetZipCodesWithin("90015", 10);
for (int i=0; i<zipCodes.Length; i++)
{
	ZipCodeDistances zipCode = zipCodes[i];
	Console.Write("Zip: {0}, Distance: {1}", 
		zipCode.ZipCode, zipCode.Distance);
}

+ Using HTTP GET (click to expand/collapse)

The web service can be called using URL parameters pretty much the same way the web page is requested, the difference is that the response is in XML. The best way to get a feel of how to create URLs for calling the web service is to use the service test page: http://codebump.com/services/placelookup.asmx. Choose a function, enter parameters and click "Invoke". New browser window should open with the response. Grab the URL from that window.
As you recall you need to pass your Unique ID with every call to the web service. While using HTTP GET method you have 2 options for sending it: in HTTP header or in URL. HTTP header is called AuthenticationHeader and URL parameter is called AuthenticationHeader as well. The test page described above already appends the Unique ID to the URL. Take a look at the request URL below, replace UNIQUE_ID with your own and paste it into the browser: ...placelookup.asmx/GetPlacesWithin?AuthenticationHeader=UNIQUE_ID&place=90210&state=&distance=4&placeTypeToFind=ZipCode
The result will be this XML document

<?xml version="1.0" encoding="utf-8"?>
<arrayofgeoplacedistance xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
		xmlns="http://skats.net/services/literalTypes">
  <geoplacedistance>
    <toplace>90209</toplace>
    <tostate>CA</tostate>
    <distance>2</distance>
  </geoplacedistance>
  <geoplacedistance>
    <toplace>90069</toplace>
    <tostate>CA</tostate>
    <distance>2</distance>
  </geoplacedistance>
  <geoplacedistance>
    <toplace>90212</toplace>
    <tostate>CA</tostate>
    <distance>2</distance>
  </geoplacedistance>
  <geoplacedistance>
    <toplace>90067</toplace>
    <tostate>CA</tostate>
    <distance>2</distance>
  </geoplacedistance>
</arrayofgeoplacedistance>

User-Defined Places
User-Defined Places (UDPs) allows storage of custom locations in Zip Codes database and query them just like a regular a zip code or city and state. The perfect scenario for UDPs is office or branch locator. After the list of offices is uploaded and GetUserPlacesWithin() function can be used to lookup offices around a zip code or city and state.
UDPs can be groupped into categories and search results can be narrowed down by categories. Perfect example of that is different type of branches: full service and limited.
There are several ways to manage UDPs:
- Upload TAB delimited file using User-Defined Places screen under Your Account
- Enter custom locations by hand using User-Defined Places screen under Your Account
- Call SaveUserPlaces() service function to save custom locations
Samples and Demos
I have created a couple of sample application showing off how to use Zip Codes web service. The C# Windows app is the most feature complete, it will allow you to call several web service methods as well as manage user-defined places.
C# Windows application

Older samples:
VB 6 Windows application
VB.NET Windows application