This series explores the useful yet simple Web services of GeoNames, starting with their time zone API. I'll explain how to use these free Web services, providing examples of single and orchestrated usage to accomplish tasks that can help your business in innovative ways!

We live in a global village; there's no way to deny it. Long gone are the days of countries standing alone, of companies staying within the boundaries of their nations. In today's busy world, it's common to find an American company with branches in Japan, India, or France or vice versa. Sometimes, this global presence causes serious headaches, simply because it's not the same time everywhere.

That's where this first Web service comes in. It provides information about the time zone of a set of GPS coordinates (latitude and longitude), along with some other possible useful details, such as time zone name, country name, and so on. These pieces of data can be used to obtain other sets of data, using the Web services in an orchestrated manner. I'll go over that on the next tip. GeoNames provides a wide range of Web services. You can find out more about them and the GeoNames organization in this link.

You'll need to create and activate a user in the GeoNames Web site. The user name for your application can be registered here. You will then receive an email with a confirmation link; after you have confirmed the email, you will have to enable your account for the Web services on your account page.

The time zone REST Web service expects you to provide the latitude and longitude. Here's how it works: you provide a URL—for example, http://api.geonames.org/timezone?lat=47.01&lng=10.2&username=demo.

This is composed of the Web service location (http://api.geonames.org/timezone?) and parameters (lat=47.01&lng=10.2&username=demo). In return, you get an XML document with all the time zone–related information (or an error, which I'll refer to later):

<geonames>

  <timezone>

    <countryCode>AT</countryCode>

    <countryName>Austria</countryName>

    <lat>47.01</lat>

    <lng>10.2</lng>

    <timezoneId>Europe/Vienna</timezoneId>

    <dstOffset>2.0</dstOffset>

    <gmtOffset>1.0</gmtOffset>

    <rawOffset>1.0</rawOffset>

    <time>2011-07-08 22:42</time>

    <sunrise>2011-07-08 05:32</sunrise>

    <sunset>2011-07-08 21:15</sunset>

  </timezone>

</geonames>

I'll be using only the portion highlighted in blue, but feel free to modify the code in order to use the additional information provided. It's simply a matter of adjusting the procedure's parameters and filling the variables with the data structure fields.

The time zone information is expressed in the hour difference (from -12 to +13) to the Greenwich Mean Time, or GMT. In this example, the dstOffset element tells us that there's a +2 hour difference to GMT for this location, while the gmtOffset has a value of +1. The dstOffset element indicates the time difference according to Daylight Saving Time (hence, DST), while the gmtOffset element shows the actual hour difference to GMT, unaffected by DST. Finally, rawOffset is the amount of time in hours to add to GMT to get standard time in this time zone. Because this value is not affected by Daylight Saving Time, it is called raw offset. You can find this Web service's documentation here.

I'll be using the methodology and structure of a previously published article ("GPS-Enable the Addresses in Your Database!"). I recommend that you read it carefully, because I won't go into much detail about the way things are done here. I'll just cover the highlights of this Web service. You'll also need to download the utility library mentioned on the article for the Web service invocation to work.

For ease of use, I've created a function that you can invoke in an IF statement:

If RtvTmzFrmGPS(P_Lat: P_Lng: P_CountryCode: P_CountryName: P_TimeZoneID: P_dstOffset : P_gmtOffset : P_rawOffset : P_ErrCode : P_ErrMsg ) = *Off;

  // Do something with the parameters

EndIf;

In order for this procedure to work (and using RtvGPSFmrAddr as a base), I've started by changing the data structure used on the XML-INTO to match the XML document returned by the Web service. You'll find the GeoNames data structure in the QCPYLESRC/RTVTmz_PR member.

Next, I've adjusted the procedure's parameters in order to return the time zone information and fill them in the Proc subroutine with the data structure fields.

// Otherwise, pass the results to the output parms 

  P_CountryCode = Geonames.TimeZone.CountryCode;   

  P_CountryName = Geonames.TimeZone.CountryName;   

  P_TimeZoneID  = Geonames.TimeZone.TimeZoneID;    

  P_dstOffset   = Geonames.TimeZone.dstOffset;     

  P_gmtOffset   = Geonames.TimeZone.gmtOffset;     

  P_rawOffset   = Geonames.TimeZone.rawOffset;     

  P_ErrCode   = *Zeros;                            

  P_ErrMsg    = *Blanks;                           

Finally, I had to adjust the response in case of error. This was necessary because this Web service uses a different structure to return errors:

<geonames>

  <status message="invalid lat/lng" value="12"/>

</geonames>

This error structure is common to other GeoNames Web services, so you'll see more of it later. I've noticed that in some versions of i5/OS, the fact that the closing of the status tag is "/>" instead of "</status>" causes some problems, so a real error message might be misinterpreted as a malformed XML.

In the examples provided in QRPGLESRC/TST_TMZADD, you'll find an orchestration of Web services (the previously mentioned RtvGPSFrmAddr being used to retrieve the GPS coordinates of an address and then RtvTmzFrmGPS using those coordinates to retrieve the Time Zone information). 

The next tip will cover the Country Info Web Service. Meanwhile, if you have any questions, feel free to contact me!

as/400, os/400, iseries, system i, i5/os, ibm i, power systems, 6.1, 7.1, V7, V6R1