Places

The places module is intended for use with Googles Places API. The places table allows a limited amount of information to be cached locally by your service to improve performance. You should ensure that your specific usage is allowed under Googles Terms and Conditions.

Generally, the indended usage is that a user provides a free form 'input' that is stored in places table. Using Google's Place Autocomplete request, this input is used to retrive one or more place suggestions, each of which contains a 'description', 'main_text', and 'secondary_text', which are stored in the 'places_suggestions' table.

https://maps.googleapis.com/maps/api/place/autocomplete/json?input=100+Queen+Street,+Brisbane&key=<API KEY>

If only one suggestion is returned, the system will automatically perform a Google Places Details request, which will return further information which will be stored in the 'places' table; otherwise, a person will need to manually select which suggestion should be used for the address. Once a suggestion has been confirmed, its details will be retrieved and stored in the 'places' table.

Note, it is envisioned that use of this module will also involve use of the front-end Google Places Javascript API, which will reduce the need for such manual intervention.

https://maps.googleapis.com/maps/api/place/details/json?placeid=EjtCcmlzYmFuZSwgNzMgRGVubmlzIFJvYWQsIFNwcmluZ3dvb2QsIFF1ZWVuc2xhbmQsIEF1c3RyYWxpYQ&key=<API KEY>

Lifecycle 1

Front-end invokes call to 'Base Places Autocomplete' procedure, which creates a new tuple in 'base_places' table storing 'input'.

Base_Places_Autocomplete( <sid>, <input> )

Back-end process calls 'Base Places Unprocessed' procedure, which returns tuples in 'base_places' table that have no associated tuples in the 'base_places_suggestions' table; then for each such place calls Google Places Autocomplete request.

Base_Places_Unprocessed( 'LOCAL' )

For each suggestion returned, the back-end process will store the suggestion in the 'base_places_suggestions' table.

Base_Places_Suggestions_Replace( 'LOCAL', 0, <PLACE ID>, <place id>, <description>, <main text>, <secondary text> );

If only one suggestion is returned, the back-end process will also set the 'CONFIRMED_PLACE_SUGGESTION_ID' field of the 'base_places' table.

Base_Places_Save( 'LOCAL',  <PLACE ID>, 'CONFIRMATION_PLACE_SUGGESTION_ID', <CONFIRMATION_PLACE_SUGGESTION_ID> );

If manual intervention is required, all unconfirmed place suggestions can be retrieved - optionally only suggestions related to a specific place may be retrieved:

Base_Places_Suggestions_Unconfirmed( <sid>, [PLACE ID] )

A suggestion can be associated with place using the 'Base Places Save' procedure.

Base_Places_Save( 'LOCAL',  <PLACE ID>, 'CONFIRMATION_PLACE_SUGGESTION_ID', <CONFIRMATION_PLACE_SUGGESTION_ID> );

A back-end process will then retrieve all places that have had a suggestion confirmed, but are still incomplete:

Base_Places_Incomplete( 'LOCAL' )

For each of these tuples, the back-end process will call the Google Places Details API passing the google place id, and will use the return result to complete its tuple in the 'base_places' table.

Base_Places_Update( 'LOCAL', <PLACE ID>, <street number>, <street>, <suburb>, <city>, <state>, <country>, <postal_code>, <latitude>, <longitude> );