SETTING UP MAPPING FEATURES IN TNG
TNG (and sometimes WordPress) users often want to use the maps feature in their software deployments to extend feature sets. Two methods are available—Google Maps & OpenStreetMap (OSM). Google Maps is the primary, and most robust mapping solution available—but involves a more complex setup procedure than OSM. It also has the least issues and most features for TNG. Before discussing the steps necessary to add the Google Maps API key to your application, let’s first look at OpenStreetMap for TNG.
OpenStreetMap Details
According to Wikipedia, “OpenStreetMap (OSM) is a collaborative project to create a free editable map of the world. The geodata underlying the map is considered the primary output of the project. The creation and growth of OSM has been motivated by restrictions on use or availability of map data across much of the world, and the advent of inexpensive portable satellite navigation devices. OSM is considered a prominent example of volunteered geographic information.” The programming code it uses is Open Source, and its GIS data is volunteer submitted and maintained. For more information, read the full article here:
https://en.wikipedia.org/wiki/OpenStreetMap
OSM is a robust solution for those who may have philosophical issues with how Google manages its Maps model—and/or privacy concerns with registering billing information with them. The downside to OSM is that there are still many areas of the world that do not present complete information in OSM’s dataset. As OSM is a volunteer project, work and improvements are ongoing. Secondly, as currently implemented in TNG, the OSM feature does not allow batch geocoding of places. It is a slightly laborious process to include each location that is in your Places via a ‘one at a time’ manual procedure.
That said, Erik Hoppe, with assistance from Ken Roy and Alan Craxford, have developed several versions of a mod that will install OSM capabilities on TNG versions 10.1.3 to 12.x. The URL for this mod, and detailed information can be found in this TNG Wiki article:
https://tng.lythgoes.net/wiki/index.php?title=OpenStreetMap
Additional discussions may be found in the TNG Community forum here:
https://tng.community/index.php?/search/&q=OSM
If one decides to deploy OSM as their mapping feature, it is recommended that they sign up for a free OSM account. The URL for the official OSM site is:
At the time of writing this article (v1.1, 9/28/19), two TNG mods have been found to be incompatible with the OpenStreetMap mod. These must be uninstalled prior to loading the map mod (if you are using either)—and cannot be installed/reinstalled later. They are: Placesearch-More Info and Cemetery_Edit. This may change in future iterations of the mod—check the mod’s TNG Wiki page in the future for updates.
For those seeking parallel OSM features in the WordPress side of a WP/TNG integration, this excellent WP plugin for OSM is available:
https://wordpress.org/plugins/osm/
Google Maps Details
According to Wikipedia, “Google Maps is a web mapping service developed by Google. It offers satellite imagery, aerial photography, street maps, 360° panoramic views of streets (Street View), real-time traffic conditions, and route planning for traveling by foot, car, bicycle and air (in beta), or public transportation…Google Maps offers an API that allows maps to be embedded on third-party websites…” For more information, read the full article here:
https://en.wikipedia.org/wiki/Google_Maps
For several years now, Google has requested or required the use of an ‘API key’ to access and present maps that are embedded in a website. Google’s API mapping library includes numerous options, including Maps JavaScript, Geocoding, Directions, Places, Street View, and many others. The first two API’s are of interest to TNG users, as they provide the map views and enable bulk geocoding of Places that have been linked to Persons, Cemeteries, and Events.
In order to understand the steps to get a working API key–and what the issues are for existing ‘long time’ users who have found their maps no longer work—a bit of history is necessary. Prior to 2018, Google’s map platform was a curious mix of 18 different services scattered about various admin consoles and webpages. By May of 2018, Google had consolidated all map API’s into three distinct services, placed all of them under a single Google Cloud Computing interface, and merged the existing Basic and Premium plans into one single plan.
The final changeover for all Maps users happened on June 16, 2018. For a while, site owners still had functioning map displays on their sites—but gradually over time, their old methods (and API keys) ceased to function properly. This results in either a blank display (in the case of a single digit such as ‘1’ entered into the key field) or the now common (and infamous) display image as shown below. All embedded Google maps users now require an API key as of the June 2018 date.
Both issues can be resolved by following the setup instructions in this guide. Aside from consolidating services, another reason for the changes and requirement for registration and billing accounts with Google is that many sites ranging from small to large were abusing their API access with humongous numbers of resource calls under the Basic plan. Consolidation of both plans eliminated that abuse—and contributed to Google’s bottom financial line.
A few current and potential Maps API users have made an objection to the requirement that users must create an integrated billing account and provide a payment method in the event resource use exceeds what is provided for ‘free.’ It is important to understand that the average TNG user is NEVER going to approach—no less exceed the limits and be charged for mapping access.
As a parallel offering to the former ‘Basic Plan’ for most small users, Google now provides a monthly recurring $200 credit against any charges. Essentially, one’s site would have to rack up over 28,000 map and geocoding calls in a single month to incur any payable charges. One can also set quota limits to put a cap on usage and prevent overage charges. Simply stated, charges are not a concern for most users—and can be soundly dismissed as a reason for not deploying Google Maps within their TNG site.
Full disclosure on Google’s current pricing schema for Maps, Routes, and Places is to be found here:
https://cloud.google.com/maps-platform/pricing/
As noted previously in this discussion, some people do not wish to provide Google with a credit card number to enable billing. This writer is not going to argue the case one way or another—as this is a matter of personal choice. For those who find the billing requirement problematic and want to enable maps in TNG, the only other viable option is to return to the previous discussion on OpenStreetMap and use that method as your map deployment.
Getting/Updating a Google API Key
It is assumed that most people considering enabling Google Maps will already have a working Google account. If you do not, follow the instructions below as it is not possible to acquire and provision a valid Maps API key without one. If you do have an account, skip to the next step.
Creating a Google Account
Open the following URL in your browser of choice:
https://myaccount.google.com/intro
Click on “Create a Google Account” link just below the |Sign in| button as shown in the image below.
The next screen you see will look like the image below—without the text I have added! There are two options here. If you choose the default option, Google will automatically create a new gMail account for you with the username you have provided. If you don’t want that, click on the |Use my current email address instead| link, and fill out the email field with your preferred email address.
If you choose to use your own existing email address, an email will be sent to you requiring confirmation of that address as valid before your new Google account is fully activated. In either case (existing email or new gmail account), the next screen will ask you several questions. Except for the phone number, the remaining fields are required. Continue along any menus or steps asked for (such as agreeing to Google policies) and your account will be complete. Be advised that you can use your Google Account credentials on Google Drive, YouTube, Docs, and the Google Web Store. After confirming your existing email (if necessary), you may now proceed to the next step.
Configuring a Project on Google Cloud Platform
Bring up the Google Cloud Console entry page by visiting the URL shown below. If you have just created your new account, you may be automatically directed to the main console page. Otherwise, enter any existing Google credentials you have (new or old).
https://console.cloud.google.com
Depending on whether you are logging in with a new account or it’s been some time since you visited the Console, a popup may appear asking you to confirm your country and agree to the Cloud Platform terms of service. Agree, and continue. Your resulting screen will look like this (without the red arrow):
Yes, it’s a bit daunting at first! Your first step is to click on the |Billing| link in the left panel, as shown by the red arrow. Here you will provide the information necessary to enable the Google API Library for use. After clicking, a popup will invite you to |Add billing account| if you have not previously one—or if you have, show you the |Billing Account Manage| link. In the case of the former, provide all the information requested on the page. If you already have a billing account, click the link and review your information for accuracy.
As a new user, disregard the dire notice of “No autocharge after free trial ends.” This only applies when the Trial Period ends and if you exceed 28K calls to your API—or if you are using some other Google Cloud service such as Computing, Storage, or AI. Your next screen after accepting the agreement will look like the second image on the right:
 |
|
Enter all the requested information and click on |Start My Free Trial|. Do not think for a moment that you can thwart Google by entering an imaginary credit card number. When clicking the Start button, it will run a valid card account check—and on failing ask you to correct any errors!
On the return screen, you will use the Projects dropdown in the top bar to create a new project if you are a new user. If you are an existing user and need a new API key, you will follow the same steps. Our recommendation is for existing users to create a brand-new Project and environment for their new updated key.
In the top blue bar of your screen, click as shown on the |Google Cloud Platform| title to reload the page. When the screen refreshes, you will see a display dropdown that reads “Select a Project” or “My First Project.” Click on the item and select “New Project” from the resulting popup dialog.
 |
 |
Title this something appropriate and click the |Create| button. On the resulting screen that has “Project Info” in it, look at the left services pane and navigate to |APIs & Services|Credentials| and click.
Click on the |Create credentials| button and select |API key| as shown below. This will return a screen showing a popup stating “API key created” and an option in the lower right of the box to |Restrict Key|.
 |
 |
First, copy your new API key by clicking on the double page icon to the right of it, or via highlighting and a copy command. Paste this key somewhere you can find it again, such as on a Notepad text file, a Word doc, or other accessible place. You will need it again! Do not close the popup window yet.
Now click on the |Restrict Key| link. (shown in graphic above). Give your API key a new name of your choice. Under “Application restrictions” select the “HTTP referrers (web sites)” radio button. This prevents others with bad ideas from hijacking and using your stolen credentials to supply their sites for free!
Under the section “Website restrictions” click on “Add an Item.” There are a few options to consider in setting the URL.
- If you are sure that all your TNG files are in the root directory of your domain folder, insert ‘https://yourtngsite.com’ without the apostrophes and changing the name to that of your registered domain. If your site does not support HTTPS, you would enter ‘http://yourtngsite.com’ as the referrer.
- If you have TNG in a subdirectory or subdomain, it is necessary to use wildcard referrers in this field. The most common would be *.yourtngsite.com/* .
Click on DONE when you have entered your preference. Finally, click on the “Don’t restrict key” radio button. This may sound counterintuitive as you are doing all this to restrict the key! But this section applies to other Google Cloud services that may want to use the key. This is not pertinent to our mapping needs. To finish this part, click on the “Save” button.
Adding Mapping API’s
At this point, you have successfully created an account, created a new project, and created a new key for that project. Our last major step on the Cloud Console is to add our two necessary Google Maps API libraries to the key!
You now are at a ‘Credentials’ page showing all of your keys. Our next task is to click on the |Library| link in the left navigation pane. The resulting page will show you everything that Google offers as an API. Your top row will maps API’s, and in the right a “View All (15)” link. Click on that link and your resulting screen will look like this:
Let’s first load the mapping function library. Click on the “Maps JavaScript API” box. The resulting page has an |Enable| button at the top left of the title bar. Click it! The screen will show the API being installed and then return to a metrics monitoring page. Click on the blue ‘back’ arrow next to the Maps JavaScript API title as shown below on the left:
 |
 |
As shown in the diagram to the above right, under “Additional APIs” click on |Geocoding API|. Same as installing the previous API, click on the |Enable| box. When the screen completes, you are essentially finished with setting up your Google Maps access key.
If you do not wish to set the optional quotas, you are done with your API project, and may now go into TNG and load your key!
[OPTIONAL] Setting Access Quota’s
As noted earlier in this guide, those that are concerned about possible charges can set monthly quotas on API usage. At the present pricing schema, it takes slightly over 28K calls to the API before exceeding the $200 monthly ‘free’ allowance. Let’s also dispel a common misconception. Bots, search engine spiders, and crawlers DO NOT call up your TNG maps and rack up your API call count. ONLY public calls made by you or a visitor and displaying a page add to your Google count.
If you wish to limit these display calls to on-demand visitor requests, you can install a TNG mod that collapses the map—and requires the visitor (or you) to expand the map and thus make the API call at that time. The name of this mod is “Person Map” and it may be downloaded from the link below. Instructions to enable this feature can be found below in the Loading Your Key in TNG section.
https://tng.lythgoes.net/wiki/index.php?title=Person_Map
Let’s qualify how to set quotas. In the Maps JavaScript API, all public calls to create the page will count. Geocode API calls are not made by any public visitor, only by you when geocoding places. As such, I do not personally set a quota on Geocoding. As the Maps API has a limit of 28K a month for free, I have my quota set at 20K, which would allow me around 5K geocoding calls a month–presuming there were 20K map calls! People geocoding for the first-time thousands and thousands of places should not worry—as everything will balance out.
To set a quota on your Maps (or Geocoding if you wish), return to the “Overview” page for your project in the Console. There you will find a screen showing your Enabled APIs, like the graphic below.
Click on the Maps JavaScript API line as shown by the red arrow. Your page will now look like this after you click on the |QUOTAS| tab:
Click on the ‘edit pencil’ graphic as shown by the arrow in the above graphic. In the popup screen that appears, enter your desired monthly quota amount, without any commas. Click |Save| and you are done! You may repeat these steps for the Geocoding API if you wish, but it may cause you trouble down the line…
You have completed setting up your Maps key, and can now enter it in TNG!
Loading Your Key in TNG
This is the simplest part! Log into your TNG Admin control panel and select |Setup|Configuration|Map Settings|. In the resulting screen, copy and paste your Google project key into the Map Key field as shown below. Modify any other fields as you feel necessary. If you have installed the ‘Person Map’ mod, a setting for hiding maps will be available. See the section below the graphic for options.
Options
Set to determine whether you want the Map Type to display:
- Map (standard Google street map)
- Satellite (combination of aerial and satellite images of terrain)
- Hybrid (aerial/satellite images with overlay of location names)
Options available for Hide Admin Maps to Start
- No – Admin Place Edit will show the map by default
- Yes – Admin Place Edit will show a Show / Hide Clickable Mapbutton with the map collapsed
Options available for Consolidate Duplicate Pins
- No – Every unique event will get its own pin number
- Yes – All events at the same location will be conflated into a single number
Event Map Section Behavior (with the Person Map mod installed)
Start with Expanded Section
- Yes—Maps load fully expanded
- No—Maps are collapsed and require user toggle to expand
Allow to toggle the visibility
- Yes—Allows the user to expand or collapse the map
- No—Hides the map
Reset location markers on unhide
- Yes—Reloads the location markers when expanded
- No—Retains static location markers
Scroll event map section to
- Choices are Browser Default, Top, Middle, and Bottom. Default is recommended
That’s it! Happy mapping…
CLICK HERE TO DOWNLOAD THIS GUIDE IN PDF FORMAT
This guide is written and maintained by Patrick Thrush ©2019+
Rights are governed by a Creative Commons Attribution-NonCommercial 4.0 International Public License
Read the details here: https://journeysingenealogy.com/copyright-considerations/
Leave A Comment