Class OracleELocation

Object
   |
   +--OracleELocation

class OracleELocation

This class provides a number of convenient methods for accessing Oracle's eLocation Geocoding and Routing services.
Defined in oracleelocationv3.9.js

Field Detail

AUTOCOMPLETE_ON_SELECTION_DO_NOTHING

<static> Object AUTOCOMPLETE_ON_SELECTION_DO_NOTHING

eLocation Autocomplete behavior: Don't modify input text when an option is selected

AUTOCOMPLETE_ON_SELECTION_REPLACE

<static> Object AUTOCOMPLETE_ON_SELECTION_REPLACE

eLocation Autocomplete behavior: Replace input text with current selection (default)

ERROR_GEOCODE_FAILED

<static> Object ERROR_GEOCODE_FAILED

Geocoder Error code: Geocoder has encounted internal error.

ERROR_ROUTE_ADDR_INVALID

<static> Object ERROR_ROUTE_ADDR_INVALID

Router Error code: One or more input addresses can not be geocoded or the geocoded results might not be accurate.

ERROR_ROUTE_FAILED

<static> Object ERROR_ROUTE_FAILED

Router Error code: Router has encounted internal error.

ERROR_ROUTE_NOT_FOUND

<static> Object ERROR_ROUTE_NOT_FOUND

Router Error code: Route can not be calculated.

ERROR_UNEXPECTED_SERVER_RESPONSE

<static> Object ERROR_UNEXPECTED_SERVER_RESPONSE

eLocation Error code: eLocation returned an unexpected response.

TARGET_CLIENT

<static> Object TARGET_CLIENT

The target map client. By default, Oracle Maps (v2)

OracleELocation

OracleELocation(<String> elocURL, <String> localImagesURL, <String> appId)

Parameters:
elocURL - the eLocation service base URL, which specifies the host and application context root for the eLocation service. The default value is https://elocation.oracle.com/elocation.
localImagesURL - the local images URL, useful when loading images from a different server domain. Images in map markers could taint the map canvas and cause display errors when capturing the map using html2canvas API, by loading those marker images from a local source prevents the canvas from being tainted. The default value is elocURL + /ajax/images/
appId - the Application's key to use the service.

attachEventListenerToRoute

void attachEventListenerToRoute(routeId, eventType, eventHandler)

Attach event handlers to routes and route segments, such as:

• OM.event.MouseEvent.MOUSE_CLICK
• OM.event.MouseEvent.MOUSE_RIGHT_CLICK
• OM.event.MouseEvent.MOUSE_OVER
• OM.event.MouseEvent.MOUSE_OUT
The eventHandler function should define a parameter where the actual event will be filled.

Parameters:
routeId - The feature ID of the desired route to attach the event to
eventType - The event type to handle. Options are: OM.event.MouseEvent.MOUSE_CLICK, OM.event.MouseEvent.MOUSE_RIGHT_CLICK, OM.event.MouseEvent.MOUSE_OVER, OM.event.MouseEvent.MOUSE_OUT
eventHandler - The function that will handle the event.

autocomplete

void autocomplete(<Object> input, <Function> callback, <Object> options)

This method adds event listeners to an HTML input element rendered on the page and retrieves address suggestions based on what the user types. Once the auto-complete service finds the appropriate addresses, a list of options is displayed below the input text field and the user is able to click on any of them (or use the arrow keys to navigate through them). After a user selects an address, that selection's text replaces the text on the input field, by default. A geocode call can be chained to obtain the longitude/latitude information, see the description for the options parameter below.

When an address is selected, if a callback was provided then it is invoked with the user's selection, wrapped in an object with the following attributes:

• address(Object): This is the selected address from the list, with the following properties:
  • fullAddress(String): The full address as displayed in the address suggestion list.
  • houseNumber(String): The house number, if any.
  • street(String): The street name, if any.
  • settlement(String): The city or settlement.
  • region(String): The state or region.
  • postalCode(String): The postal or zip code.
  • country(String): The ISO-2 country code.
• inputElement(Object): This is the input DOM element that triggered the auto-complete (useful when there is more than one input text with auto-complete enabled).
• suggestions(Array): This is the list of suggestion addresses, where each element is a String with the full address.
• detailedSuggestions(Array): An array of object addresses presented as the auto-complete suggestions, where each object represents an address (as described in the address property above).

The application can also control whether to draw the selected address on the map or not (by first geocoding the address), the minimum characters that will trigger the auto-complete, the number of address suggestions, etc. by providing an auto-complete options object, which can have the following attributes:

• minChars(int): This attribute specifies minimum characters in order to trigger the auto-complete for the input text. By default, this property is set to 2 (auto-complete will trigger when the user has typed at least two characters). This property value should be within 0 and 4, both inclusive.
• maxSuggestions(int): This attribute specifies how many suggestion addresses will be presented at most (could be less than this number based on actual world data). By default, 10 suggestions will be displayed and the minimum value for this property is 3.
• geocode(Object): A geocode call can be chained after a user's address selection and retrieve the longitude and latitude data. In order to call the geocode() method, this object should provide the following information:
  • successCallback(Function): The success callback to use in the geocode call (as expected in the geocode's API).
  • errorCallback(Function): The error call back to use in the geocode call (as expected in the geocode's API).
  • options(Object): The options object to use in the geocode call (as expected in the geocode's API).
  Calling the geocoder here is the same as handling it in the auto-complete callback like this: geocode(selectionObject.address, successCallback, errorCallback, options);
• onSelectionBehavior(String): This property is used modify the behavior when the user selects an address. The default behavior is to replace the input text's with the user selection. These are the two available options:
  • OracleELocation.AUTOCOMPLETE_ON_SELECTION_REPLACE(String): The default behavior to replace the input text.
  • OracleELocation.AUTOCOMPLETE_ON_SELECTION_DO_NOTHING(String): Do not modify the input text when the user selects a suggestion address.
  Note: This setting is in place to give more flexibility to the users on how they handle all of the events.

Parameters:
input - The input DOM element displayed on the page
callback - is a user-specified function that is invoked when an address is selected
options - The options to affect how auto-complete is triggered, how many suggestion addresses to display, among other things, like geocode callbacks.

batchGeocode

Object batchGeocode(addressArray, <Function> callBack, <Function> errHandler, <Object> mapOptions)

This method invokes the geocoder on eLocation to obtain the longitude/latitude information for a given Array of addresses. It then invokes the user defined callback function and pass the geocoded result to the callback function. Each of the input addresses can be either a street address (a string text) or an object. The object could have longitude/latitude information (for reverse-geocoding), name and country information (for name-based search), or a structured sequence of street, city and state values for a US-only search.
• A street address is specified as a string that has the house number, street name, locality, postal code, etc. Examples: "500 Oracle Pkwy, Redwood City, CA", "San Mateo, CA".
• A longitude/latitude location is specified as an object that has a "lon" attribute that specifies the longitude value and a "lat" attribute that specifies the latitude value. Example: {"lon":-71.45937, "lat":42.70781}.
• A name location is specified as an object that has a "name" attribute that specifies a place's name and a "country" attribute that specifies the country where that place is located. Additionally, "street" and "city" are also accepted in this kind of request and will help filtering out the results, but the only mandatory attributes are "name" and "country". Examples: {"name":"eiffel tower", "country":"fr"}, {"name":"parthenon", "street":"Dionysiou Areopagitou", "city":"athens", "country":"greece"}.
• A structured location is specified as an object that has a "street", "city", and "state" attributes to clearly separate the different values we want to look up. The country will always be defaulted to "US". Examples: {"street":"1 main st", "city":"san francisco", "state":"california"}, {"street":"1 oracle dr", "city":"nashua", "state":"nh"}

The application can also control whether to draw the geocoded addresses on the map or not and how to draw the markers by providing a map options object, which can have the following attributes:

• mapview(OM.Map): This attribute specifies the Oracle Maps client instance in which the markers will be displayed. The markers will not be displayed on any map if this attribute is null or invalid.
• id(int): This is the id for the first marker, by default, 1.
• label(String): This is the label to be assigned to the markers, by default, "A".
• marker(Object): This property serves to render the marker, providing both style and color. Available styles are:
  • ELocationMarkerFactory.STYLE_SQUARE_BUBBLE
  • ELocationMarkerFactory.STYLE_POINTER_BUBBLE
  • ELocationMarkerFactory.STYLE_DIAGONAL_SQUARE
  • ELocationMarkerFactory.STYLE_BUBBLE
  • ELocationMarkerFactory.STYLE_FLAG
  • ELocationMarkerFactory.STYLE_HEXAGON
  • ELocationMarkerFactory.STYLE_PIN_1
  • ELocationMarkerFactory.STYLE_PIN_2
  • ELocationMarkerFactory.STYLE_SMALL_PIN
  • ELocationMarkerFactory.STYLE_3D_CUBE
  • ELocationMarkerFactory.STYLE_SIGN_1
  • ELocationMarkerFactory.STYLE_TRAFFIC_SIGN_1
  • ELocationMarkerFactory.STYLE_TRAFFIC_SIGN_2
  • ELocationMarkerFactory.STYLE_SIGN_2
  Available colors are:
  • ELocationMarkerFactory.COLOR_RED
  • ELocationMarkerFactory.COLOR_GREEN
  • ELocationMarkerFactory.COLOR_BLUE
  • ELocationMarkerFactory.COLOR_ORANGE
  • ELocationMarkerFactory.COLOR_PURPLE
  By default, this is the Object used to render the marker:
  mapOptions.marker = {style:ELocationMarkerFactory.STYLE_TRAFFIC_SIGN_1, color:ELocationMarkerFactory.COLOR_GREEN} ;
• markerStyle(String): This property serves to override the markers' label, style style and color. When setting this property to "letterSequence", letters instead of numbers are used for each stop-point FOI. Colors of the markers go through 5 different colors in a loop: Green-> Orange-> Purple-> Red-> Blue-> Green->... If the id was provided, the letter sequence will start at that number, e.g. id=5 means label="E"
• zoomToFit(boolean): This attribute specifies whether to zoom in and recenter the map so that the markers are fitted to the size of the map.
• infoWindowStyle(String): This property is used to select the window style to show whenever a marker created by eLocation is clicked on the map. Available styles are:
  • ELocationMarkerFactory.WINDOW_STYLE_1
  • ELocationMarkerFactory.WINDOW_STYLE_2
  • ELocationMarkerFactory.WINDOW_STYLE_3
  • ELocationMarkerFactory.WINDOW_STYLE_4
  By default, ELocationMarkerFactory.WINDOW_STYLE_4 will be used.
• getTimeZone(boolean): When set to true, this property will retrieve the timezone information for the geocoded location. By default is set to false.
The result is an array of address objects. The array will contain only one address object if only one match is found. It will contain multiple address objects if multiple matches are found. Each geocode address object has the following attributes.
• x : The x (longitude) coordinate of the result location.
• y : The y (latitude) coordinate of the result location.
• houseNumber : Address street house number
• street : Street
• settlement : City
• municipality: Municipality
• region : Region(state, province, etc.)
• postalCode: Postal code
• country: Country
• matchVector: Match vector that tells how each address field is matched. Please refer to Oracle Spatial Developer's guide for more information.
• matchCode: Match code, a number indicating which input address attributes matched the data used for geocoding. The following table lists the possible match code values.

  Match Code	Description
  1	Exact match: the city name, postal code, street base name, street type (and suffix or prefix or both, if applicable), and house or building number match the data used for geocoding.
  2	The city name, postal code, street base name, and house or building number match the data used for geocoding, but the street type, suffix, or prefix does not match.
  3	The city name, postal code, and street base name match the data used for geocoding, but the house or building number does not match.
  4	The city name and postal code match the data used for geocoding, but the street address does not match.
  10	The city name matches the data used for geocoding, but the postal code does not match.
  11	The postal code matches the data used for geocoding, but the city name does not match.

• accuracy: Result accuracy, a number indicating the accuracy level of the geocoding result. Unlike match code, the accuracy level does not indicate how well the result matches the input address. Instead it describes the level of details the result has, e.g, whether the result is a house number level address, street level address or city level address. The following table lists the possible accuracy values.

  Accuracy	Description
  -1	The result is empty.
  1	The result has house number level details.
  2	The result has street level details.
  3	The result has city level details.
  4	The result has municipality level details.
  5	The result has region level details.
  6	The result has country level details.

Parameters:
callBack - is a user specified function that is invoked when the input addresses are geocoded. It should declare two parameters, one is an address array that contains the geocoded results and the second one is the input addresses received.
errHandler - A user specified function that is invoked when error happens during geocoding. Three parameters are passed to this function when being invoked: error code, error message and the input address(es).
mapOptions - mapping options in case we want a geocoded address to be displayed on the map
addresses - A collection of either a street address (a string text) or an object. The object could have longitude/latitude information (for reverse-geocoding), name and country information (for name-based search), or a structured sequence of street, city and state values for a US-only search.

captureMap

Object captureMap(mapDiv)

Captures the map contents using the html2canvas API. This is an asynchronous call, so a Promise is returned with the URI result. The html2canvas script should have been loaded and available by the time this method is called, otherwise an error will be logged and no capture will happen.
See: https://html2canvas.hertzen.com/

Parameters:
mapDiv - The div element where the map is being rendered.

changeRouteStyle

void changeRouteStyle(<Array> routeStyles)

Updates the draw color/style for already drawn routes on the map. This function takes an array of styles as parameter, one for each desired route:
routeStyles (Array): Rendering options to re-draw routes on screen. Each element in the array holds two values:

• routeId (String): The route id to change the style (e.g. route1, route4sub2, route9...)
• render_style (Object): Details to render a route on the map. There are three supported style formats: one for predefined and two for dynamic styles. For predefined styles, only the name and datasource of the style (which resides in the database) are required. If no datasource is provided, a default value of "ELOCATION" is used. Once a datasource is provided, subsecuent calls to changeRouteStyle() or getDirections() will use the last value provided if ommited in new calls:
  • name (String): The name of the pre-defined style (e.g. L.AH3C_GB).
  • datasource (String): The datasource of the pre-defined style (e.g. "MVDEMO").
  For dynamic styles, the first variation requires an OM.style.Line object:
  • styleObj (OM.style.Line): Dynamic style object to draw the route.
  For the second dynamic styles variation, three properties are expected:
  • color (String): RGB code to identify this route in the form: "#11ff33" with value range from 00 to ff.
  • opacity (float): Color opacity, value between 0 and 1 (e.g. 0.5).
  • width (int): Route brush width in pixels (e.g. 7).

Parameters:
routeStyles - Array of styles to apply to current routes on the map

detachEventListenerFromRoute

void detachEventListenerFromRoute(routeId, eventType, eventHandler)

Detach event handlers from routes and route segments, such as:

• OM.event.MouseEvent.MOUSE_CLICK
• OM.event.MouseEvent.MOUSE_RIGHT_CLICK
• OM.event.MouseEvent.MOUSE_OVER
• OM.event.MouseEvent.MOUSE_OUT

Parameters:
routeId - The feature ID of the desired route to detach the event from
eventType - The event type to detach. Options are: OM.event.MouseEvent.MOUSE_CLICK, OM.event.MouseEvent.MOUSE_RIGHT_CLICK, OM.event.MouseEvent.MOUSE_OVER, OM.event.MouseEvent.MOUSE_OUT
eventHandler - The function previously attached to this route feature

drawMarker

void drawMarker(gcAddress, params)

Draws a marker on the map

Parameters:
gcAddress - A geocoded address (as returned by the geocode service).
params - The parameters to render the marker.

generateShareableURL

Object generateShareableURL(<Array> addresses, <Object> options)

Generates a URL to easily share and embed an Oracle map that features either a predefined route or a marker.
When the input address is a single location (string), the map will render a single marker. The options available are {String} label and {int} id. By default, the marker will display the letter "A" and it will be a green marker. The marker color is determined by the id number, going in a loop from 1=Green-> 2=Orange-> 3=Purple-> 4=Red-> 5=Blue-> 6=Green->...
When the input is a list of locations, each of them will render a marker and a route to connect the locations will be displayed. The only option is {String} color, to display the route. By default, the route will be pink. The available colors are 'blue', 'orange', 'green', 'pink' and 'purple'. Additionally, the color could be an Hex RGB string (starting with '#'), for example: '#123FFF'.

Parameters:
addresses - The location information to display the map.
options - Options for the marker or route to display.

geocode

void geocode(<Object> address, <Function> callBack, <Function> errHandler, <Object> mapOptions)

This method invokes the geocoder on eLocation to obtain the longitude/latitude information for a given street address. It then invokes the user defined callback function and pass the geocoded result to the callback function. The input address can be either a street address (a string text) or an object. The object could have longitude/latitude information (for reverse-geocoding), name and country information (for name-based search), or a structured sequence of street, city and state values for a US-only search. A new supported option is the address object returned by the auto-complete feature.
• A street address is specified as a string that has the house number, street name, locality, postal code, etc. Examples: "500 Oracle Pkwy, Redwood City, CA", "San Mateo, CA".
• A longitude/latitude location is specified as an object that has a "lon" attribute that specifies the longitude value and a "lat" attribute that specifies the latitude value. Example: {"lon":-71.45937, "lat":42.70781}.
• A name location is specified as an object that has a "name" attribute that specifies a place's name and a "country" attribute that specifies the country where that place is located. Additionally, "street" and "city" are also accepted in this kind of request and will help filtering out the results, but the only mandatory attributes are "name" and "country". Examples: {"name":"eiffel tower", "country":"fr"}, {"name":"parthenon", "street":"Dionysiou Areopagitou", "city":"athens", "country":"greece"}.
• A structured location is specified as an object that has a "street", "city", and "state" attributes to clearly separate the different values we want to look up. The country will always be defaulted to "US". Examples: {"street":"1 main st", "city":"san francisco", "state":"california"}, {"street":"1 oracle dr", "city":"nashua", "state":"nh"}
• Another structured location that is supported is the address object returned by the auto-complete feature. This kind of objects will generate a gen_form geocode request. Examples: {"houseNumber":"100","street":"Oracle Pkwy","settlement":"REDWOOD CITY","region":"CALIFORNIA","postalCode":"94065","country":"US","fullAddress":"100 ORACLE PKWY REDWOOD CITY CALIFORNIA 94065 US"}, {"houseNumber":"1","street":"Main St","settlement":"SAN FRANCISCO","region":"CALIFORNIA","postalCode":"94105","country":"US","fullAddress":"1 MAIN ST SAN FRANCISCO CALIFORNIA 94105 US"}

The application can also control whether to draw the geocoded address on the map or not and how to draw the marker by providing a map options object, which can have the following attributes:

• mapview(OM.Map): This attribute specifies the Oracle Maps client instance in which the marker is to be displayed. The marker will not be displayed on any map if this attribute is null or invalid.
• id(int): This is the id for the marker, by default, 1.
• label(String): This is the label to be assigned to the marker, by default, "A".
• marker(Object): This property serves to render the marker, providing both style and color. Available styles are:
  • ELocationMarkerFactory.STYLE_SQUARE_BUBBLE
  • ELocationMarkerFactory.STYLE_POINTER_BUBBLE
  • ELocationMarkerFactory.STYLE_DIAGONAL_SQUARE
  • ELocationMarkerFactory.STYLE_BUBBLE
  • ELocationMarkerFactory.STYLE_FLAG
  • ELocationMarkerFactory.STYLE_HEXAGON
  • ELocationMarkerFactory.STYLE_PIN_1
  • ELocationMarkerFactory.STYLE_PIN_2
  • ELocationMarkerFactory.STYLE_SMALL_PIN
  • ELocationMarkerFactory.STYLE_3D_CUBE
  • ELocationMarkerFactory.STYLE_SIGN_1
  • ELocationMarkerFactory.STYLE_TRAFFIC_SIGN_1
  • ELocationMarkerFactory.STYLE_TRAFFIC_SIGN_2
  • ELocationMarkerFactory.STYLE_SIGN_2
  Available colors are:
  • ELocationMarkerFactory.COLOR_RED
  • ELocationMarkerFactory.COLOR_GREEN
  • ELocationMarkerFactory.COLOR_BLUE
  • ELocationMarkerFactory.COLOR_ORANGE
  • ELocationMarkerFactory.COLOR_PURPLE
  By default, this is the Object used to render the marker:
  mapOptions.marker = {style:ELocationMarkerFactory.STYLE_TRAFFIC_SIGN_1, color:ELocationMarkerFactory.COLOR_GREEN} ;
• infoWindowStyle(String): This property is used to select the window style to show whenever a marker created by eLocation is clicked on the map. Available styles are:
  • ELocationMarkerFactory.WINDOW_STYLE_1
  • ELocationMarkerFactory.WINDOW_STYLE_2
  • ELocationMarkerFactory.WINDOW_STYLE_3
  • ELocationMarkerFactory.WINDOW_STYLE_4
  By default, ELocationMarkerFactory.WINDOW_STYLE_4 will be used.
• getTimeZone(boolean): When set to true, this property will retrieve the timezone information for the geocoded location. By default is set to false.
The result is an array of address objects. The array will contain only one address object if only one match is found. It will contain multiple address objects if multiple matches are found. Each geocode address object has the following attributes.
• x : The x (longitude) coordinate of the result location.
• y : The y (latitude) coordinate of the result location.
• houseNumber : Address street house number
• street : Street
• settlement : City
• municipality: Municipality
• region : Region(state, province, etc.)
• postalCode: Postal code
• country: Country
• matchVector: Match vector that tells how each address field is matched. Please refer to Oracle Spatial Developer's guide for more information.
• matchCode: Match code, a number indicating which input address attributes matched the data used for geocoding. The following table lists the possible match code values.

  Match Code	Description
  1	Exact match: the city name, postal code, street base name, street type (and suffix or prefix or both, if applicable), and house or building number match the data used for geocoding.
  2	The city name, postal code, street base name, and house or building number match the data used for geocoding, but the street type, suffix, or prefix does not match.
  3	The city name, postal code, and street base name match the data used for geocoding, but the house or building number does not match.
  4	The city name and postal code match the data used for geocoding, but the street address does not match.
  10	The city name matches the data used for geocoding, but the postal code does not match.
  11	The postal code matches the data used for geocoding, but the city name does not match.

• accuracy: Result accuracy, a number indicating the accuracy level of the geocoding result. Unlike match code, the accuracy level does not indicate how well the result matches the input address. Instead it describes the level of details the result has, e.g, whether the result is a house number level address, street level address or city level address. The following table lists the possible accuracy values.

  Accuracy	Description
  -1	The result is empty.
  1	The result has house number level details.
  2	The result has street level details.
  3	The result has city level details.
  4	The result has municipality level details.
  5	The result has region level details.
  6	The result has country level details.

Parameters:
address - the street address or the longitude/latitude location to be located.
callBack - is a user specified function that is invoked when the input address is geocoded. It should declare two parameters, one is an address object that contains the geocoded result and the second one is the input address received.
errHandler - A user specified function that is invoked when error happens during geocoding. Three parameters are passed to this function when being invoked: error code, error message and the input address(es).
mapOptions - mapping options in case we want a geocoded address to be displayed on the map

geocodeForUS

Object geocodeForUS(address, callBack, errHandler, mapOptions, geocodeFunc)

getDirections

void getDirections(<Array> routes, <Function> callBack, <Function> errHandler, <Object> routeOptions, <Object> mapOptions)

This method invokes the eLocation routing engine to caculate route and/or driving directions between destinations. It then invokes the user defined callBack function and passes the routing result to the callBack function. When required, it can also show the route on a map displayed by the Oracle Maps client if such map already exists on the same web page where this method is invoked.

The input destinations are specified as an array of routes. Each route is in fact another array that holds input addresses. Each input address can be either a street address or a longitude/latitude location as explained in geocode().
For backwards compatibility purposes, input addresses can also be represented as a single array of addresses, each of them being a street address or a longitude/latitude location. When this is the case, a few aspects of the route drawing behave as they did in previous versions of these APIs:

• Actual route coordinates are returned as part of the route calculation (opposed to current behavior which draws routes as a PNG images). Each route is an MVFOI object representing a line that is built up with a collection of longitude/latitude points.
• All calls to getDirections() cause the previous information on the map to be removed prior to calculating the new route request. This is due to the route and stop-point naming convention, since in previous APIs only one route was drawn at a time.

Once the routing calculation is finished, the callback function is invoked and two parameters are passed to it. The first parameter is the geocoded destinations. The geocoded result is the same as that returned by geocode(). The geocode can be skipped if two things happen: 1) the input address is an object that specify a longitude and latitude (e.g. the address 'obj' has obj.lon and obj.lat attributes) and 2) 'useLonLatIfAvailable' is set to 'true' as part of the attributes in the route option object.
The second parameter is the routing result. It's an array of routes. Each array element is an object that specifies the routing result for that particular route. When requested, this second parameter could also include an "htmlDirections" attribute with the route directions as an HTML string. The routing result object has the following attributes:

• id : The serial ID of the route.
• stepCnt : The number of driving direction steps.
• dist: Total distance of the route
• distUnit: Distance unit
• time: Total estimated driving time.
• timeUnit: Time unit.
• routeMBR : The bounding box coordinates for this route (upper left and bottom right coordinates).
• subroutes: The subroute array, each of them with specific route information:
  • id : The serial ID of the subroute.
  • stepCnt : The number of driving direction steps.
  • dist: Total distance for this route segment
  • distUnit: Distance unit
  • time: Total estimated driving time for this route segment.
  • timeUnit: Time unit.
  • routeMBR : The bounding box coordinates for this subroute (upper left and bottom right coordinates).
  • steps: The driving direction steps. It's an array of step objects, each of which specifies one driving direction sequence and has the following attributes:
    • seq: The sequence number.
    • inst: The driving instruction.
    • dist: The distance of this sequence.
    • time: The estimated time of this sequence.
• steps: The driving direction steps. If route is a two-destination route (meaning no stop-points were involved) then this array is provided, each object specifies one driving direction sequence and has the following attributes:
  • seq: The sequence number.
  • inst: The driving instruction.
  • dist: The distance of this sequcence.
  • time: The estimated time of this sequcence.

The application must provide an error handling function when invoking this method. It will be called when an error happens during the routing calculation. Most errors are caused by invalid destination addresses, which the application might want to deal with. For example, the application might ask the user to correct the addresses before recalculating the driving directions. When being invoked, the following five parameters are passed to the error handling function.

• The error code.
• The error message.
• The address(es) that has(have) caused the error.
  • If the error code is OracleELocation.ERROR_GEOCODE_FAILED, the value of this parameter is the input address that has caused the error.
  • If the error code is OracleELocation.ERROR_ROUTE_ADDR_INVALID, the value of this parameter is an array of geocoded destination addresses. Each array element specifies the geocoded result of one destination route, which is the same as the result passed to the geocode() callback function.
  • If the error code is OracleELocation.ERROR_ROUTE_NOT_FOUND or OracleELocation.ERROR_ROUTE_FAILED, the value of this parameter is an array of geocoded addresses, the start, end and stop-point addresses, for all routes requested.
• The route number
• The address index within the route array
• Array of error messages (for batch requests), where each element in the array has 3 attributes: id (based on their position index in the input route array), errorMessage (reason why the route failed to be processed) and invalidAddresses (array with the index of all the invalid input addresses that failed to be geocoded; this attribute may not be present if the route failed for a reason other than error at the geocode level).

The application can customize how the driving directions are calculated and how the results are returned by providing a route option object, which can have the following attributes:

• routePref(String): The constraints to pick the best possible route, by default SHORTEST is used. Possible values are:
  • FASTEST: The route with the lowest estimated driving time
  • SHORTEST: The route with the shortest driving distance
  • TRAFFIC: The route with less traffic that ultimately will make it the fastest one
  When TRAFFIC is selected as the route preference, other attributes can be specified as well:
  • routeDate(String): The date when the route is starting. If this value is not provided, the current date will be used. See "routeDateFormat" for the expected date pattern for this attribute.
  • routeTime(String): The time when the route is starting. If this value is not provided, the current time will be used. See "routeTimeFormat" for the expected time pattern for this attribute.
  • routeDateFormat(String): The "routeDate" value is expected to comply with this date format (pattern). If this attribute is not provided, the default date format is: "dd-MMM-yyyy".
  • routeTimeFormat(String): The "routeTime" value is expected to comply with this time format (pattern). If this attribute is not provided, the default time format is: "HH:mm".
  • outputTimeFormat(String): The start and end times in the router response are formatted according to this parameter. The default pattern is: "dd-MMM-yyyy HH:mm z".
• roadPref(String): Whether you want the route to use highways (HIGHWAY, the default) or local roads (LOCAL) when a choice is available.
• avoidFerry(boolean): Whether to avoid using ferries while plotting the route (true) or not (false, the default).
• directions(boolean): Whether to return turn-by-turn driving directions. Default is true.
• distUnit(String): The unit of measure for distance values that are returned: KM for kilometer, MILE (the default) for mile, or METER for meter.
• timeUnit(String): The unit for time values that are returned: HOUR for hour, MINUTE (the default) for minute, or SECOND for second.
• langPref (String): The language preference. By default English is used. Valid options are:
  • English
  • Spanish
  • French
  • German
  • Italian
• addrIsValid(Function): By default, this method uses its own address validation module to check whether the input addresses are valid. If any of them is not valid, it stops route calculation and invokes the application provided error handler function so that the application can deal with the invalid address(es). You can customize how input address validation is performed by providing your own address validation function with this attribute. The address validation function takes a geocoded address object as the only input. It checks the geocoded address, returns true if the address is valid and returns false if the address is invalid.
• ignoreGeocodeErrorsForBatchRequests(boolean): Whether to bypass geocode errors on batch route requests and continue processing all the routes requested or not. By default this property is set to false, returning to the client when errors are present while geocoding the input addresses.
• vehicleType(String): TRUCK for a route where special constraints need to be taken in account while calculating the driving directions, such as weight, length, height, etc. AUTO (default) for a route where a regular car is the driven vehicle. If TRUCK is selected, then the following parameters could also be specified for the route calculation:
  • truckType(String): What kind of truck is being driven. Valid options are: DELIVERY, PUBLIC, RESIDENT, TRAILER. There is no default value for this option.
  • lengthUnit(String): The unit to measure length. Valid options are US (default) for feet or METRIC for meters.
  • weightUnit(String): The unit to measure weight. Valid options are US (default) for tons or METRIC for metric tons.
  • truckHeight(float): The truck's height.
  • truckLength(float): The truck's length.
  • truckWidth(float): The truck's width.
  • truckWeight(float): The truck's weight.
  • truckAxleWeight(float): The truck's weight per axle.
• useLonLatIfAvailable(boolean): When set to 'true' geocoding is skipped for an address if it is an object and it contains longitude and latitude information. A geocode will happen if the address is a string or if that address does not contain both 'lon' and 'lat' attributes. By default, all addresses are geocoded prior to calculating the directions in order to obtain the coordinates where each address is physically located.

The application can also control whether to draw the route on the map and how to draw the route by providing a map option object, which can have the following attributes:

• mapview(OM.Map): This attribute specifies the Oracle Maps client instance in which the route is to be displayed. The route will not be displayed on any map if this attribute is null or invalid.
• resultPanel(DOM node): This attribute specifies where the driving directions are displayed on the application web page. It should be a HTML DOM node that has been allocated on the application page. If this attribute is not provided, then the routing directions will not be rendered. You can customize the look of the driving direction result by applying the following custom CSS styles.
  • table.eloc_direction_table: The overall style of the HTML table that shows the step by step driving directions.
  • th.eloc_direction_header: The style of the direction header.
  • td.eloc_direction_instruction: The style of the direction instruction entries in the direction table.
  • td.eloc_direction_stop: The style of the destination entries in the direction table.
  • div.eloc_direction_summary: The style of direction summary at the top.
• htmlDirections(boolean): When set to true the route directions are calculated as an HTML string and attached to the route response as [htmlDirections].
• zoomToFit(boolean): This attribute specifies whether to zoom in and recenter the map so that the route is centered and fitted to the size of the map.
• disableLoadingIcon(boolean): This parameter indicates whether to disable the map loading icon while processing the route requests or to display it (by default the loading icon is displayed)
• routeNamingIDs (Array): This is a collection of route IDs to be assigned to routes on the map. Each element in this object is a list of IDs. Each list of IDs is expected to contain just one route ID for A to B routes (single-segment-route). For multi-stop routes (A to B to C... to n), the number of required IDs is n, (where n is the number of stop-points within the route), starting with a route ID for the whole route (A through n) and followed by n-1 route segment IDs. When this property is not set, or when the number of IDs provided does not match the expected number of IDs, then default route IDs are generated, for example:
  • route1
  • route3sub2
  • route8sub4
  • route2
• routeStyles (Array): Rendering options to display routes on screen. Each element in the array is a style or array of styles (for multi-stop routes). A batch route request requires a Route Style for each route/route segment. Default values are used if the number of styles provided is less than the total routes requested or the style provided is null. If a single style is provided for a multi-stop route request, all segments within that route will share the same style. Each style have the following information:
  • render_style (Object): Details to render a route on the map. There are three supported style formats: one for predefined and two for dynamic styles. For predefined styles, only the name and datasource of the style (which resides in the database) are required. If no datasource is provided, a default value of "ELOCATION" is used. Once a datasource is provided, subsecuent calls to getDirections() or changeRouteStyle() will use the last value provided if ommited in new calls:
    • name (String): The name of the pre-defined style (e.g. "L.AH3C_GB").
    • datasource (String): The datasource of the pre-defined style (e.g. "MVDEMO").
    For dynamic styles, our first variation requires a name and an OM.style.Line object:
    • name (String): The name of the style that matches the style object below.
    • styleObj (OM.style.Line): Dynamic style object to draw the route.
    For our second dynamic styles variation, three properties are expected:
    • color (String): RGB code to identify this route in the form: "#112233" with value range from 00 to ff.
    • opacity (float): Color opacity, value between 0 and 1 (e.g. 0.5).
    • width (int): Route brush width in pixels (e.g. 7).
  • typeName (String): The route type. By default "Customer".
  • label (String): The label we want to assign to a given route. When clicking on a route we can display an information window with this route label we provided. Default is "{time}. {distance}.", which are substituted by their actual time and distance value (e.g. "5 min. 4.9 mi.")
  • label_width (int): The width in pixels of the information window. Default is 115.
  • label_height (int): The height in pixels of the information window. Default is 45.
• drawMarkers(boolean): This attribute specifies whether the route destinations are to be drawn on the map along with the route geometries. The markers are drawn by default.
• startMarker(Object): This attribute specifies the style and color of the marker that represents the route start point. You can choose any combination of builtin style and color from ELocationMarkerFactory. It's specified as a object that has two attributes, "style" and "color". The default startMarker value is {style: ELocationMarkerFactory.STYLE_TRAFFIC_SIGN_1, color:ELocationMarkerFactory.COLOR_GREEN}.
• endMarker(Object): This attribute specifies the style and color of the marker that represents the route end point. You can choose any combination of builtin style and color from ELocationMarkerFactory. It's specified as a object that has two attributes, "style" and "color". The default startMarker value is {style: ELocationMarkerFactory.STYLE_TRAFFIC_SIGN_1, color:ELocationMarkerFactory.COLOR_RED}.
• stopMarker(Object): This attribute specifies the style and color of the marker that represents any route destination other than the start and end points. You can choose any combination of builtin style and color from ELocationMarkerFactory. It's specified as a object that has two attributes, "style" and "color". The default startMarker value is {style: ELocationMarkerFactory.STYLE_TRAFFIC_SIGN_1, color:ELocationMarkerFactory.COLOR_BLUE}.
• getMarkerInfoStr(Function): By default, an info window showing the address is displayed when the marker that represents a route destination is clicked on the map. You can customize the info window content by providing a custom function with this attribute. This function takes two parameters, the address object and the index number of the clicked destination in the input destination array, starting from 0. It returns the info window content as a HTML content string.
• removePreviousRoutes(boolean): Whether to remove previous routes displayed on the map or not. By default routes are preserved until user calls explicitly removeRoutesFromMap() or sets this property to true on future routing calls.
• markerStyle(String): This property serves to override start, stop and end markers (both style and color). When setting this property to "letterSequence", letters instead of numbers are used for each stop-point FOI. Colors of the markers go through 5 different colors in a loop: Green-> Orange-> Purple-> Red-> Blue-> Green->...
• infoWindowStyle(String): This property is used to select the window style to show whenever a marker created by eLocation is clicked on the map. Available styles are:
  • ELocationMarkerFactory.WINDOW_STYLE_1
  • ELocationMarkerFactory.WINDOW_STYLE_2
  • ELocationMarkerFactory.WINDOW_STYLE_3
  • ELocationMarkerFactory.WINDOW_STYLE_4
  By default, ELocationMarkerFactory.WINDOW_STYLE_4 will be used.

Alternatively, the application can have total control over where and how the route is displayed by doing it in the callback function that is called after the route is calculated. In this case, you should set the map option object to null.

Parameters:
routes - an array of destination addresses.
callBack - A user specified function that is invoked when the routing results are returned.
errHandler - A user specified function that is invoked when error happens during route calculation.
routeOptions - An object that specifies how the routes should be calculated.
mapOptions - An object that specifies how the routes should be displayed on the map.

removeRoutesFromMap

void removeRoutesFromMap(<Array> routeArray)

Removes routes drawn on the map. By default, routes displayed on the map remain there until an explicit call to this method is performed.

Parameters:
routeArray - Array with all the route IDs to be removed. If route array is empty or null then all routes on the map are removed.

saveMapAsPNG

void saveMapAsPNG(mapDiv, filename)

Captures the map contents using the html2canvas API and triggers a "Save as..." dialog with the generated image. This is an asynchronous call, so once the image is ready, the save dialog will pop up. The html2canvas script should have been loaded and available by the time this method is called, otherwise an error will be logged and no capture will happen.
See: https://html2canvas.hertzen.com/

Parameters:
mapDiv - The div element where the map is being rendered.
filename - The file name for the image generated. 'eLocationMap.png' is the default value.

setInfoTip

void setInfoTip(featureId, <String> infoTipTxt)

Sets specific infoTip on drawn routes

Parameters:
infoTipTxt - The text to display as infoTip on mouse over
foiId - The id for the route feature to attach the infoTip