Google Maps v1.6

This package provides capabilities that extend the Avoka Transact platform with integration to the Google Maps Geocoding APIs Including :

  1. Locality Lookup

    Using postal codes to lookup localities

  2. Geolocation Capture

    Using google maps to capture a single geolocation

  3. Reverse Geocoding

    Using a geolocation to lookup an Address

  4. Address Lookup

    Searching for an address on the map from data

To support this functionality this package includes the following components

  1. Google Map

    A google map component use to capture a geolocation by manually placing a marker on it

  2. Reverse Geocode Lookup

    A Dynamic Data Service Button, that uses a provided lat/long location and produces the address located at that point

  3. Locality Search

    An autocomplete that provides search for a locality by postcode

  4. Address Search

    A custom block for doing general address searches

Address Formats

Avoka provides 2 address format options:

Short format address (sometimes called standard 5 field address) is a very common address format used in systems of record and consists of the following fields:

  1. Address Line 1
  2. Address Line 2
  3. Locality
  4. State
  5. Postal Code

Long format address provides a more explicit breakdown of address components:

  1. Building Name
  2. Subdwelling
  3. Street Number
  4. Street Name
  5. Street Type
  6. Locality
  7. State
  8. Postal Code

Where practical we also provide the following addtional fields:

  1. Country
  2. Country Code
  3. Full Address
  4. Postal Flag

Address Field Definitions

Field Description
Address Line 1
(short format only)		 This will be the first of 2 address lines. The contents of this element will depend on the existence of a building name or subdwelling where a subdwelling could be a unit/flat/shop/suite number or a level/floor number. If any of these elements exist then this field will contain these sub-location elements in the following order:

[buildingName] [floor/level] [unit/flat/shop/suite]

If none of these sub-location elements exist then this field will contain:

[streetNumber] [streetName] [streetType]

Address Line 2
(short format only)		 This will be the second of 2 address lines and will be blank unless addressLine1 contains sub-location elements, in which case the addressLine2 will contain:

[streetNumber] [streetName] [streetType]

Building Name
(long format only)		 Occasionally physical addresses include the name of the building they are located within. For example, performing a lookup for 34/267-277 CASTLEREAGH ST will return a building name of MUSEUM TOWERS.
Subdwelling
(long format only)		 The subdwelling value will contain floor/level identifiers and/or unit/flat/shop/suite identifiers.
Street Number
(long format only)		 For physical addresses this value will contain the street number of the address which does not include the unit or flat number, but may be represented as a range (e.g. 267-277). For non-physical addresses this field will contain the PO Box, Locked Bag, or similar data.
Street Name
(long format only)		 Where practical, this field will contain the name of the street only, with street type being provided separately (see below).
Street Type
(long format only)		 The street type value may be provided as an expanded value (e.g. ROAD) or abbreviation (e.g. RD), depending on the lookup service response data.
Locality The locality information varies from country to country but will usually be either suburb or city.
State The State that the address resides in. For some countries (e.g. New Zealand) this may be blank.
Postal Code The regional postal code, also referred to as Zip Code (US) and Postcode.
Country The Country that the address is located wihin, in its expanded form (e.g. Australia).
Country Code Where practical, the Country code will be provided as represented in the ISO 2 character (e.g. AU) or 3 character (e.g. AUS) standards, depending on the data provided by the lookup service.
Postal Flag The postal flag field indicate whether this address is a non-physical address (e.g. PO Box, Locked Bag etc...). Most address lookup providers support the ability to exclude non-physical addresses from lookup searches if required.
Full Address The intention of this field is to provide the full address with the exclusion of Country, as a single one line string. For example:

MUSEUM TOWERS U 34 267-277 CASTLEREAGH ST SYDNEY NSW 2000

Lookup Key This field represents a unique identifier for the address in the 3rd party system and will be different for each provider.

Google Map Pin

The Google Map component supports the ability to add a custom marker image. The formats supported are:

  1. PNG
  2. JPEG
  3. BMP

Licensing

Clients must ensure they are appropriately licensed in order to use this package. Organisations who wish to use this package are required to establish a commercial relationship with Google Maps

This package requires the Google Maps Geocoding API.

Compatability

This package has the following compatibility requirements:

Module Compatibility Notes
Transact Manager 5.0 or above
Transact Maestro 5.0 or above

Installation Instructions

To install this package please walk through the following proceedure:

  1. Unzip the package to a directory on your computer
  2. Import each zip archive found in the services folder to Transact Manager under the Services >> All Services menu item.
  3. Review the Help Doc tab for each of the imported services and make any required adjustments to service parameters.
  4. Configure any required Service Connections. These requirements can be found at the bottom of this document or in the Help Doc for each of the imported services.

    Service Connections can be configured in Transact Manager under the Services >> Service Connections menu item.

  5. Import each archive found in the libraries folder to Maestro.

    Importing these into the Organisation level libraries folder is recommended as this will make the components available to all projects, however they can be imported at the Project level if required.

Release Notes

Version 1.6 May 24, 2019

  • Fix Google Map component to support multiple instances in single form including in repeat.

Version 1.5 Jul 05, 2018

  • Included the Google API key in the services request (Address Search and Locality Search).
  • Added calls to service log.
  • Updated the service connection documentation to use https endpoint instead of http, since we include the API Key in the URL.

Version 1.4 May 03, 2018

  • Added ability to upload image for Map Marker.

Version 1.3 Dec 05, 2017

  • Replaced item.rules property with Form.hasRule, as it was removed from Maestro version 17.10.0 or above.

Version 1.2 Oct 20, 2017

  • Added a click handler on the map image to support an onMapClick rule.

Version 1.1 Oct 10, 2017

  • Added the ability to disable the user pin placement when clicking on a map.

Version 1.0 Jan 12, 2017

  • Baseline release.

Maestro Assets

Google Map Library: exchange.google.maps Category: Google Maps

Rule Templates

You may add your own logic to handle the following rule types triggered by this component:

  • On Map Click : A click handler for the map

Properties

Property Category Description Type Default
Google Maps API Key Configuration

Your Google Maps API Key

text
Height Configuration

Height of the Google Maps component in pixels

integer 300
Initial Latitude Configuration

Starting latitude

text 0
Initial Longitude Configuration

Starting longitude

text 0
Initial Zoom Configuration

Starting map zoom

integer 4
Disable Click Configuration

Disable user pin placement on the map

boolean false
Latitude Location Data

Form field reference for latitude

fieldRef data.$latitude
Longitude Location Data

Form field reference for longitude

fieldRef data.$longitude
Select a marker icon Google Map Pin

Select from the available images resources, or upload a new one

image {fileName=, width=, height=}
Google Maps Reverse Geocode Lookup Library: exchange.google.maps Category: Google Maps

A Dynamic Data Service button that will retrieve and address for a given geolocation

Service Calls

Properties

Property Category Description Type Default
Longitude Input

The Longitude Value to use in reverse geocoding

fieldRef
Latitude Input

The latitude value to use in review geocoding

fieldRef
Address Output

Address Field Outputs (Properties marked with Long and Short are only available when that format is selected)

Field Refs:

  • buildingName : Building Name (Long Format)
  • unitNo : Unit No (Long Format)
  • streetNumber : Street Number (Long Format)
  • streetName : Street Name (Long Format)
  • locality : Locality
  • state : State
  • country : Country
  • postalCode : Postal Code
  • addressLine1 : Address Line 1 (Short Format)
  • addressLine2 : Address Line 2 (Short Format)
 fieldRefMap
Address Format Configuration

Address format to return (valid values are LONG and SHORT)

text LONG
All Caps Configuration

Whether to display the returned results in Uppercase

boolean false

Services

Google Maps - Address Search v1
A General Google Geocode API address search. For information on how inputs affect returned results see Google Geocode API

Service Connection

Compatibility

Module Compatibility
Manager 5.0

Inputs

Name Description Required
addressFormat The format of address to request valid values are LONG | SHORT, defaults to No
withDetails Return results with details about transaction success, if false will return a simple array of No
address A general address search string No
countryCode The country to limit searches to No
postalCode A postalCode to limit searches to No
latitude A latitude location to search for the address at No
longitude A longitude location to search for the address at No
maxResults The maximum number of results to retrieve (0 for no limit) No
allCaps A boolean defining if returned addresses should be in UpperCase No

Outputs

Name Description
addresses A list of [address] returned by the service the output depends on the addressFormat parameter see google.maps package help for more information
status The status of the service call SUCCESS if successful and ERROR if an error occurred
errorMessage A reason for failure if any
Google Maps - Locality Search v1
Provides real-time searches against Google Maps geocoding APIs to search of localities by ZIP codes

Service Connection

Compatibility

Module Compatibility
Manager 5.0

Inputs

Name Description Required
postalCode The postalCode of the locality to search for Yes
countryCode The country to limit searches to No

Outputs

Name Description
country The short name of the localities country
locality The locality of the provided postcode
label A formatted address string for the locality
state The state of the locality
postalCode The postal code of the locality

Service Connections

The following service connections are used by this package.

Google Maps Geocode
Property Name Description Required
Type HTTP Endpoint Yes
Endpoint Should point to Google Maps Geocoding API at: https://maps.googleapis.com/maps/api/geocode Yes
Auth Key Should contain your API key to access the service Yes