Version 3.04.00 introduces support for Google’s Maps Embed API embedded map.

Traditionally, embedding an interactive Google map onto a website was done without the need for any authentication or API keys. You would create an iFrame with the source looking something like the below URL, and you would get a fully interactive Google Map placed on your website.

http://maps.google.com/maps?q=19+Marine+Parade,Bluff+Hill,Napier,New+Zealand&output=embed

finPOWER Connect uses this to display the Client map in the Client Key Details Summary Page.

Google now prefers the new embedded map approach, which requires an API Key. They are pushing this method so much so that they have removed any reference to the old method in their documentation. More information about the new API can be found in the Google documentation here:

The Maps Embed API overview

Outages

We have found that there have been several instances recently where applications using the old method of embedding presented an error in place of the map for up to 24 hours at a time. During these outages, applications which use the API Key embedded map were still displaying their maps as expected.

This suggests that support from Google for the older method is less reliable than the new. It is possible that this method will be removed entirely in the future, and for that reason version 3.04 of finPOWER Connect supports the API Key method of displaying a map.

finPOWER Connect Changes

For some time now, the ability to configure Browser & Server Google API Keys has been available in Global Settings, Clients, Addressing within finPOWER Connect. These settings were largely unused by the core system, and were predominantly only available for custom Scripting or Portals. An API Key entered here will now be used if configured to use the Maps Embed API.

If you do not have a Google Map API Key, or your existing API Key is not valid with the Embedded Map API then see the Setting up your Google Maps Embed API Key section below.

New fields have been added which allow configuration of the API Key embedded map method (outlined in the screenshot below). Once configured, you can switch your database to the new method simply by checking the Use API Embedded Maps? checkbox. If there are any errors as a result of invalid configuration, they will be displayed in place of the map within the Summary Page.

The Embed URL text box will only have a blank tip populated if an API Key has been specified. Note that the tip will change depending on whether a Browser or Server Key has been specified. If both have been specified, then the Browser Key has priority. Without either, the API Key method will not work and therefore there is no blank tip.

Setting up your Google Maps Embed API Key

Google has its own help to guide Users through the process of obtaining or updating an existing API Key to work with the Maps Embed API.

Setting up in the Google Cloud Console

This link is also available in Global Settings.

At the time of writing this Blog, an API Key for use with this API is free. The Google Documentation mentions the requirement to create a Billing Account; however, in our testing we have found that a Billing Account does not need to be created and linked to the project so long as the Maps Embed API is the only API subscribed to.

 

If your business already subscribes to Google APIs, you will need to enable the Maps Embed API within your existing project to use the same API Key. Otherwise, create a new project to be issued a new API Key. 

Once you have been issued your Maps Embed API enabled API Key, this should be configured in Global Settings, Clients, Addressing, Browser Key or Server Key.

 

If you have any questions regarding setting up your Maps Embed API Key, please contact your Dealer.

why is using the Maps Embed API better?

Reliability

As mentioned at the beginning of this Blog, we have noticed the number of outages of the old method increasing; switching to the new API provides a more reliable map. It may be the case that the old method will be shut down by Google entirely at some stage, leaving those unprepared scrabbling to update their databases.

More Customisable

Modifying the default URL when using the Maps Embed API allows for the map to be customised to better suit your needs.

Embedding a map

The above link provides examples on how the URL can be modified to display differently. For example:

Map View / Satellite View
The default map display for the API is “Map”. To switch this to be “Satellite” to use as default, the below can be appended to the URL in Global Settings:

&maptype=satellite

The full URL in Global Settings would look like this:

https://www.google.com/maps/embed/v1/place?key=[APIKey_Browser]&q=[Address]&maptype=satellite

 

Map Zoom
The zoom of the map can be adjusted by appending &zoom=X, where X is a number from 0 (the whole world) to 21 (individual buildings). The full URL in Global Settings would look something like this:

https://www.google.com/maps/embed/v1/place?key=[APIKey_Browser]&q=[Address]&zoom=20 

 

It is possible to combine additional parameters. For example, to set the display as Satellite and also set the map zoom to 20, then the URL in Global Settings would appear like so:

https://www.google.com/maps/embed/v1/place?key=[APIKey_Browser]&q=[Address]&maptype=satellite&zoom=20 

Refer to the Embedding a map link in the More Customisable section above to see the full list of supported parameters. At the time of writing this Blog, map zoom and display appear to be the most relevant for finPOWER Connect, however Google may add additional useful parameters in the future.