GPS-Enable the Addresses in Your Database!
This was originally in a wonderful article in the now-dead mcpressonline website. I had saved it to my hard-drive of saucy IBM i Programming techniques, so here it is – resurrected from the dead.Original Source – http://www.mcpressonline.com/programming/rpg/gps-enable-the-addresses-in-your-database.html
Do you realize how much your business can do with GPS coordinates?
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 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 IBM i System 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.
Foremost, keep in mind that even though Yahoo Place Finder Web service is free, there are a few rules to abide by. There are two important things to keep in mind. The Google Maps API Terms of Service allow you to use geocodes derived from the service on Google Maps or Google Earth only. You may not sell or distribute them in other fashion. Geocoding changes often as our data gets more and more accurate.
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.
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>
(enter your username & password when asked)
put httpapi.savf QGPL/HTTPAPI
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:
CRTCLPGM INSTALL SRCFILE(LIBHTTP/QCLSRC)
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</p> Else; // Oops! Something went wrong! Use the P_ErrorCode to react accordingly</p> 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</p> 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:
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:
Supported Response Formats
The PlaceFinder Web service supports the following response formats:
|Format||How to Specify||Description|
|XML||default||eXtensible Markup Language is an open standard specification for serializing structured data. See Example.|
|Serialized PHP||Include P in the Flags Parameter.||A format for storing structured data in PHP. See Example.|
The Web service returns the following error codes in the response:
- 0: No error
- 1: Feature not supported
- 100: No input parameters
- 102: Address data not recognized as valid UTF-8
- 103: Insufficient address data
- 104: Unknown language
- 105: No country detected
- 106: Country not supported
- 10NN: Internal problem detected
The following tables describe the data elements in a response.
|Container||Top-level element for the response. Container for the remaining elements in this table. More than one result element may be returned if the given address is ambiguous.|
|Integer||Error code. See Error Codes for possible values.|
|String||Error message (locale specific).|
|String||The language and country. A two-letter ISO-639 major language code and a two-letter ISO-3166-1 alpha-2 country code, separated by either a hyphen or underscore.|
|Integer||Best possible quality of the location parameter (input address). See Address Quality for details.|
|Integer||Number of Result elements.|
|Container||Contains elements associated with a single match result. See Result Sub-elements.|
|Integer||Quality of the result. Returned if P flag is not set. See Address Quality for details.|
|Float||Latitude of matched point in degrees, should be on a road center-line. Returned if P flag is not set.|
|Float||Longitude of matched point in degrees, should be on a road center-line. Returned if P flag is not set.|
|Float||Latitude of offset point in degrees, representing building/parcel setback from road center-line. Returned if P flag is not set and if Offset is greater than 0.|
|Float||Longitude of offset point in degrees, representing building/parcel setback from road center-line. Returned if P flag is not set and if Offset is greater than 0.|
|Integer||Radius of matched area in meters. Returned if P flag is not set. Default if E flag is set, dynamic if not.|
|Container||Defines the extent of a box that encloses an area. Returned if P flag is not set and X flag is set. See Bounding Box Sub-elements for details.|
|String||POI/AOI name or Airport code. Returned if C flag is not set.|
|String||First line of address (House Street UnitType Unit). Returned if C flag is not set.|
|String||Second line of address (City State Zip in the US). Returned if C flag is not set.|
|String||Third line of address. Returned if C flag is not set.|
|String||Fourth line of address. Returned if C flag is not set.|
|String||Cross streets nearest to location. Returned if C flag is not set and C gflag is set.|
|String||House number. Returned if C flag is not set.|
|String/Container||Street name or container for detailed street data (if S flag is set). Returned if C flag is not set. See Street Sub-elements.|
|String/Container||Cross street name or container for detailed street data (if S flag is set). Returned if C flag is not set. See XStreet Sub-elements.|
|String||Unit type. Returned if C flag is not set.|
|String||Unit/Suite/Apartment/Box. Returned if C flag is not set.|
|String||Postal code. Returned if C flag is not set.|
|String||Neighborhood name. Returned if C flag is not set and G flag is not set. See Neighborhood Element for details.|
|String||City name. Returned if C flag is not set and G flag is not set.|
|String||County name (US/Canada only). Returned if C flag is not set and G flag is not set.|
|String||State/Province name. Returned if C flag is not set and G flag is not set.|
|String||Country name. Returned if C flag is not set and G flag is not set.|
|String||Level 4 area name (neighborhood). Returned if C flag is not set and G flag is set.|
|String||Level 3 area name (city/town/locality). Returned if C flag is not set and G flag is set.|
|String||Level 2 area name (county). Returned if C flag is not set and G flag is set.|
|String||Level 1 area name (state/province). Returned if C flag is not set and G flag is set.|
|String||Level 0 area name (country). Returned if C flag is not set and G flag is set.|
|String||County ISO 3166-2 code. Returned if C flag is not set.|
|String||State ISO 3166-2 code. Returned if C flag is not set.|
|String||Country ISO 3166-1 code. Returned if C flag is not set.|
|String||Level 2 area ISO 3166-2 code. Returned if C flag is not set and G flag is set.|
|String||Level 1 area ISO 3166-2 code. Returned if C flag is not set and G flag is set.|
|String||Level 0 area ISO 3166-1 code. Returned if C flag is not set and G flag is set.|
|String||Timezone tz name. Returned if C flag is not set and T flag is set.|
|String||Telephone area code. Returned if C flag is not set and R flag is set.|
|String||Unique zip code. Returned if C flag is not set.|
|String||A unique string derived from the returned address. Can be used by an app to index content based on the address.|
|Integer||Where On Earth ID for area. Returned if C flag is not set.|
|Integer||Where On Earth place type for area. Returned if C flag is not set.|
|String||Street name. Returned if S flag is set.|
|String||Street prefix directional. Returned if S flag is set.|
|String||Street prefix type. Returned if S flag is set.|
|String||Street body. Returned if S flag is set.|
|String||Street suffix type. Returned if S flag is set.|
|String||Street suffix directional. Returned if S flag is set.|
|String||Cross Street name. Returned if S flag is set.|
|String||Cross Street prefix directional. Returned if S flag is set.|
|String||Cross Street prefix type. Returned if S flag is set.|
|String||Cross Street body. Returned if S flag is set.|
|String||Cross Street suffix type. Returned if S flag is set.|
|String||Cross Street suffix directional. Returned if S flag is set.|
Bounding Box Sub-elements
|Float||North latitude in degrees. Range is -90.0 to 90.0|
|Float||South latitude in degrees. Range is -90.0 to 90.0|
|Float||East longitude in degrees. Range is -180.0 to 180.0|
|Float||West longitude in degrees. Range is -180.0 to 180.0|
The value of an Address Quality element defines the granularity of the location described by an address. It is expressed as an integer between 0 and 99; higher values indicate more precision. Values of 80 or greater describe points; values less than 80 and 70 or greater describe lines; values less than 70 describe areas. A value of 0 indicates that no location could be extracted from the address data.
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 mulitple
Resultelements, each will contain a
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.
The following tables list the possible values for the Address Quality elements.
|PointsAddress Quality Value||Description|
|87||Address match with street match|
|86||Address mismatch with street match|
|85||Address match with street mismatch|
|84||Address mismatch with street mismatch|
|82||Intersection with street match|
|80||Intersection with street mismatch|
|LineAddress Quality Value||Description|
|75||Postal unit/segment (Zip+4 in US)|
|74||Postal unit/segment, street ignored (Zip+4 in US)|
|71||Street match, address ignored|
|AreaAddress Quality Value||Description|
|64||Postal zone/sector, street ignored (Zip+2 in US)|
|60||Postal district (Zip Code in US)|
|59||Postal district, street ignored (Zip Code in US)|
|49||Level4, street ignored (Neighborhood)|
|39||Level3, level4 ignored (City/Town/Locality)|
|29||Level2, level3 ignored (County)|
|19||Level1, level2 ignored (State/Province)|
|9||Level0, level1 ignored (Country)|
|0||Not an address|
Now let’s 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.
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.
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.“
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.
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.
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!