SOAP Zip Code Web Service!

Posted on 26. Jul, 2007 by Will Fitch in News, PHP, Resources, Web Services

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!

PHP
  1. $zip1 = 35761; // New Market, AL
  2.  
  3. $zip2 = 12345; // Schenectady, NY
  4.  
  5. try {
  6.  
  7.   $soap = new SoapClient("http://www.phpfever.com/web-services/ZipCode.wsdl");
  8.  
  9.   $distance = $soap->getDistanceByZip($zip1,$zip2);
  10.  
  11. } catch (SoapFault $e) {
  12.  
  13.   print_r($e); // print the exception or do something different
  14.  
  15. }

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:

PHP
  1. try {
  2.  
  3.  $soap = new SoapClient("http://www.phpfever.com/web-services/ZipCode.wsdl");
  4.  
  5.  $distance = $soap->getZipsByRadius(35761,100,‘XML’,0,300);
  6.  
  7. } catch (SoapFault $e) {
  8.  
  9.  print_r($e); // print the exception or do something different
  10.  
  11. }

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:

PHP
  1. try {
  2.   $soap = new SoapClient(‘http://www.phpfever.com/web-services/ZipCode.wsdl’);
  3.   $time = $soap->getLocalTime(35761);
  4. } catch (SoapFault $e) {
  5.   print_r($e);
  6. }

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

[del.icio.us] [Digg] [Google] [LinkedIn] [StumbleUpon] [Windows Live] [Yahoo!] [Email] More »

Tags: , ,

Related Articles

22 Responses to “SOAP Zip Code Web Service!”

  1. Rob

    02. Oct, 2007

    Love your web service. Having a bit of confusion with it though.

    when we call this…
    $distance = $soap->getZipsByRadius(80222,100,‘XML’,0,300);

    the XML file only contains 30 results.
    Is 30 the max? Seems like it should return from 0-300. I guess we could repeatedly call for 0-29, 30-59 and so on…

    Thoughts?
    Thanks
    Rob

  2. Jeff Walker

    22. Nov, 2007

    Hey, thanks a zillion. This service really helped out.

    :o )

  3. Will Fitch

    02. Apr, 2008

    The zip code search has been increased to 300 elements out.

  4. Chad Crowell

    29. Jul, 2008

    I’m new to SOAP and the radius lookup is exactly what I need. Can you give me a few pointers? So, I know that calling this function with a provided zip code and radius value will give me an XML array of zip codes within that radius of he original zip code. Secondarily, I would need to use that array to run against my records to provide the results to my users. Fine.

    I’m just having trouble getting the calls to your API right. If you could email me please, just a blank message, I’d be grateful if we could have a conversation about how to get this call right in PHP.

    Thanks Will.

  5. Jose

    22. Oct, 2008

    Hi ! your service is what i’m looking for but i find some troubles when trying to make it working:

    try
    http://www.phpfever.com/web-services/zip_radius.php?zip_code=33033&radius=10

    it fails with some php warnings and fatal errors.
    Are you going to fix that sooner ?

    Regards

    Jose

  6. Will Fitch

    10. Nov, 2008

    Hi Jose,

    Please use the latest version of the web service here http://www.phpfever.com/soap-zip-code-web-service.html. The service you are referencing is outdated.

  7. cloud9ine

    22. Dec, 2008

    Will,

    Thanks a ton for this awesome service. One question though. I am catching time off by an hour. Is there possibly a DST error? Or should I adjust for DST? Is this service still being maintained?

    Thanks

    Cloud9ine

  8. cloud9ine

    22. Dec, 2008

    Actually, it looks like it is a whole 11 hours off since the result is an hour ahead but AM instead of PM

  9. Will Fitch

    22. Dec, 2008

    Hello cloud9ine,

    I will check this when I get home this evening. Thanks for bringing it to my attention!

  10. cloud9ine

    09. Jan, 2009

    Thanks, Will

    On second looks, it is an hour off, not 11 hours.

    In your example, you have only one parameter passed, the zip code. What is the second parameter (string) in the WSDL? Is it a selection of 12 or 24 hourly? Could you help us with the explanation of this parameter?

    I end up having an AM / PM problem as well. I am trying the zip code 63031. Also, I might be hitting your server a little hard around now since I am developing. Sorry for the trouble.

    Thanks again for a very useful service.

  11. Jay

    21. Feb, 2009

    Awesome, I can’t wait to use this. Is this free? What ab the code that powers the web service? My only concern is that eventually you will stop offering this and it will go away (as many others I’ve seen has)

  12. Will Fitch

    25. Feb, 2009

    Hi Jay,

    This service has been around for more than two years, and it has always been free. The code behind it is PHP and the service is RPC. I am working on, in as much time as I can spare, a document-literal version which will provide more than just “data”. It will provide business functions as web services were intended to do.

  13. Diego

    05. Mar, 2009

    Hi Will,
    I’m planning to use this web service in a project I’m about to start. Is it still online? For how long do you think it’s going to be available? I mean… if there’s the possibility that it is put out of service.

    Thanks!

  14. Will Fitch

    05. Mar, 2009

    Hi Diego,

    This service isn’t going anywhere. I will be releasing a new version of it very soon, but this version will be available for 6 months or so after that release.

  15. Weast

    16. Mar, 2009

    Hi Will,
    This is a great service, thanks for all your hard work! I’ve noticed that some zip codes return no results on the radius search (i.e. 60586, 60491). My requests to other zip codes work beautifully, but occasionally I see these rogues. Could this be due to outdated data?

    Thanks!

  16. Kevin

    08. Apr, 2009

    Great article, very extensive. The best one I found on the first page of Google. Looking forward to Part 2. Thanks!

  17. Pankaj

    08. May, 2009

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

    The arguments should have been ‘String’ and not ‘int’. What if someone wants to calculate distance between ‘07044′ and ‘07928′? Both are valid NJ zip codes.

  18. Jason

    15. May, 2009

    Great article…but…..any ideas on this error:

    SOAP-ERROR: Encoding: string ‘\x91…’ is not a valid utf-8 string [faultcode] => Client [faultcodens] => http://schemas.xmlsoap.org/soap/envelope/ )

  19. Tony Garcia

    19. Jun, 2009

    hello. Thanks for providing this great service. I’ve been testing it and would like to use it for a site I’m developing. I do have one question, though — how often is the zip code data updated?

    thanks again

  20. Amit

    25. Jun, 2009

    Hi Will,

    Is this service limited to United States or it serves for other countries too ? I am looking for something which help for maximum country of out planet. Will it able to fulfill my requirement ?

  21. Jeff

    23. Sep, 2009

    Does your service support REST requests? If so, what is the format for making such requests?

  22. Will Fitch

    18. Dec, 2009

    As of now, it does not. I am working on the REST version of this and also updating the database with additional API options.

Leave a Reply