Will Fitch’s Blog

I have completed the major functionality to the SOAP integration of the zip code services. The following methods can be used to get the data you need:

1. getDistanceByZip - Get the distance from one zip code to another
2. getZipsByRadius - Get GPS information within (X) miles of a zip code
3. getLocalTime - Get the local time for a zip code

I am going to describe each function in depth, and give examples of each in a few languages.  If you have suggestions to this service, feel free to contact me using the contact form.

About the Service

This web service is provided absolutely free.  Please don’t abuse this.  If requests start getting out of hand and bringing my server to its knees, I will start limiting the number of queries per user per day.  I don’t want to do this, but I do like my server actually serving :).

It is an RPC style web service, as it really isn’t complicated and is limited to a very specific audience.  It’s also easier for developers to use and understand in comparison to document-literal.

Error Handling - SoapFault

If you receive a SoapFault from any of these services, it will be for one of two reasons:

1. Client - you specified invalid parameters
2. Server - something is wrong with my server (let me know if you get this )

Always use a try-catch block when executing requests.  In the event a SoapFault is caught, check to see if it’s a Server or Client error.  If it’s a Client error, you can rest assured that there are no results to be returned because of invalid parameters, or there’s just no more data.  If it is a Server reason, you might inform your users that “The server is experiencing difficulties” or something.

Optimization (and less bandwidth)

To optimize your runtime experience, download my WSDL.  This will save your script tons of time and me bandwidth.  Also, unless you are in a development environment, make sure your php.ini value “soap.wsdl_cache” is set to 1.  This will cache your WSDL in a temporary directory.

Now, on to the service description.

Getting Distances Between Zip Codes - getDistanceByZip(int zipcode1, int zipcode2)

The parameters for this service is pretty much self-explanatory.  In order to successfully retrieve the distance between two zip codes, you should specify two valid zip codes. 

It’s important to inform you that this is not road distance!  This is in fact calculating the distance based on longitude and latitude.  The result is always mileage returned in floating point number format, unless you try to get the distance between non-existing zip codes, at which point a Client SoapFault will be returned.  This is a very simple, but useful tool for dating sites, phonebooks, etc.  Time for some example code!

$zip1 = 35761; // New Market, AL

$zip2 = 12345; // Schenectady, NY

try { 

    $soap = new SoapClient("http://www.phpfever.com/web-services/ZipCode.wsdl"); 

    $distance = $soap->getDistanceByZip($zip1,$zip2);

} catch (SoapFault $e) {

    print_r($e); // print the exception or do something different

}

It’s that simple! 

Zip Code Radius Searching - getZipsByRadius(int $zip_code, int $radius, string $return_type, int $start, int $end)

The purpose of this service is getting other zip codes within a specified mileage, by a zip code.  For instance, you have a dating service and you want your users to be able to search for matches by zip code.  The process flow like this:

1. Get user’s zip code (e.g. via form submission).
2. Send that zip code along with a radius (specified mileage) to the web service.
3. Receive the information from the service.
4. Query against your database with the provided zip codes.

Voila!  You now have a list of users by zip code and radius.  The cool part about this service is that you can either receive the data by serialized array (PHP only) or XML.  I recommend using SimpleXML if you plan to request the document in XML format.

The parameters are very important.  You must specify each of them every time.  Here are the definitions:

1. int zip_code - this is the zip code to search against
2. int radius - this is the distance in mileage from the zip code.  There is no maximum value here although this is limited to the US.
3. string return_type - either XML or ARRAY (case doesn’t matter).  If array is chosen, a serialized array will be returned.  If XML, obviously XML will be returned.  See below for sample XML document.
4. int start - this is the starting point.  It actually allows you to do pagination!  If you are familiar with MySQL’s LIMIT clause, this is the first number (e.g. LIMIT 0,…)
5. int end - this is the ending point.  Reverting back to the MySQL LIMIT clause LIMIT 0,30.  This has a maximum value of 500.  In other words, you can only receive a maximum of 500 results at any given query.  Use the start, end capabilties to paginate!

Click here to download the sample XML document.

Again, the example:

try {

 $soap = new SoapClient("http://www.phpfever.com/web-services/ZipCode.wsdl");

 $distance = $soap->getZipsByRadius(35761,100,'XML',0,300);

} catch (SoapFault $e) {

 print_r($e); // print the exception or do something different

} 

Very simple.

Getting Local Time Based on Zip Code - getLocalTime(int zipcode,string format)

This simple, yet powerful service allows you to get the local date/time of a specific zip code. The date and time fields are two separate elements for easier parsing.

Example:

try {
    $soap = new SoapClient('http://www.phpfever.com/web-services/ZipCode.wsdl');
    $time = $soap->getLocalTime(35761);
} catch (SoapFault $e) {
    print_r($e);
}

That’s it! I will be posting more example code in different languages as I go.