Plugin - Location Services

What you will learn in this chapter
Location Services plugin features
Advanced UI elements
Actions specific to Location Services
Download and Import Location Services Plugin

Location Services plugin features

Location Services plugin enables your app to

  • Search Places by name, keyword, type (like a bank, atm, school etc) and distance (up to 50 kms or 31 miles) near a vicinity of a GeoPoint.
  • Find a geo-location for a place by searching it by name or address.
  • Get directions between two addresses or GeoPoints
  • Get distances between two address or GeoPoints

The results can be listed as text or the places can be shown on the map.

Each market place (Apple, Google, Amazon) has its own map services. This plug-in hides the underlying implementation nuances between the market places, giving you a simple way to use location services into your app. The plugin provides common actions

The maps are displayed using a new view called MAP_VIEW.

Advanced UI elements

The Location Services Plugin defines several new User Interface elements. They are as follows.

Name Description Usage
com.appemble.google.locservices.MAPS To create a MAPVIEW on a screen, this UI element has to be defined as screen_type screen_type=”com.appemble.google.locservices.MAPS”
com.appemble.google.locservices.MAPVIEW MAPVIEW is a control to display a map. Overlays can be added to the MAPVIEW to pinpoint places. control type=”com.appemble.google.locservices.MAPVIEW”
com.appemble.google.locservices.SEARCHABLE_MAP A Group control that has an EDIT box and a MAPVIEW. User can search for places by entering their name, address in the EDIT box. control type=”com.appemble.google.locservices.SEARCHABLE_MAP”

Actions specific to Location Services

Note

Click on each of the Actions described below to lean about their Parameters

action_name= Description
com.appemble.google.locservices.GEOCODE_PLACE This action is used to find latitude and longitude of a place by giving its full address or part of the address. If a partial address is given it may match multiple places. See Google Geocoding API for more information. com.appemble.google.locservices.ON_GEOCODE_RESULTS event is raised when the geocode results are available after executing the action GEOCODE_PLACE. The results event are placed in the table _geocode_place and are accessible using geocode_place_id.
com.appemble.google.locservices.REVERSE_GEOCODE_PLACE This action is used to find closest readable address at a given latitude and longitude of a place. See Google Geocoding API for more information.
com.appemble.google.locservices.SEARCH_PLACES

This action is used to search places in a geographical area (specified by its latitude and longitude) with radius upto 50 kms or 31 miles by their name or by type(s) like a bank or a school. See Google Places Search API for more information.

com.appemble.google.locservices.ON_SEARCH_PLACE_RESULTS event is raised when the search results are available after executing the action SEARCH_PLACES. The results are placed in the table _places and are accessible using search_places_id.

com.appemble.google.locservices.GET_PLACE_DETAILS
The details of the place including its complete address, phone numbers, email, website, reviews, location (LatLng) and events can be obtained using this action. See Google Place Details API for more information.
com.appemble.google.locservices.ON_GET_PLACE_DETAILS_RESULT event is raised when the place details are available after
executing the action GET_PLACE_DETAILS. The results are placed in the table _place_details and are accessible using place_details_reference_id.
com.appemble.google.locservices.PLACE_MAP_OVERLAYS This action is used to pin point places on the map using their location (LatLng).
com.appemble.google.locservices.GET_DIRECTIONS

Get directions between two addresses. The directions can be obtained for driving, public transit, walking, bicycling and can avoid tolls and highways. If the transit mode is selected, then arrival or departure time is a MUST.

com.appemble.google.locservices.ON_GET_DIRECTIONS_RESULT event is raised when the directions are available after executing the action GET_DIRECTIONS. The results are placed in the table _route, _leg, _step tables and are accessible using directions_query_id.

com.appemble.google.locservices.DRAW_ROUTE Draws a route on a map between two locations. It requires that GET_DIRECTIONS action has already been called.
com.appemble.google.locservices.GET_DISTANCES

Gets distances between two places identified by their address.

com.appemble.google.locservices.ON_GET_DISTANCES_RESULTS event is raised when the distances are available between several points after executing the action GET_DISTANCES. The results are placed in the table _distance_matrix and are accessible by querying the table.

Parameters for each Action

com.appemble.google.locservices.GEOCODE_PLACE

The GEOCODE_PLACE action results in one or more places and the results are saved into the database table geocode_places. The GEOCODE_PLACE action request itself is saved into the table _geocode_query. In case the same action is called up again, the results can be fetched from the local database instead of calling the remote servers. The cache expiry time is specified using the setting google_geocodes_query_stale_time The results can be displayed in the form of a text or on the MAP.


Parameter Description Required
address Address can be full or partial. address or components
components

A filter to narrow the results of geocoding within a certain geographical area. A filter consists of one or more of the following fields.

  • route or street
  • locality or city
  • postal_code
  • administrative_area_level_3
  • administrative_area_level_2 or county
  • administrative_area_level_1 or state
  • country

For description of the above fields, See Address Component Types .

components or address. This can be used in conjunction with the address to narrow down the result set.
sensor boolean. Indicates whether or not the geocoding request comes from a device with a location sensor. Yes
bounds_ne_latitude bounds_ne_longitude bounds_sw_latitude bounds_sw_longitude You can influence the query results by giving a bounding box to search for a place (For more information see Viewport Biasing). No
language The language in which to return results. See the list of supported domain languages. No
region You can influence the geocode query results by giving the region code, specified as a ccTLD (“top-level domain”) two-character value. (For more information see Region Biasing) No
key Key can be obtained from TODO Yes

Sample Code

The sample code below is from geocode_place.xml present in the tutorial avm-google-loc-services-tutorial. The action GEOCODE_PLACES is called when user taps the pushbutton do_search. Upon return the list control search_results is REFRESHED to display the latitude / longitude of each place resulted from the GEOCODE_PLACES action.

<control name="do_search" appearance_name="blue_button" type="PUSHBUTTON"
    x="74" y="2" width="25" height="16" word_wrap="true" default_value="Search">
    <action event_list="TAP" action_name="com.appemble.google.locservices.GEOCODE_PLACE"
        input_parameter_list="address, route, city, state, postal_code, country">
        <action event_list="TAP" action_name="REFRESH" target="search_results" remote_data_also="false"/>
    </action>
</control>

com.appemble.google.locservices.REVERSE_GEOCODE_PLACE

The reverse geocode place takes a geolocation and searches for the closest human related address. The reverse geocoder matches political entities (countries, provinces, cities and neighborhoods), street addresses, and postal codes. See Reverse Geocoding for more information. The action results in zero, one or more places and the results are saved into the database table geocode_places. The action query itself is saved into the table _geocode_query. In case the same search is done again, the results can be fetched from the local database instead of calling the remote servers. The cache expiry time is specified using the setting google_geocodes_query_stale_time


Parameter Description Required
latitude Specifies the north-south position of a point on the Earth’s surface. Yes
longitude Specifies the east-west position of a point on the Earth’s surface Yes
key Key can be obtained from TODO Yes

com.appemble.google.locservices.SEARCH_PLACES

The actions results can be one or more places saved into the database table _places. The action query itself is saved into the table _place_query. While calling this action next time, in case the same search is done again, the results can be fetched from the local database instead of calling the remote servers. The cache expiry time is specified using the setting google_places_query_stale_time. The search results can be displayed in the form of a text or on the MAP.


Parameter Description Required

latitude

longitude

Specifies the north-south position of a point on the Earth’s surface.

Specifies the east-west position of a point on the Earth’s surface

LatLng or geocode_query_id or _places_id or search_token
geocode_query_id An id from the previous geocode query. If there are multiple locations then a single choice dialog will be displayed for the user to select one single location using which the nearby places will be searched. LatLng or geocode_query_id or _places_id or search_token
_places_id An id of the previously searched place LatLng or geocode_query_id or _places_id or search_token
search_token Returns the next 20 results from a previously run search. Setting a pagetoken parameter will execute a search with the same parameters used previously — all parameters other than pagetoken will be ignored. LatLng or geocode_query_id or _places_id or search_token
sensor boolean. Indicates whether or not the geocoding request comes from a device with a location sensor. Yes
keyword A term to be matched against all content that Google has indexed for this Place, including but not limited to name, type, and address, as well as customer reviews and other third-party content. No
language The language in which to return results. See the list of languages supported. No
name A term to be matched against the names of Places. Results will be restricted to those containing the passed name value.  
open_now Returns only those Places that are open for business at the time the query is sent. Places that do not specify opening hours in the Google Places database will not be returned if you include this parameter in your query. No
rankby
  • prominence (default). This option sorts results based on their importance. Ranking will favor prominent places within the specified area. Prominence can be affected by a Place’s ranking in Google’s index, the number of check-ins from your application, global popularity, and other factors.
  • distance. This option sorts results in ascending order by their distance from the specified location. Ranking results by distance will set a fixed search radius of 50km. One or more of keyword, name, or types is required.
No
types Restricts the results to Places matching at least one of the specified types. Types should be separated with a pipe symbol (type1|type2|etc). See the list of supported types. No
key Key can be obtained from TODO Yes

Sample Code

The sample code below is from search_results.xml present in the tutorial avm-google-loc-services-tutorial. The action SEARCH_PLACES is called when user taps the pushbutton do_search. Upon return the list control search_results is REFRESHED to display the search results.

<control name="do_search" appearance_name="black" type="PUSHBUTTON"
    x="70" y="20" width="28" height="7" word_wrap="true" default_value="Search">
    <action event_list="TAP" action_name="com.appemble.google.locservices.SEARCH_PLACES"
        input_parameter_list="latitude, longitude, keyword, name, types, radius">
        <action event_list="TAP" action_name="REFRESH" target="search_results" remote_data_also="false"/>
    </action>
</control>

The sample code below is from search_results.xml present in the tutorial avm-google-loc-services-tutorial. The action SEARCH_PLACES is called when user taps the pushbutton do_search. Upon return a new screen called show_places_in_map is created.

<control name="show_places_in_map" appearance_name="black" type="PUSHBUTTON"
    x="70" y="30" width="28" height="7" word_wrap="true" default_value="Show on Map">
    <action event_list="TAP" action_name="NEXT_SCREEN" target="show_places_in_map"
        input_parameter_list="latitude, longitude, radius, search_places_id">
    </action>
</control>

The screen show_places_in_map has the map controls and it displays the search results using the action PLACE_MAP_OVERLAYS. The action takes search_places_id to fetch the search results.

<action action_name="com.appemble.google.locservices.PLACE_MAP_OVERLAYS" event_list="ON_CREATE_SCREEN"
    target="map" input_parameter_list="search_places_id"/>

com.appemble.google.locservices.GET_PLACE_DETAILS

The action results return the place details saved into the database table _place_details. While calling this action next time, in case the same search is done again, the results can be fetched from the local database instead of calling the remote servers. The cache expiry time is specified using the setting google_place_details_query_stale_time

The place details can be fetched from the Google API using the sample code below. The reference for the place was obtained as a result of the action SEARCH_PLACES.


Parameter Description Required
reference Specifies the place reference returned from action SEARCH_RESULTS. Yes
sensor boolean. Indicates whether or not the geocoding request comes from a device with a location sensor. Yes
language The language in which to return results. See the list of languages supported. No
key Key can be obtained from TODO  

Sample Code

See file search_places.xml in the tutorial avm-google-loc-services-tutorial for complete code.

<action action_name="com.appemble.google.locservices.GET_PLACE_DETAILS"
    input_parameter_list="reference" event_list="TAP">
    <action action_name="NEXT_SCREEN" target="place_details" event_list="TAP"
    input_parameter_list="reference"/>
</action>

The results of the GET_PLACE_DETAILS can be displayed in text format. The code below is from get_place_details.xml to display results.

<screen
    name="place_details" screen_type="SCREEN" allowed_layouts="BOTH"
    background="#DDDDDD" allow_reorientation="true"
    width="100" height="100" on_resume_update="true" initial_focus="lat_label"
    local_data_source="select a.name, a.icon, b.address, b.phone, b.website,
        b.google_url, b.rating from _places a, _place_details b
        where a.reference='&lt;reference&gt;' and b._id='&lt;reference&gt;'">
    <!-- Starting screen controls -->
    <controls>
        <control name="icon" appearance_name="black_with_radius" x="2" y="2" width="50dp" height="50dp"
            type="IMAGE" data_type="VARCHAR" field_name="icon"/>

        <control appearance_name="black_with_radius"
            x="2" y="15" width="20" height="5" type="TEXT" default_value="Name: "/>
        <control appearance_name="black_with_radius"
            x="24" y="15" width="85" height="5" type="TEXT" field_name="name"/>

        <control appearance_name="black_with_radius"
            x="2" y="22" width="20" height="5" type="TEXT" default_value="Address: "/>
        <control appearance_name="black_with_radius"
            x="24" y="22" width="85" height="5" type="TEXT" field_name="address"/>

        <control appearance_name="black_with_radius"
            x="2" y="29" width="20" height="5" type="TEXT" default_value="Phone: "/>
        <control appearance_name="black_with_radius"
            x="24" y="29" width="85" height="5" type="TEXT" field_name="phone"/>

        <control appearance_name="black_with_radius"
            x="2" y="36" width="20" height="5" type="TEXT" default_value="Website: "/>
        <control appearance_name="black_with_radius"
            x="24" y="36" width="85" height="5" type="TEXT" field_name="website"/>

        <control appearance_name="black_with_radius"
            x="2" y="43" width="20" height="5" type="TEXT" default_value="Google Url: "/>
        <control appearance_name="black_with_radius"
            x="24" y="43" width="85" height="5" type="TEXT" field_name="google_url"/>

        <control appearance_name="black_with_radius"
            x="2" y="50" width="20" height="5" type="TEXT" default_value="Rating: "/>
        <control appearance_name="black_with_radius"
            x="24" y="50" width="70" height="5" type="TEXT" field_name="rating"/>

        <control appearance_name="black_with_radius"
            x="99" y="99" width="1" height="1" type="TEXT" default_value=""/>
        </controls>
    <!-- Ending screen controls -->

</screen>

com.appemble.google.locservices.PLACE_MAP_OVERLAYS

The action PLACE_MAP_OVERLAYS is called for the control MAP_VIEW to place overlays or markers to highlight the places on the map. The action takes a list of places that can be fetched by the action SEARCH_PLACES. PLACE_MAP_OVERLAYS can either take the search_places_id which is a collection of places or an individual place identified by place_reference.


Parameter Description Required
search_places_id Result Id from the action SEARCH_PLACES search_places_id or _places_reference
_places_reference Place reference id. The place reference id is obtained from the action SEARCH_PLACES, consists of one or more of the following fields. search_places_id or _places_reference

Sample Code

In the sample code below, the action PLACE_MAP_OVERLAYS is called when the screen is created. It fetches the latitude and longitude of the place using the parameter place_reference which was passed from the user selection in the previous screen.

<screen
    name="show_place_in_map" screen_type="com.appemble.google.locservices.MAPS" allowed_layouts="BOTH"
    allow_reorientation="true" width="100" height="100" on_resume_update="true">
    <action action_name="com.appemble.google.locservices.PLACE_MAP_OVERLAYS" event_list="ON_CREATE_SCREEN"
        target="map" input_parameter_list="place_reference"/>
    <!-- Starting screen controls -->
    <controls>
        <control name="map" appearance_name="black" x="2" y="0" width="98" height="100"
            type="com.appemble.google.locservices.MAPVIEW" field_name="map" data_type="CURSOR"
            local_data_source="select latitude, longitude, radius from _place_query where _id='&lt;search_places_id&gt;'"/>
    </controls>
    <!-- Ending screen controls -->
</screen>

com.appemble.google.locservices.GET_DIRECTIONS

The action results in driving directions from the origin to the destination. The results are saved in following tables: _route, _leg, _step. If there are any warnings, they are saved in the _warning table. The action itself is saved into the table _directions_query. In case the same direction is to be calculated again, the results can be fetched from the local database instead of calling the remote servers. The cache expiry time is specified using the setting google_directions_query_stale_time

The action results can be displayed in the form of a text or on the MAP.


Parameter Description Required

origin_address

and

destination_address

Address can be full or partial.

Address can be full or partial.

address or GeoPoint of origin and destination.

origin lat / lang

and

destination lat / lang

The GeoPoint of the origin from where you wish to calculate the directions.

The GeoPoint of the destination to where you wish to calculate the directions.

address or GeoPoint of origin and destination
sensor boolean. Indicates whether or not the geocoding request comes from a device with a location sensor. Yes
mode
Specifies the mode of transport to use when calculating directions. Valid values are:
  • driving (default) indicates standard driving directions using the road network.
  • walking requests walking directions via pedestrian paths & sidewalks (where available).
  • bicycling requests bicycling directions via bicycle paths & preferred streets (currently only available in the US and some Canadian cities).
No
waypoints Specifies an array of waypoints. Waypoints alter a route by routing it through the specified location(s). A waypoint is specified as either a latitude/longitude coordinate or as an address which will be geocoded. Waypoints are only supported for driving, walking and bicycling directions. (For more information on waypoints, see Using Waypoints in Routes.) No
alternatives If set to true, specifies that the Directions service may provide more than one route alternative in the response. Note that providing route alternatives may increase the response time from the server. No
avoid Introduces restrictions to the route. Valid values are specified list of restrictions Only one restriction can be specified. No
units Specifies the unit system to use when expressing distance as text. See the List of unit systems for more information. No
language The language in which to return results. See the list of supported domain languages. No
region You can influence the geocode query results by giving the region code, specified as a ccTLD (“top-level domain”) two-character value. (For more information see Region Biasing) No
departure_time Specifies the desired time of departure as seconds since midnight, January 1, 1970 UTC . The departure time may be specified by Maps for Business customers for to specify the departure_time to receive trip duration considering current traffic conditions. The departure_time must be set to within a few minutes of the current time. No
arrival_time arrival_time specifies the desired time of arrival for transit directions as seconds since midnight, January 1, 1970 UTC. One of departure_time or arrival_time must be specified when requesting transit directions. No
key Key can be obtained from TODO Yes

Displaying directions in Text

The sample code below is taken from the file get_directions_in_text.xml present in the tutorial avm-google-loc-services-tutorial. The action GET_DIRECTIONS is called when user taps the pushbutton get_directions.

<control name="get_directions" appearance_name="black" type="PUSHBUTTON"
    x="75" y="10" width="20" height="8" word_wrap="true" default_value="Search">
    <action event_list="TAP" action_name="com.appemble.google.locservices.GET_DIRECTIONS"
        input_parameter_list="origin, destination"
        target_parameter_list="origin_address, destination_address"/>
</control>

Upon return the FUNCTION REFRESH_DIRECTIONS_LIST is called. The function fetches the results from the table _step and displays it in the list control direction_list by calling the action REFRESH.

<action event_list="com.appemble.google.locservices.ON_GET_DIRECTIONS_RESULTS"
    action_name="FUNCTION" target="REFRESH_DIRECTIONS_LIST"
            input_parameter_list="directions_query_id"/>

Displaying the direction on a MAP

The action results can be displayed on the MAP using the action DRAW_ROUTE. The action takes directions_query_id to fetch the data for drawing the route. It takes a MAP_VIEW (as its target) to draw the directions. The following code taken from the file get_directions_on_map.xml located in the project avm-google-loc-services-tutorial\app-def-loc-services shows how to draw the route.

<action event_list="com.appemble.google.locservices.ON_GET_DIRECTIONS_RESULTS"
            action_name="com.appemble.google.locservices.DRAW_ROUTE" target="map"
            input_parameter_list="directions_query_id"/>

com.appemble.google.locservices.DRAW_ROUTE

The action is called after the GET_DIRECTIONS action fetches the directions to draw the route on the MAP_VIEW. It needs directions_query_id to fetch the data for the route and the to/from latitude and longitude.


Parameter Description Required
target Name of the MAP_VIEW control on which route is to be drawn. Yes
directions_query_id The Id returned by GET_DIRECTIONS action. Yes

Sample Code

The sample code below is taken from the file get_directions_in_text.xml present in the tutorial avm-google-loc-services-tutorial. The action GET_DIRECTIONS is called when user taps the pushbutton get_directions. The action GET_DIRECTIONS generates the event ON_GET_DIRECTIONS_RESULTS.

<control name="get_directions" appearance_name="black" type="PUSHBUTTON"
    x="75" y="10" width="20" height="8" word_wrap="true" default_value="Search">
    <action event_list="TAP" action_name="com.appemble.google.locservices.GET_DIRECTIONS"
        input_parameter_list="origin, destination"
        target_parameter_list="origin_address, destination_address"/>
</control>

The action results are displayed on the MAP using the sample code below.

<action event_list="com.appemble.google.locservices.ON_GET_DIRECTIONS_RESULTS"
            action_name="com.appemble.google.locservices.DRAW_ROUTE" target="map"
            input_parameter_list="directions_query_id"/>

com.appemble.google.locservices.GET_DISTANCES

The action results in distance matrix from each origin to each destination. The results are saved in _distance_matrix table. If distances are to be fetched again, the results are fetched from the local database instead of calling the remote servers.


Parameter Description Required
origins One or more addresses and/or textual latitude/longitude values, separated with the pipe (|) character, from which to calculate distance and time. If you pass an address as a string, the service will geocode the string and convert it to a latitude/longitude coordinate to calculate directions. If you pass coordinates, ensure that no space exists between the latitude and longitude values. Yes
destinations One or more addresses and/or textual latitude/longitude values, separated with the pipe (|) character, from which to calculate distance and time. If you pass an address as a string, the service will geocode the string and convert it to a latitude/longitude coordinate to calculate directions. If you pass coordinates, ensure that no space exists between the latitude and longitude values. Yes
sensor boolean. Indicates whether the application is using a sensor (such as a GPS locator) to determine the application’s location. This value must be either true or false. Yes
mode
Specifies the mode of transport to use when calculating directions. Valid values are:
  • driving (default) indicates standard driving directions using the road network.
  • walking requests walking directions via pedestrian paths & sidewalks (where available).
  • bicycling requests bicycling directions via bicycle paths & preferred streets (currently only available in the US and some Canadian cities).
No
avoid Introduces restrictions to the route. Valid values are specified list of restrictions Only one restriction can be specified. No
units Specifies the unit system to use when expressing distance as text. See the List of unit systems for more information. No
language The language in which to return results. See the list of supported domain languages. No
departure_time Specifies the desired time of departure as seconds since midnight, January 1, 1970 UTC . The departure time may be specified by Maps for Business customers for to specify the departure_time to receive trip duration considering current traffic conditions. The departure_time must be set to within a few minutes of the current time. No
key Key can be obtained from TODO Yes

Sample Code

The sample code fetches the distances between origins and destinations. It is taken from the file distances.xml present in the tutorial avm-google-loc-services-tutorial. The action is called when user taps the pushbutton get_distances.

<control name="get_distances" appearance_name="black" type="PUSHBUTTON"
    x="75" y="10" width="20" height="8" word_wrap="true" default_value="Search">
    <action event_list="TAP" action_name="com.appemble.google.locservices.GET_DISTANCES"
        input_parameter_list="origin, destination, CONSTANT:imperial"
        target_parameter_list="origins, destinations, units"/>
</control>

Upon return the FUNCTION REFRESH_DISTANCE_LIST is called. The function fetches the results from the table _distance_matrix and displays it in the list control distance_list by calling the action REFRESH.

<action event_list="com.appemble.google.locservices.ON_GET_DISTANCES_RESULTS"
            action_name="FUNCTION" target="REFRESH_DISTANCE_LIST"
            input_parameter_list="origin, destination"/>

Download and Import Location Services Plugin

  1. Download `avm-google-loc-services.zip`_ and import plugin to your workspace. The zip file includes the plugin and a sample project.

  2. Add the plugin avm-google-loc-services to your project.

    • Click on your project -> Properties -> Android
    • Click on Add.
    ../_images/avm-google-loc-services.png

    Note

    You can remove the library appemble-android-library from the list of libraries included as the avm-google-loc-services library already includes it.

  3. Create the tables - Location Services uses the content database to store results obtained from Google location API’s. Your content database is located in the assets folder. You can use the SQL script located in avm-google-loc-services/extras/content-db-script.sql. See Working with local content database on how to modify content database. The new created tables holds the queries sent to Google Location API services and the results received from them.