8
Using the Location API

This document describes the location application component API. Each section of this document presents a different topic. These sections include:

• Section 8.1, "Overview"

• Section 8.2, "Managing the Location Application Components"

• Section 8.3, "Using the Geocoder Interface"

• Section 8.4, "Using the Routing API"

• Section 8.7, "Using Business Directory Services"

8.1 Overview

The Wireless Edition provides a set of location application component APIs that enable developers to include geocoding, location marks, routing, and business directory (yellow pages) components into the Wireless Edition applications. Using these APIs, developers can integrate location services from geocoding, mapping, routing and yellow page third-party providers into Wireless Edition applications without having to write custom interfaces for each service.

The Wireless Edition framework allows developers to prioritize services based on quality, availability, or cost. The location application component APIs also include a wrapper function that maps location services providers to the APIs.

This chapter defines the Location APIs.

Note: The APIs described in this chapter define the interface between the service providers and the Wireless Edition developer. The APIs themselves mostly do not implement the core functionality. For more information on the APIs, refer to the Wireless Edition Java documentation.

8.2 Managing the Location Application Components

The Java class SpatialManager manages the following components:

• Geocoding Interface

• Point Interface

• Location Interface

• Mapper

• Router

• YPFinder

8.3 Using the Geocoder Interface

The Geocoder Interface provides the geographic location of a specified address using the geocodeAddress method. You enter the text for a geocoder in the same way that you enter the address on a standard letter. After you enter the address, the geocoding service translates it into geographic coordinates and expresses the location as a geographic point. In the following example, the Geocoder returns the coordinate of x:-122.262/y:37.532 as the location of the given address.

firmName: "Oracle"

firstLine: "500 Oracle Parkway"

secondLine " "

lastLine: "Redwood City, CA 94065"

match mode: "tight"

Result: x:-122.262/y:37.532

The Geocoder Interface is a required component for any spatial capability, including the Routing, Yellow Page, Mobile Positioner, Region, Mapper, or LocationMark functions. The Geocoder Interface defines the top-level class that an application programmer accesses to use geocoding.

The Point Interface

The Geocoder API uses the Point objects to define the longitude and latitude of a point. The Point Interface uses the following methods:

• getLabel

• setLabel

• getLatitude

• setLatitude

• getLongitude

• setLongitude

• getRadius

• setRadius

• getDistance

The Location Interface

The Location Interface extends the Point Interface by defining a location with an address and longitude/latitude. The Location Interface uses the following methods:

• getCompanyName

• setCompanyName

• getAddressLine1

• setAddressLine1

• getAddressLine2

• setAddressLine2

• getAddressLastLine

• setAddressLastLine

• getBlock

• setBlock

• getCity

• setCity

• getCounty

• setCounty

• getState

• setState

• getPostalCode

• setPostalCode

• getPostalCodeExt

• setPostalCodeExt

• getCountry

• setCountry

• getMatchMode

• setMatchMode

• geocode

Note: Some providers may not be able to correctly identify some elements of the address, such as getCity or getState if the location object is constructed using firstLine, secondLine, and lastLine, because lastLine can contain city, state, and postal code formats that vary according to country and style.

8.3.1 Third-Party Geocoders

The Wireless Edition uses a Java interface to call the geocoders from the middle tier. The Wireless Edition API uses a ranked list of geocoders. Should the first of these geocoders fail, then the subsequent geocoders are used to return the search result. The failover is transparent to the user. An example of an XML configuration file for this API is as follows:

<?xml version="1.0" standalone="yes"?>
<Providers>
  <Provider
     ProviderName   ="MapQuest"
     ProviderTmpl   ="oracle.panama.spatial.geocoder.GeocoderImplMapqeust"
     URL            ="enterprise.mapquest.com"
     UserName       ="..."
     UserPassword   ="..."
     Parameters     = "..."/>
  <Provider>
     ProviderName   ="Vicinity"
     ProviderTmpl   ="orcale.panama.spatial.geocoder.GeocoderImplVicinity"
     URL            ="demo.vicinity.com"
     UserName       ="..."
     UserPassword   =""/>
   <Provider>
     ProviderName   ="MapInfoDirect"
     ProviderTmpl   ="orcale.panama.spatial.geocoder.GeocoderImplMapInfo"
     URL            ="http://..."
     UserName       ="..."
     UserPassword   =""/>
   <Provider>
     ProviderName   ="MapInfo"
     ProviderTmpl   ="orcale.panama.spatial.geocoder.GeocoderImplSQL"
     URL            ="http://..."
     UserName       ="..."
     UserPassword   =""/>
</Providers>

8.3.2 Reliability of Service

The Wireless Edition can use a set of third-party geocoders to ensure reliability. If one service fails, another acts as a backup. The Geocoding API fails if the entire set of external geocoders fail, or if access to the Web becomes unavailable. In the latter case, all Wireless Edition services, including the geocoders, become unavailable to the Wireless Edition. The Geocoder API automatically fails over if the geocoder becomes inaccessible over the Web, if it does not support addresses in the country where an address has been requested, or if it cannot find the requested address.

8.3.3 Ambiguous Address

If a user requests an address that cannot be identified by an exact location, the GeoCodeResult returns an array of location objects.

8.4 Using the Routing API

The Routing API provides driving directions and maps. This API is a standard interface between a routing service provider and the Wireless Edition developer. The Routing API includes route optimization methods to determine for example the shortest route and displays search results as a set of driving maneuvers. The Routing API can display search results as an overall map of the route as well as a map of the maneuvers themselves. In addition, the Routing API displays the geometry of the route (an array of points). The search results also include the distance of a specific driving maneuver and the total distance of the entire trip.

The Router Interface

The Router interface defines how an application programmer accesses the routing service. An object of a class implementing this interface is returned by the SpatialManager.

8.4.1 Source, Destination, and Via Points

The Routing API provides driving directions based on a source or starting point and a destination or end point. These points can be expressed as addresses or as longitudes and latitudes.

The Routing API may also include intermediate "via points". These via points are optional, and the API includes them when a traveler needs to start from point A, stop at points B and C, and then ends the journey at point D. In this case, point A is the source point, D is the destination point, and points B and C are the via points. Source, destination, and via points are the input parameters to the routing computation function described in Section 8.4.4, "Driving Distance".

8.4.2 Maneuver List

The Routing API expresses search results as a list of maneuvers or driving instructions. In addition, the Routing API describes the distance travelled during a single maneuver as well as the distance travelled up to, but not including, a certain maneuver. For example, the Routing API can return search results that include such instructions as "Turn RIGHT onto FRANKLIN ST." Maneuver information also includes a detailed maneuver map and a list of longitude and latitude coordinate points that correspond to each maneuver.

The Routing API uses the Maneuver class to define a single maneuver in a route.

8.4.3 Map Displays

The Routing API uses requestMap to include a map of the route. The Routing API provides two types of maps: an overview map (getOverviewMap) and a maneuver map (getManueverMap). These maps, which are returned as Java image objects or URLs, can be displayed in any size, scale, or zoom levels.

Note: The application may affect the size, scale, or zoom level of a map. In addition, some service providers may not support parameters for changing the size, scale, or zoom level of a map and may only support a single image format. Because different devices require different image formats, the application is responsible for image transformation between formats.

The Routing API uses requestGeomery to specify whether the exact geometry of the route is requested. This option, along with requestMap, can be disabled if the application only shows the list of maneuvers.

8.4.4 Driving Distance

The Router interface defines the top-level class that the application programmer accesses for routing. The Routing API uses computeRoute to perform routing computation based on source, destination, via points, and the routing options.

8.4.5 Routing Settings

The Routing API uses the RoutingSettings class to specify whether to generate a map or driving directions. Developers can specify the algorithms to choose the shortest distance from the source point to the destination point or the shortest driving time. The RoutingSettings class has two routing option types: basic and secondary. The basic options, which application developers specify in the constructor of a RoutingSettings object, include the following:

• Requests for maps.

• Requests for the geometry of a route.

Application developers can define the secondary options as either mandatory or preferred. The secondary options include the following:

• Optimization methods that compute the shortest driving time and shortest route.

• Map sizing functions.

• Route properties, such as avoid toll roads, avoid ferry lanes, and avoid limited access highways.

The secondary options can be set using setSecondaryOption. The first parameter is a RoutingOption object, which is a static constant defined in the RoutingOption class. It identifies the option for which a value is set. The second parameter is a String representing the value.

A secondary option is defined as mandatory by setSecondaryOptionRequired. The first parameter is the RoutingOption and the second parameter specifies whether this option requirement is mandatory. Unless this function is called, the default value is used.

The following defaults are applied if the application developer requests a secondary option without specifying whether it is mandatory or preferred:

• Optimization method: preferred

• Avoid Ferry: preferred

• Avoid Limited Access Hwy: preferred

• Avoid Toll: preferred

• Overview Map Size: mandatory

• Maneuver Map Size: mandatory

• Overview Map scale and zoom level: preferred

• Maneuver Map scale and zoom level: preferred

Note: If a secondary option is defined as mandatory but is not supported by a provider, the API automatically fails over to the next provider. If a secondary option is preferred but is not supported by a provider, the API does not check if other providers support the option.

The secondary class also includes the TSP (Traveling Salesman Problem) algorithm, useTSP. If useTSP is set to true, the routing provider is instructed to find a near-optimal route that leaves the source and visits each via point once before arriving at the destination. The order in which the traveller visits the via points may be different from the order specified in the vector of via points. If useTSP is set to false, the order of the visit is the same as that specified in the vector of via points.

8.4.6 Routing Search Results

The Routing API uses RoutingResult class to define the output of a routing request. The routing result components include a list of maneuvers, the total distance of the trip, the total estimated driving time, and an overview map.

Multiple Language Support

If the routing provider supports multiple languages, then the Routing API selects a language based on the Java Locale object specified in the request to the router. The language setting can affect the maneuver narratives and the distance measures.

Routing XML File

An XML configuration file contains information about the routing service providers. For this example, the providers are MapInfo, MapBlast, and MapQuest.

<?xml version+"1.0" standalone="yes"?>
<providers>
  <Provider>
    ProviderName = "MapInfo" 
    ProviderImpl = "oracle.panama.spatial.router.MapInfoRouterImpl"
    URL = "http://..."
    UserName = "..."
    UserPassword = "..."
    Parameters = "..."/> 
Provider>
    ProviderName = "MapBlast" 
    ProviderImpl = "oracle.panama.spatial.router.MapBlastRouterImpl"
    URL = "http://..."
    UserName = "..."
    UserPassword = "..."
    Parameters = "..."/> 
Provider>
    ProviderName = "MapQuest" 
    ProviderImpl = "oracle.panama.spatial.router.MapQuestRouterImpl"
    URL = "http://..."
    UserName = ""
    UserPassword = "..."
    Parameters = "..."/> 
</Providers>

8.4.7 Display Functions

The Wireless Edition uses Imagex and ImageFormats classes to perform general operations on image files, such as maps. The ImageFormats class defines identifiers for various formats commonly used on wireless devices. The ImageX class enables the following operations:

• Conversion between image formats, such as .gif, .bmp, and .wbmp.

• Rotating an image by multiples of 90 degrees.

• Scaling an image to a larger or smaller target display.

• Flipping an image horizontally, vertically, diagonally and anti-diagonally.

The Imagex class enables the transformation of an image from one image format, such as .gif, into another format, such as .wbmp. For example, an external provider of a mapping service might support a .gif image while a particular device can only interpret .wbmp files. The Wireless Edition's ImageX API enables the creation of the .wbmp version of the image files.

In addition to image conversion, the ImageX class enables users to rotate images by 90 degrees for better viewing. For example, if a user retrieves a tall, vertical image that cannot be fully viewed on a wide display, the user can rotate the image by 90 degrees in either direction to fit it on a wide device display for complete viewing. The ImageX class enables images, such as maps, to be viewed in their entirety, rather than displaying them in several segments.

The ImageX class enables images to be scaled to fit the display of a device. Because transformation from .gif to .wbmp for display on a cell phone may also involve a scaling operation to make the image fit on the small display, the ImageX class enables scaling to be performed simultaneously with image format transformation. Combining scaling with image transformation enables developers to create several target images from one source (such as a 200x200 .bmp and a 100x50 .wbmp from the original 800x600 .gif), using one function call for each.

The flipping and rotation operations are not combined with image format transformation into a single operation, as these operations always result in .bmp target files. Rather than perform a rotation operation for several different target transformations, developers perform the rotation operation only once and then execute multiple format transformations from the .bmp target files. The quality of the results is not affected, while performance increases.

8.4.8 Mapping

The Wireless Edition uses the Mapper Interface to retrieve maps that display a list of marked points, addresses and business, a complete route, or a single maneuver.

In addition, the Mapper Interface enables users to adjust map images retrieved from third-party providers to any resolution and aspect ratio. In some cases, the requested map image may not display well on the target device. For example, if a user requests a map of California to display on a cell phone screen with a resolution of 300 (width) ¥ 100 (height), the aspect ratio of the retrieved map of California may not match that of the cell phone's display screen. There are four solutions to this problem:

1. A map of size 50 (width) ¥ 100 (height) is created and the rest of the cell phone screen remains empty. This is similar to taking a group photo vertically and then cutting the upper and lower sections off.

2. A map of size 300 (width) ¥ 100 (height) is created but only a small segment -- 50 (width) ¥ 100 (height) -- is covered by the area of interest (AOI). The remainder is a buffer to fill the screen. This is similar to taking a portrait photo horizontally, rather than vertically. To view the display properly, the user must turn the cell phone 90º.

3. A map of size 300 (width) ¥ 600 (height) is created and cut in 6 segments measuring 300 (width) ¥ 100 (height). This is similar to taking a group photo as a set of neighboring vertical segments and stitching them together.

4. A map of size 100 (width) ¥ 300 (height) is created and a relatively large segment of size 100 (width) ¥ 200 (height) is covered by the AOI. To receive a map of size 300 (width) ¥ 100 (height), the original map is turned by 90º. The user must turn the cell phone accordingly to properly view the display.

In the Mapper Interface enables Solutions 2 and 3 separately, or in combination with Solution 4. The Mapper API describes the following functions:

• Returning single map images or matrices of map segments.

• Taking arrays of points, single points, routes or maneuvers to be mapped.

• Taking bounding boxes as parameters or inferring them from the marked points.

Each function can turn the image by 90º if doing so better matches the aspect ratio of the AOI and the visualization of the map image.

8.4.8.1 Mapping Routes and Maneuvers

Mapping of routes and maneuvers is more restricted than the mapping of points because maps of routes are actually provided by the routing component.

XML File

<?xml version="1.0" standalone="yes"?>
<Providers>
<Provider
  ProviderName  = "Vicinity"
  ProviderImpl  = "oracle.panama.spatial.mapper.MappingProviderVicinity"
  URL           = "http://..."
  UserName      ="..."
  UserPassword  = ""
  Parameters    = ""/>
<Provider
  ProviderName  = "Mapquest"
  ProviderImpl  = "oracle.panama.spatial.mapper.MapperImplMapquest"
  URL           = "..."
  UserName      = "..."
  UserPassword  = ""
  Parameters    = "..."/>
<Provider
  ProviderName  = "eLocation"
  ProviderImpl  = "oracle.panama.spatial.mapper.MappingProviderELocation"
  URL           = "http://..."
  UserName      =    ""
  UserPassword  =    ""
  Parameters    = ""/>
</Providers>

8.5 Finding a User's Location

The Mobile Positioner retrieves a mobile user's current physical location. The Mobile device positioning is performed by calling function requestPosition() in class MobilePositioner. This function takes user name, password and subscriber ID as input parameters. (You can set user name and password to null if they are not needed). The positioning result is encapsulated in a PositionResult object. Although different underlying positioning servers may return the position result in different formats, you can access them through the Wireless Edition interface. A PositionResult has an array of PositionArea objects. A PositionArea can be either a point location or a region and it has an accuracy level which indicates how precision of the positioning.

8.6 The Locationmark Interface

The form factor of some mobile devices limits the inputting and display of such spatial information as street address and location coordinates. To solve this problem, the Wireless Edition stores spatial information as a location mark, a name of a location that is meaningful to the user. For example, the location mark My Home identifies "123 Main Street, Somewhere City, CA 12345; Longitude = -122.42, Latitude = 37.58". Likewise, the location mark Downtown San Francisco corresponds to "The rectangle geometry within bounding points (Longitude/Latitude = -122.49, 37.79) and (Longitude/Latitude = -122.41, 37.74)."

Note: Location marks must be identified as a point for this release of Oracle9i Application Server Wireless Edition.

Locationmarks free users from inputting lengthy and complex alphanumeric strings on their mobile devices. Instead, users enter and manage the underlying spatial information to the locationmarks on a desktop computer. Users access this information by selecting the locationmark on their mobile device. The location marks are stored in the Wireless Edition repository. For more information on creating locationmarks, see Oracle9i Application Server Wireless Edition Implementation Guide.

Each user-defined locationmark is stored in the Wireless Edition repository. Each of these locationmark objects has a unique object ID registered in the object table. The value pair of the user name and locationmark name are used together as a composite key to identify the locationmark.

Geocoding provides the spatial information. The location marks are created using the LocationMark class.

8.7 Using Business Directory Services

Each external provider implements business directory, or yellow pages (YP) services differently; each provider has its own method of categorizing businesses. Some providers organize YP categories into a flat list, others organize them into a hierarchy tree. The hierarchies themselves may be deep or shallow, with a high or low fan-out, or they may be balanced or unbalanced.

To unify different hierarchy styles, those implementing the Wireless Edition must provide a custom hierarchy. Each node in the hierarchy can have references to a category of one or more service providers. The Wireless Edition developer can customize the YP service to meet customer need by listing these provider service references. A Wireless Edition developer can rank YP services by popularity or by cost.

In searching for a business, a user may start traversing the hierarchy at its root, the default starting point. Alternatively, a user may enter a keyword that matches a starting point within the hierarchy.

8.7.1 Yellow Pages XML Files

Category Hierarchy Definition File

The customized hierarchy is represented as an XML file called the Category Hierarchy Definition File. Each category in this file can have any number of subcategories. There is no restriction on the number of nesting levels in the Category Hierarchy Definition File. Each node in the hierarchy tree can be linked to multiple business directory service content providers. An example of the Category Hierarchy Definition File is as follows:

<?xml version ="1.0" standalone = "yes"?>
<Categories>
  ...
  <Category
    CategoryName = "Berry crops">
    <Provider
      Name = "..."
      Parameter = "..."/>
      <Category
      CategoryName = "Cranberry farm">
      <Provider
        Name = "..."
        Parameter = "..."/>
      </Category>
      ...
      <Category
        CategoryName = "Ornamental nursery products">
        <Provider
          Name = "..."
            Parameter = "..."/>
          </Category>
             <Category
             CategoryName = "Florists'greens and flowers">
             <Provider
               Name = "..."
               Parameter = "..."/>
             </Category
           </Category  
           <Category
             CategoryName = "Crops grown under cover">
             <Provider
               Name = "..."
               Parameter = "..."/>
           </Category>
          </Category>
          ...
        </Categories> 

Provider Description File

The Provider Description File is an XML file that contains information about all the 
accessible business directory services content providers. An example of a Provider 
Description file is as follows:
<?xml version="1.0" standalone = "yes"?>

<Providers>
  <Provider
    ProviderName = "InfoUSALocal"
    ProviderImpl = "oracle.panama.spatial.yp.YPFinderImplInfoUSAlocal"
    URL = "jdbc:oracle:thin:@..."
    UserName = "..."
    UserPassword = "...">
   </Provider>
   <Provider
<Provider
    ProviderName = "InfoUSA"
    ProviderImpl = "oracle.panama.spatial.yp.YPFinderImplInfoUSA"
    URL = "..."
    UserName = "..."
    UserPassword = "...">
   </Provider>
   <Provider
<Provider
    ProviderName = "InfoUSALocal"
    ProviderImpl = "oracle.panama.spatial.yp.YPFinderImplMapquest"
    URL = "jdbc:oracle:thin:@..."
    UserName = "..."
    UserPassword = "...">
   </Provider>
   <Provider
<Provider
    ProviderName = "InfoUSALocal"
    ProviderImpl = "oracle.panama.spatial.yp.YPFinderImplVicinity"
    URL = "..."
    UserName = "..."
    UserPassword = "...">
   </Provider>
</Provider

8.7.2 Yellow Pages API

The yellow pages API provides application developers with the means to accommodate user search requests and search methods. For example, application developers list all businesses using getBusinesses in the YPFinder Interface. For searches starting at the root of the hierarchy, application developers use getCategoryAtRoot in the YPFinder interface. For searches that start from within the hierarchy using keywords, application developers use getCategoryAtPath in the YPFinder interface. Application developers can list the directly related business subcategories using getSubCategories in the YPCategory class. At the most specific, or leaf category level, application developers use getBusiness in the YPFinder simple interface to get a set of businesses. A business object of the YPBusiness class contains a name, location, telephone number, and description.

YPFinder Interface

The YPFinder interface defines how an application programmer accesses the 
business directory service. An object of a class implementing the interface is 
returned by the SpatialManager.

YPCategory Class

The YPCategory class defines a single category that is part of the hierarchy. This class lets users access businesses in the category and subcategories of the category.