<Locations>

Gigatrees5 supports two types of Maps: Heatmaps and Named Location maps. The heatmaps (Population Distribution Heatmap and Origin Maps use a Google map to display the location markers using the latitude and longitude for each location and is overlaid with a density heatmap. When multiple location markers occur in close proximity, they are grouped together and their total count is shown. Zooming in on a map regroups the markers. Hovering over a location marker display an information window showing the location name, the coordinates, and hyperlinks to the persons found at that location.

The map display is controlled by the gigatrees-maps plugin. Technical users can modify the file to change the heatmap gradient, radius and opacity, the initial and maximum map zoom level, map center and bounds, enable roads and in general muck with its look and feel. You may be able to get some tips from the Google development site. The location and group markers are also located in the plugin folder and can be replaced if desired.

The Named Location maps appear on the location pages and also use a Google map to display the location marker using its latitude and longitude. When location coordinates are missing, Google will use the location description to perform the client-side geocoding lookup. Google requires an API key to perform this lookup and to display the results. If you see any of the following errors when viewing the named location maps, then Google needs the API key or the API key is misconfigured: Oops! Something went wrong., Cannot load this page correctly; Do you own this site?. To obtain an API key from Google, go to https://developers.google.com/maps/documentation/javascript/get-api-key and click on the "[Get Key]" button. You will need to create a dummy project if you do not have one already. If you are viewing your maps online, you will need to set a restriction under HTTP Referrers for your domain path. This restriction will prevent web scrapers from discovering your key and using up your allotment of free queries. If you are viewing your maps offline, no restriction should be necessary. The API key allows Google to restrict lookups to 25,000 per day for free uses (more than enough).

In order to use the heatmaps maps effectively, all locations found in your location file must include associated coordinates. Most of us, of course, do not have or add coordinates manually. Gigatrees supports configuring automatic geocoding that will query one or more free servers, to resolve any missing coordinates found while processing.

To obtain an API key for the MapQuest geocoding service, you will need to go to https://developer.mapquest.com/plan_purchase/steps/business_edition/business_edition_free/register, signup and follow their instructions to obtain a Consumer Key and then enter that key into the MapQuest Geocoding Key option in the configuration. To obtain an API Key for LocationIQ, goto https://locationiq.org , signup and follow their instructions to obtain an AI token and then enter that token into the LocationIQ Geocoding Key option in the configuration.

When Gigatrees5 runs, it will check each location it finds in your genealogy database to see if the coordinates for that location are contained in the location file as well. Gigatrees5 supports non-standard GEDCOM location records ( PLAC and _PLAC_DEFN ) as well as standard GEDCOM location coordinate fields ( PLAC.MAP ). If it finds coordinates for a location it will use them and go on to the next location. If it does not find embedded coordinates, it will check to see if coordinates for that location have already been added to the locations file ( gigatrees.sqlite ) located in the installation's includes folder. If it finds coordinates for a location it will use them and go on to the next location. If it does not an find coordinates in the location file and if either of the gecoding services are enabled (have an API/Geocoding Key) it will query each service in order, using the location description, until it gets a positive result or until all services have been queried. When it gets a positive result, it saves the coordinates into the location file, uses them and then goes on to the next location. If it does not receive a positive result from any of the geocoding services, it will strip off the most specific term of the location description, such as a street address or town name and re-query the geocoding services using the partial description. It will repeat this process, stripping off ever more specific terms until it gets a positive result. This will result in less specific coordinates being cached for a location, such as a town or city center instead of a street address. In this way, only location descriptions that include unrecognizable country names will not be resolvable. Unresolvable locations may re-query the geocoding services each time you run the application. It is important, therefore, that the location descriptions provided by your genealogy database can be resolved by at least one of the geocoding services. Genealogists tend to enter their location descriptions in the format they are found in their source materials. This may result in archaic descriptions being entered. Prior to the use of geocoding services this was considered a good practice, however, these services will not recognize obsolete descriptions, so I recommend that users enter only modern location descriptions into their genealogy databases, and add the original descriptions to their location fields in the form of a note of some sort. Future genealogy standards will undoubtedly include a separate field for original location descriptions. When upgrading Gigatrees5 to a new version, the location file should be copied over to the new installation so that your cached coordinate lookups are retained. Ideally you would move your location file to a folder outside the installation's includes folder so that the file won't be overwritten when upgrading.

All of the coordinate lookup services that Gigatrees uses throttle requests by limiting how often they can be queried and how many queries are permitted per hour and per day. MapQuest limits queries on free accounts to 15,000 per month and LocationIQ limits queries to 10,000 per month. Gigatrees5 is therefore limited in how quickly it can resolve missing coordinates. It generally takes running the application several times over a period of days to complete the process for a new genealogy database. If Gigatrees5 hits a restriction for one service, it will try another. If Gigatrees runs into a restriction for all services, it will stop making requests until the next time it is run. Re-running Gigatrees to get around these restrictions will not help, since the limitations come from the external servers. Once all coordinates have been resolved, Gigatrees will stop querying the services. You can monitor the geocoding progress in the build log. It will tell you when the process is complete and if it aborted, the reason.

If the original location description could not be resolved or resolved to a less specific location such as a town or city center instead of a street address, you can adjust your location description to be more accurate and rerun the program, or you can manually enter the correct coordinates into your database into one of the above-mentioned supported GEDCOM records or here using the <Location> option.

Gigatrees:
<LocationFile> [ ] The absolute or relative file path to the location file.
<AcceptLang> [ en ] The geocoding server's query language. If your location are not entered in English, you will need to use the correct language code. See the geocoding server's documentation for the proper format of language codes.
<MaxCoordQueries> [ 500 ] Due to throttling by Gigatrees5 and the geocoding services, querying can a long time. You can change this value to increase or reduce the number of total queries to perform be execution of the application.
<MapQuestGeocodingKey> [ ] Enter your MapQuest geocoding key. It will be used only for querying the MapQuest server.
<LocationIQGeocodingKey> [ ] Enter you LocationIQ geocoding key. It will only be used for querying the LocationIQ server.
<GoogleMapsApiKey> [ ] Enter your Google Maps API Key. This value is used to substitute the %GoogleMapsApiKey% in the googlemaps plugin.
<CleanupLocationDescriptions> [ true ]Gigatrees5 attempts to automatically cleanup location descriptions by filling in missing elements, replaving abbreviations, etc. Disabling this option will show your original description in instances.
<Location> This tag indicates the beginning of a new location coordinate definition.
<Description> [] The original location description.
<Latitude> [] The location's latitude.
<Longitude> [] The location's longitude.
Example:
<Locations>
<LocationFile> includes/gigatrees.sqlite </LocationFile>
<AcceptLang> en </AcceptLang>
<MaxCoordQueries> 500 </MaxCoordQueries>
<MapQuestGeocodingKey> dksdgjwpeogmwmg </MapQuestGeocodingKey>
<LocationIQGeocodingKey> dhw;[[l[lerfdf </LocationIQGeocodingKey>
<GoogleMapsApiKey> h[h[r[[r[oyoh.fhh </GoogleMapsApiKey>
<CleanupLocationDescriptions> true </CleanupLocationDescriptions>

<Location> <Description> Palestine </Description> <Latitude> 31.952162 </Latitude> <Longitude> 35.233154 </Longitude> </Location>
<Location> <Description> Acre, Palestine </Description> <Latitude> 32.933957 </Latitude> <Longitude> 35.079946 </Longitude> </Location>

</Locations>
Troubleshoot Named Location Maps:

If your Google maps are not appearing as expected, I recommend you follow the following procedure on a new installation. This will test that your Google Maps API key is valid and setup correctly.

  1. Enter your API key under Google Maps API Key in your configuration file.
  2. Save the file and run the application.
  3. Go to Locations in your website's menu.
  4. Click on the first location - you should now see a functional Google map.
Troubleshoot Heatmaps:

If your heatmaps are not appearing as expected, I recommend you follow the following procedure on a new installation. This will test that your Google Maps API key is valid and setup correctly as well as your MapQuest and LocationIQ geocoding keys.

  1. Enter your API key under Google Maps API Key and your other keys under MapQuest Geocoding Key and/or Location IQ Geocoding Key
  2. Save the file and run the application.
  3. Go to Map in your website's menu.
  4. You should now see a functional Google heatmap.