Use the procedure explained here to help your clients find the Points of Interest (POIs) near your place of business, just like a GPS device would!

While the previous tips of this series have been focused on retrieving information relevant to your company, this time it'll be a bit different: this one is for your clients.

Knowing beforehand that there's a nice restaurant or bar near your car dealership is useful when you go in for a small repair that won't take long. You can either find out for yourself or, if your dealership has a really nice service, its Web site or customer support line will be able to tell you. From a company's point of view, having additional information available about its locations (stores, offices, branches) might provide an edge over the competition.

This TechTip explains the "Find Nearby POIs" Web service from GeoNames in order to achieve that goal. Even though the Web service is provided by GeoNames, the data actually comes from OpenStreetMap. I recommend that you learn more about OpenStreetMap (it's a great open-source project) and read their copyright and license.

Let's start by looking at the Find Nearby POIs Web Service. Being a REST Web service, it is invoked by composing a URL (in which you include the GPS coordinates of the location) such as the one below:

http://api.geonames.org/findNearbyPOIsOSM?lat=37.451&lng=-122.18&username=demo

It will return an XML document with the POIs that are near the coordinates indicated:

<geonames>

  <poi>

    <name>Cook's Seafood</name>

    <typeClass>amenity</typeClass>

    <typeName>restaurant</typeName>

    <lng>-122.1795529</lng>

    <lat>37.4516093</lat>

    <distance>0.08</distance>

  </poi>

  <poi>

    <name>Starbucks</name>

    <typeClass>amenity</typeClass>

    <typeName>cafe</typeName>

    <lng>-122.1803386</lng>

    <lat>37.452055</lat>

    <distance>0.12</distance>

  </poi>

  <poi>

    <name>Safeway</name>

    <typeClass>shop</typeClass>

    <typeName>supermarket</typeName>

    <lng>-122.1787081</lng>

    <lat>37.4507461</lat>

    <distance>0.12</distance>

  </poi>

  <poi>

    <name>Akasaka</name>

    <typeClass>amenity</typeClass>

    <typeName>restaurant</typeName>

    <lng>-122.1809239</lng>

    <lat>37.4524367</lat>

    <distance>0.18</distance>

  </poi>

</geonames>

The <poi> element is composed of the following sub-elements:

• <name>—The name of the point of interest (POI)
• <typeClass>—The class of the POI, according to the OpenStreetMap Map Features classification
• <typeName>—The type (or sub-class) of POI, again according to the OpenStreetMap Map Features classification
• <lng>—The longitude coordinate of the POI
• <lat>—The latitude coordinate of the POI
• <distance>—The distance between the POI's coordinates and the ones indicated on the Web service invocation.

Now, examine the XML. This time, there's a new type of reply: instead of having only one set of similar data in the response XML (<timezone> on the first tip and <country> in the second), here we have multiple sets (the <poi> element repeats multiple times). In order to handle this, a slightly different approach is required in both the procedure's parameters and the data structure used on the XML-INTO opcode; they must have the ability of storing multiple instances of the same type of data. In other words, they must be arrays.

In the QCPYLESRC/RTVFNP_PR source member, I've defined a new data structure, t_poi, with a structure similar to the <poi> element and used it to define the XML-INTO data structure:

D GeoNames        DS                  Qualified                      

D   Poi                               LikeDS(t_Poi) Dim(C_MaxElems)  

D   Status                            LikeDS(t_Status)               

And this is the procedure's parameter that will pass the POIs back:

DP_Poi_DS         DS                  LikeDS(t_Poi) Dim(C_MaxElems)

I'll explain the rest of the procedure's parameters later. Now, notice the Dim(C_MaxElems). This turns the data structure into an array, which fits our needs, but it will require additional coding when passing the values from the GeoNames.Poi data structure to the P_Poi_DS parameter:

   For W_Idx = 1 to C_MaxElems;                                 

     If Geonames.Poi(W_Idx).TypeClass <> *Blanks;

       P_Poi_DS(W_Idx).Name = Geonames.Poi(W_Idx).Name;

       P_Poi_DS(W_Idx).TypeClass = Geonames.Poi(W_Idx).TypeClass;

       P_Poi_DS(W_Idx).TypeName = Geonames.Poi(W_Idx).TypeName;

       P_Poi_DS(W_Idx).Lng = Geonames.Poi(W_Idx).Lng;

       P_Poi_DS(W_Idx).Lat = Geonames.Poi(W_Idx).Lat;

       P_Poi_DS(W_Idx).Distance = Geonames.Poi(W_Idx).Distance;

       P_NbrElems += 1;

     Else;

       Leave;

     EndIf;

   EndFor;

Here, I'm looping through the GeoNames.Poi array until one of two things happens: either the last element in the array is reached or the current element of the array doesn't contain a POI. C_MaxElems is a numeric constant, set to 20 in QCPYLESRC/RTVFNP_PR. During my tests, I never got more than 10 POIs from the Web service, regardless of the GPS coordinates.

Now for the procedure itself: as usual, you'll be able to call it from an IF statement, because it returns *ON if something goes wrong. Here's an example:

If RtvPOIFrmGPS(P_Latitude : P_Longitude : P_Poi_DS: P_NbrElems:  P_ErrCode : P_ErrMsg ) = *Off;

  // Do something with P_Poi_DS and P_NbrElems

EndIf;

The procedure's parameters include the usual P_Latitude, P_Latitude, P_ErrCode, and P_ErrMsg that I used on the first two procedures. The specifics here are the P_Poi_DS and P_NbrElems. This last parameter contains the number of elements of the P_Poi_DS array that contain data. Even though the maximum number of elements of the array is set to 20 (see C_MaxElems), that doesn't mean you'll always get 20 POIs. Actually, depending on how precise your GPS coordinates are (i.e., how many "decimal places" your coordinates have), you might receive an empty array, in the worst-case scenario. As I said before, the maximum I got during my tests was 10 POIs, but I couldn't get a feedback from GeoNames or OpenStreetMap about the maximum number of POIs the Web service returns.

Finally, a quick look at the provided example in the QRPGLESRC/TST_FNPADD source member shows the usual orchestration of Web services, starting with an address (in this case, of the biggest mall in the United States, according to Wikipedia). For simplicity's sake, the example lists the name of only the first POI found, but it should be clear enough on how to use the P_Poi_DS array.

You can download the source code for this article here.

That's all for this TechTip. If you have any questions or suggestions, feel free to contact me!

The next TechTip of this series will demonstrate how the same Web service can have different sets of input parameters: the "Find Nearby Wikipedia" Web service can be used by passing the GPS coordinates or the postal code of the location you want to search about.

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