Do you realize how much your business can do with GPS coordinates? No? Well, let me tell you.

All of our applications' databases hold hundreds if not thousands of addresses—from our clients, suppliers, stores, warehouses, branches, and so on. This article explains how to GPS-enable, or geocode, that precious information in order to expand the horizons of what you can do with your data: improve your logistics processes, locate areas where your network (of clients, stores, or suppliers) is poor or non-existent, and develop a lot of other business-specific uses for the GPS coordinates.

Almost daily, our call center receives phone calls from clients asking questions like this one: "I'm in the x area; what's your closest store to my location?" Unless the operator knows the area the client is in, this is a tough question to answer...unless the operator has a little help from an online maps service (Google, Bing, Yahoo) or another application. Of course, this requires that the store locations are geocoded (that is, the stores' addresses are translated into GPS coordinates). This is what we're going to do here.

The process has three parts: receive the address and compose a proper request to the Web service; invoke the Web service; process the response (receive and parse the Xml) and extract the latitude and longitude coordinates from the response.

So let's get started!

There are a few things we'll need to set up. We'll be using the Yahoo Place Finder API, which is a free online Web service, and on the iSeries side, we'll use a great free utility library created by Scott Klement called HTTP API. Then we'll also need to process the Web service's response; for that, we'll use the op code XML-INTO. Lastly, your iSeries must have an Internet connection. This usually means going through a firewall to get to the Internet. Since we're going to connect to Yahoo's servers, you'll need to set up a firewall rule or two to be able to get through.

First of all, keep in mind that even though Yahoo Place Finder Web service is free, there are a few rules to abide by. Please read carefully the terms and conditions and the API documentation. I'll be going through some parts of it, but a complete read is advised. In order to use the Web service, you must create an Application ID. You're required to create a Yahoo account if you don't already have one. After you sign in, the application form shown in Figure 1 will pop up.

Figure 1: Fill in the application form. (Click image to enlarge.)

It's important to fill it in properly, because you might not be able to use the Web service otherwise. Enter your application name, choose client/desktop in the "kind of application" box, and briefly describe its purpose. If you choose "Web-based," you are also required to fill in the application and icon URLs. Finally, in the Access Scopes section, choose "This app will only access public APIs, Web Services, or RSS feeds." Tick the Terms of Use checkbox. Click the "Get API Key" button and make a note of your Application ID. It will be needed later.

The next step is installing the HTTP API library. This is a fairly simple process: 

Log on to your iSeries, and create a save file to store the downloaded file in. To do this, type CRTSAVF QGPL/HTTPAPI. Next, use FTP to transfer the save file to your iSeries by opening an MS-DOS prompt and typing the following:

cd \<directory where you put the save file>

ftp your-iSeries-name-here

(enter your username & password when asked)

binary

put httpapi.savf QGPL/HTTPAPI

quit

Back on the iSeries, type this:

DLTLIB LIBHTTP (ignore errors if library doesn't exist)

RSTLIB SAVLIB(LIBHTTP) DEV(*SAVF) SAVF(QGPL/HTTPAPI)

Finally, build and run the install program:

CHGCURLIB CURLIB(LIBHTTP)

CRTCLPGM INSTALL SRCFILE(LIBHTTP/QCLSRC)

CALL INSTALL

The install program will guide you through the rest of the process.

You're all set! Now let's analyze the code and see how the three steps I mentioned previously are implemented.

Implementing the Steps

In order to do that, some context is needed. I've created a function that accepts the postal address (street name and door number, city, zip code, and country—or any combination of these) and returns the GPS coordinates (latitude and longitude) closest to the address. It's important to note that the result is not always accurate: if the door number is not found, the Web service will return the closest it finds, or if the street name is a partial match to some other street name and the original is not found by the Web service in its database, you'll get the partial match. The quality of the response is also passed back by the function, and I'll explain it in detail later. There's an additional parameter named Error Code that is mainly to help the application support team track down and resolve any issue that arises. I'll also cover that in depth later. Here's how to invoke the Web service:

CallP RtvGpsFrmAddr(P_Address : P_Quality : P_Latitude : P_Longitude : P_ErrorCode);

The function itself returns an indicator (in which *OFF means success and *ON means error), so the best way to use it is like this:

If RtvGpsFrmAddr(P_Address : P_Quality : P_Latitude : P_Longitude : P_ErrorCode) = *Off;

      // Use the P_Latitude and P_Longitude for something

Else;

      // Oops! Something went wrong! Use the P_ErrorCode to react accordingly

EndIf;

Finally, let's go over step one: receive the address and compose a proper request to the Web service.  The Web service is expecting two things in the request: a properly formatted address and a valid Yahoo Developer Network Application ID (YDN App ID). By "properly formatted," I mean that the address cannot have blank spaces, and any special characters (ö, for instance) have to be encoded in UTF-8. I explained earlier how to obtain a YDN App ID, so the only thing missing is here is where to use these two: the base URL of the Web service. Since Yahoo is continually working on improving its tools, the base URL might change sometime in the future (to include the version number or change the name, for instance), so I've stored it in a data area referred to as DAApiBaseUrl in the code. The real name is shorter (DAAPIURL) due to the 10-character limitation on the object names. Analyzing the code, you'll find the retrieval and check of the YDN App ID and the base URL in (1) and (2), respectively:

             // (1)

             // Retrieve Yahoo Developers Network Application ID

             In DAAppID;

             W_AppID = DAAppId;

             // Check If the YDN App ID is filled in

             If W_AppID = *Blanks;

               P_ErrorCode = 300; //Invalid YDN App ID

               W_Return = *ON;

               ExSr End_And_Return;

             EndIf;

             // (2)

             // Retrieve Yahoo Place Finder API base url

             In DAApiBaseUrl;

             W_ApiBaseUrl = DAApiBaseUrl;

             // Check If the Yahoo Place Finder API base url is filled in

             If W_ApiBaseUrl = *Blanks;

               P_ErrorCode = 350; //Invalid Yahoo Place Finder API base url

               W_Return = *ON;

               ExSr End_And_Return;

             EndIf;

The next step is formatting the input address to the Web service's requirements. The built-in function %XLATE is used to replace the blank spaces in the address with plus signs (+). Since usually the address doesn't take up the entire size of the variable, %Trim is used to ensure that the trailing blanks are not converted to plus signs:

             // Prepare the address, by replacing blanks with the plus sign

             W_Address = %Xlate(' ' : '+' : %Trim(P_Address));

After this, there's only one thing left to do: encode your request. For this task, I use a little something from the HTTP API library called a Web form. Basically, it encodes whatever variables you include, composing a string in UTF-8:

             // Compose the WebService URL with the address and your YDN App ID

             W_Form = WEBFORM_open();

             WEBFORM_setVar(W_Form : 'q'     : %Trim(W_Address) );

             WEBFORM_setVar(W_Form : 'appid' : %Trim(W_AppID)   );

             W_Url = %Trim(W_ApiBaseUrl) + WEBFORM_getData(W_Form);

             // Close form

             WEBFORM_Close(W_Form);

Here's an example to make it clearer. Suppose your address is 701 First Ave., Sunnyvale, CA 94089 and your YDN APP ID  is A234fW9. After the code above runs, the W_Url variable will contain the following URL: http://where.yahooapis.com/geocode?q=701%2BFirst%2BAve.%2C%2BSunnyvale%2C%2BCA%2B94089&appid=A234fW9

Here, http://where.yahooapis.com/geocode? is the API base URL, stored in the data area I previously mentioned. 701%2BFirst%2BAve.%2C%2BSunnyvale%2C%2BCA%2B94089 is the address, after it has been transformed (blanks to pluses) and encoded (since there are no special characters in this address, the only change was turning + into %2B).

The YDN App ID remained untouched. The q and appid are parameters of the Web service and correspond to your query (the address) and your YDN App ID, respectively. The encoder provides this double function of translating to UTF-8 and adding the necessary parameter separators (&) to make composing a proper URL very easy.

Step two is invoking the Web service. For that, I'll use another HTTP API function, called http_get_url. This function accepts as an input parameter a URL and saves the corresponding Web page to a file in the IFS. The name of the IFS file is indicated as a second parameter. The function itself returns a status code (1 mean success; anything else is an error. Check Scott Klement's documentation for details). In order to use it, you must create an IFS file first. Since this is only temporary storage for our Web service response, I'll use another function, named http_tempfile, to create it. Here's the complete code for step two:

             // Create a temp file to receive the WebService response

             W_FileName = http_tempfile() + '.xml';

             // Invoke the WebService

             W_RetCode = http_url_get(W_url : W_FileName);

             // In case of error,  return *ON

             If (W_RetCode <> 1);

               P_ErrorCode = 400; //Problems invoking the Web Service

               W_Return = *ON;

               ExSr End_And_Return;

             EndIf;

I'll explain what is done in here case of error later. The important thing is that after this piece of code runs, I have the Web service's response, in XML format, stored in an IFS file. The file name is saved in variable W_FileName for the next step, which is process the response (receive and parse the XML) and extract the latitude and longitude coordinates from the response.

There are a few ways to process an XML file in RPG. My favorite is the op code XML-INTO. Even if you have used it before, read on because you might find something new.

The op code itself is very simple to use: just provide an XML file, a data structure to receive the parsed contents, and some options that define how the parsing should occur. I'll start by this last bit. You might not need the whole content of the XML document: it's normal to use only a sub-tree (a smaller set of data) or even only a few elements (fields) within that sub-tree. By specifying the correct options, you indicate how the parser should behave and what is acceptable in terms of validation. In the code, I don't care about the case (lowercase or uppercase is irrelevant to me) or the complete XML structure of the file (this is done to ensure that the RtvGpsFrmAddr function will continue to work even if Yahoo adds new elements to the xml of the Web service). Having this in mind, here's how I set up the options for XML-INTO:

             // Prepare parameters for XML-INTO

             W_Options = 'doc=file +

                    path=RESULTSET +

                    case=any +

                    allowextra=yes +

                    allowmissing=yes';

From top to bottom, doc=file means that we'll be parsing XML coming from a file; path=RESULTSET tells the parser which sub-tree we're interested in (I'll get back to the XML structure later); case=any refers to the upper or lowercase of the element names themselves (as I mentioned earlier, it's really irrelevant to us); finally, allowextra=yes and allowmissing=yes ensure that the parsing will still occur if the XML structure is (slightly) changed.

Now the parser knows how to act and what to act upon. W_FileName contains the name and path of the XML file. The only thing missing is where to store the result of the parsing. XML-INTO expects a data structure that "clones" the XML structure that it's parsing. In other words, the data structure field names must match the XML element names so that the parser finds the proper match and stores the content of element '<street>' in the data structure field 'street'. Because I specified case=any in the options, the field and element names can be either 'street' or 'STREET'; I really don't care about the case. To build the data structure, we need to analyze the XML structure. Specifically, we need to find the latitude, the longitude, the quality of the match, and the error code; these are the output parameters of RtvGpsFrmAddr. However, I've tried to leave the code as flexible as possible, so I've created a data structure that covers the whole XML structure. Going back to the example from the first step, the URL http://where.yahooapis.com/geocode?q=701%2BFirst%2BAve.%2C%2BSunnyvale%2C%2BCA%2B94089&appid=A234fW9 will return the following XML:

<ResultSet version="1.0">

<Error>0</Error>

<ErrorMessage>No error</ErrorMessage>

<Locale>us_US</Locale>

<Quality>87</Quality>

<Found>1</Found>

<Result>

<quality>87</quality>

<latitude>37.416275</latitude>

<longitude>-122.025092</longitude>

<offsetlat>37.416397</offsetlat>

<offsetlon>-122.025055</offsetlon>

<radius>500</radius>

<name/>

<line1>701 1st Ave</line1>

<line2>Sunnyvale, CA  94089-1019</line2>

<line3/>

<line4>United States</line4>

<house>701</house>

<street>1st Ave</street>

<xstreet/>

<unittype/>

<unit/>

<postal>94089-1019</postal>

<neighborhood/>

<city>Sunnyvale</city>

<county>Santa Clara County</county>

<state>California</state>

<country>United States</country>

<countrycode>US</countrycode>

<statecode>CA</statecode>

<countycode/>

<uzip>94089</uzip>

<hash>DDAD1896CC0CDC41</hash>

<woeid>12797150</woeid>

<woetype>11</woetype>

</Result>

</ResultSet>           

The Web service documentation explains each element in depth here, so I'll just cover the structure itself and the relevant elements. The structure only has one tree, called ResultSet. Within it there are six elements, of which five are simple and one is complex. This last one, named Result, is what we're interested in. In a situation such as this one, where there's only one match, the <Result> element exists only once. I have decided to keep things simple and expect only one <Result> element. I'll briefly explain how to change the RtvGpsFrmAddr function to handle more than one <Result> later. However, keep in mind that this might also mean that you need some logic on your program to decide which GPS coordinates to use. Our data structure has to match this duality of simple and complex elements. For those of you unfamiliar with the terminology, complex element basically means that the element has sub-elements. In the <Result> case, a lot of them! To match this structure, we need a data structure that contains five fields, with names that match the five simple elements, and another data structure that in turn has fields whose names match the sub-element names. I know it's a mind twister, so let's look at the data structure, and it might start to make sense:

      *------------------------------------------------------------------------*

      *   Data Structures                                                      *

      *------------------------------------------------------------------------*

     D ResultSet       DS                  Qualified

     D   Error                             Like(t_Error)

     D   ErrorMessage                      Like(t_ErrorMessage)

     D   Locale                            Like(t_Locale)

     D   Quality                           Like(t_Quality)

     D   Found                             Like(t_Found)

     D   Result                            LikeDS(t_Result)

     D                                     Dim(10)

     D t_Error         S              4  0

     D t_ErrorMessage  S             50A

     D t_Locale        S              5A

     D t_Quality       S              2  0

     D t_Found         S              3  0

     D t_Result        DS                  Qualified

     D                                     Based(Template)

     D   quality                           Like(t_Quality)

     D   latitude                    15A

     D   longitude                   15A

     D   offsetlat                   15A

     D   offsetlon                   15A

     D   radius                       4  0

     D   name                       100A

     D   line1                      100A

     D   line2                      100A

     D   line3                      100A

     D   line4                      100A

     D   house                       10A

     D   street                     100A

     D   xstreet                    100A

     D   unittype                   100A

     D   unit                       100A

     D   postal                      10A

     D   neighborhood               100A

     D   city                       100A

     D   county                      50A

     D   state                       50A

     D   country                     50A

     D   countrycode                  5A

     D   statecode                    5A

     D   countycode                   5A

     D   uzip                        10A

     D   hash                        20A

     D   woeid                       10A

     D   woetype                      5A

The ResultSet data structure is qualified, just to make it easier to read in the code. Similarly, the t_Result data structure, which is the definition used for the sixth "field" of the ResultSet data structure, is also qualified. The "field" Result is an array that can contain up to 10 elements, just to prevent XML-INTO from returning an error if there's more that one <RESULT> element in the XML.

It now time to put everything together—the XML file, the options, and the data structure:

             // Receive xml file into data structure

             Monitor;

               Xml-Into ResultSet %xml(W_FileName : W_Options);

             On-Error;

               P_ErrorCode = 500; //Malformed xml

               W_Return = *ON;

               ExSr End_And_Return;

             EndMon;

I'm using Monitor just to make sure that the function aborts gracefully if something is not as it should be. If everything goes well, the XML contents are now in the ResultSet data structure. If the Web service returned a valid response (in other words, a single address match), we can extract the GPS coordinates from it:

             // Check for API errors before processing

             // In case of API error, return the error code and leave

             If ResultSet.Error <> 0;

               P_ErrorCode = ResultSet.Error;

               W_Return = *ON;

               ExSr End_And_Return;

             EndIf;

             // If an exact match was found (only 1 result returned), pass the

             // coordinates to the output parms

             If ResultSet.Found = 1;

               P_Quality   = ResultSet.Result(1).quality;

               P_Latitude  = ResultSet.Result(1).latitude;

               P_Longitude = ResultSet.Result(1).longitude;

               P_ErrorCode = 0; // Sucess!

               W_Return = *Off;

               ExSr End_And_Return;

             Else;

               P_ErrorCode = 600; // No exact match (none or more than 1 found)

               W_Return = *ON;

               ExSr End_And_Return;

             EndIf;

In the If ResultSet.Found = 1 block, you can see the beauty of the Qualified keyword; the P_Quality parameter is receiving the "quality" field of the first element of the data structure Result, which in turn, is part of the ResultSet data structure. This ends the third step. It's now time to explain all of those ExSr End_And_Return calls. Each anomalous situation in the code is handled by a set of three lines:

               P_ErrorCode = 600; // No exact match (none or more than 1 found)

               W_Return = *ON;

               ExSr End_And_Return;

You've seen this over and over again, right? P_ErrorCode returns a predetermined error code telling the caller program what went wrong. The error code itself is hardcoded, except in this situation:

             // Check for API errors before processing

             // In case of API error, return the error code and leave

             If ResultSet.Error <> 0;

               P_ErrorCode = ResultSet.Error;

               W_Return = *ON;

               ExSr End_And_Return;

             EndIf;

In this situation, I return the error code of the Web service. You can find the meaning of these error codes here. W_Return contains the success or failure indicator for the RtvGpsFrmAddr function. You might have noticed that is always set to *ON, except when I extract the latitude and longitude from the data structure. The error code and the return indicator are used in routine End_And_Return:

         //--------------------------------------------------------------------*

         //  End and Return                                                    *

         //--------------------------------------------------------------------*

           BegSr End_And_Return;

             // Log status (useful for debuging)

             ExSr Log_Status;

             // Delete temp file

             unlink(W_FileName);

             // End and return the indicator (*on = error / *off = success)

             Return W_Return;

           EndSr;

         //--------------------------------------------------------------------*

         //  Log status                                                        *

         //--------------------------------------------------------------------*

           BegSr Log_Status;

             // Log request

             Open Log;

             Log_TypeReq = 'RtvGpsFrmAddr';

             Log_StsCode = P_ErrorCode;

             Log_InpParm = %Trim(P_Address);

             Log_OutParm = 'Quality=' + %Char(P_Quality)

                           + '|Latitude=' + %Trim(P_Latitude)

                           + '|Longitude=' + %Trim(P_Longitude);

             Log_DateTim = %TimeStamp;

             Write LogR;

             Close Log;

           EndSr;

End_And_Return is a very simple routine that logs the request to a file (I'll explain routine Log_Status next), deletes the temporary file using another function from the HTTP API library, and returns *ON or *OFF, in case of error or success, respectively. The Log_Status routine will be useful in the early days of the implementation, because it saves all the input and output parameters in a record per invocation of the RtvGpsFrmAddr function. You might want to disable it later on, even though I strongly recommend keeping it; it might be of use in the future.

Now let's consolidate all of this with an example:

      * Retrieve GPS Info Procedures

      /Copy QCPYLESRC,RTVGPS_PR

     DW_Response       S             52A   Inz(*Blanks)

      /FREE

         P_Address = '701 First Ave., Sunnyvale, CA 94089'; // Full address w/ door nbr

         If RtvGpsFrmAddr(P_Address :

                          P_Quality :

                          P_Latitude :

                          P_Longitude :

                          P_ErrorCode) = *Off;

           W_Response = 'Latitude=' + %Trim(P_Latitude) +

                        ' Longitude=' + %Trim(P_Longitude);

           Dsply W_Response;

         Else;

           W_Response = 'Error Code=' + %Char(P_ErrorCode);

           Dsply W_Response;

         EndIf;

         *InLr = *On;

      /END-FREE

Here, I'm calling the function from an IF statement and displaying the GPS coordinates of the address passed as a parameter. In case something doesn't work as expected, I'm displaying the error code. Note that the copy member RTVGPS_PR contains all the necessary variable definitions for the parameters, so be careful with the names of the variables in the caller program, to avoid duplications (and consequent compilation errors). I've included source member TST_GPSADD, which has other addresses ready for testing. There, you'll find incomplete addresses, airport codes instead of the address (LAX for instance), and an invalid address (which will cause ResultSet.Found = 0). Try all of these to get a feel of the way the function works before using it on your data. By the way, if your address is from a country that has a different structure (for instance, the door number appears after the street name), you might have some problems because it will return the GPS coordinates for the street but not for the door number you specified.

You can download the source code here.

A Quality Issue

One of the output parameters of the function is the quality of the response. If you look closely at the XML, you'll see that there are two elements named "quality";  one belongs to <RESULTSET> (with uppercase Q) and the other to <RESULT> (with lowercase q). The Web service documentation explains why:

"The response contains two Address Quality elements:

• Quality: Child element of ResultSet. This element defines the best possible quality of the address specified by the input parameter.
• quality: Child element of Result. This element defines the quality of the address data for this result. If a response has multiple Result elements, each will contain a quality element.

If the result quality is less than the best possible Quality, then the accuracy of the result is less than requested. For example, suppose the input parameter is "1000 1st Ave Sunnyvale CA," but the result is "998 1st Ave Sunnyvale CA." In the response, the best possible Quality for the input parameter is 87. However, the result quality is 86 because closest street number found does not match the requested street number."

You'll find additional information and the list of quality codes here.

The RtvGpsFrmAddr function returns the one from the <RESULT>, and it's up to the programmer to decide if the quality level is acceptable or not. Ideally, if the address is accurate, you should always (or almost always) get 87 in the P_Quality parameter. Read the documentation carefully and decide what you consider acceptable.

Multiple Results

I mentioned that the function would handle only an exact match (one element in the Result array) to keep things simple. Here's what you have to do to handle multiple results:

• Transform the output parameters into arrays with the same number of elements as the Result array.
• Change the If ResultSet.Found = 1; into a For cycle that loops through the whole Result array and assign each element of the Result(index).fieldname to the respective parametername(index). Something like this: P_Quality(W_Index) = ResultSet.Result(W_Index).quality;
• In the caller program, build logic to handle the multiple responses. I won't make any suggestions here, because it will have to be a case-by-case decision.

Final Thoughts

The Yahoo Place Finder Web Service is a very powerful tool, and I've only scratched the surface here. The documentation and support forums will most definitely provide valuable help and ideas to new functions. The RtvGpsFrmAddr function is a basic implementation of the Web service, with a few limitations. It uses only a small, yet important, part of the data provided by the Web service. I urge you to adapt it to your specific needs!

The next logical step is to use the newly found richness of information. A lot can be done with the GPS coordinates, once you have them—from calculating the ideal route between stores and warehouses to analyzing and reporting on geographical coverage of stores, resellers, or clients. Instead of building something from scratch, have a look at the Geographic Information System (GIS) applications out there (Google it up!) and see how they can help your business. It's certainly helping mine!

RPG, 

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