Geocoding and Maps

Geocoding and Maps

Gigatrees supports two types of : Heatmaps and Named Location maps. The (Population Distribution Heatmap and Origin Maps) use a Google map to display the markers using the and for each location and is overlaid with a density heatmap. When hovering over a location marker, information such as location name, coordinates, and hyperlinks to the profile pages of each individual found at that location is displayed. The Population Distribution Heatmap [1] includes the locations of all dated and undated events found in your database. The Origin Maps are found on the profile pages of individuals who have ancestors and display only the first dated event for each ancestor; usually their birth date, but if missing, a baptismal date or something later. This map type gives a representation of where each person's ancestors were born.

"Map Page (partially zoomed)"
Map Page (partially zoomed)

The Named Location maps appear on the location profile pages and also 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 geocoding lookup. Google requires an API key to perform this lookup when online, when being viewed offline no API key is required. Once the coordinate lookup process is complete (as described below), the API key will not be necessary. If you see the following error when viewing the named location maps online, then Google needs the API key: "Oops! Something went wrong." 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. Once you have created a key, be sure 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. The API key allows Google to restrict lookups to 25,000 per day for free uses (more than enough). Once you have an API key, you can add it to the Google Maps API Key option in the Coordinate configuration. In addition to the map, Location pages also display a timeline for every event found at that location which makes it easy for genealogists to isolate which individuals might be found at a particular location over any particular timeframe.

"Location Profile Page"
Location Profile Page

In order to use the maps effectively, all locations found in your database must include associated coordinates. Gigatrees will use the coordinates found in your database, but since most databases do not include coordinates, Gigatrees supports a Coordinates automatic geocoding that will query one or more external servers [2], to resolve any missing coordinates found while processing. Once the coordinates have been obtained, they will be cached into an SQLite database (located in the "includes" directory) so that future lookups of that location will no longer be required. If coordinates cannot be resolved for a location description using any of the lookup services, Gigatrees will strip off the most specific term, such as a street address or town name and requery the lookup services using a partial description. It will repeat this process until the description can be resolved. This will result in less specific coordinates being cached for a location, such as a town or city center. In this way, only location descriptions that include unrecognizable country names [3] will be unresolvable and marked invalid. It is important, therefore, that the location descriptions provided by your database can be resolved by at least one of the lookup services. (The Pin It utility can be used to lookup a recognizable location description). 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 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 Gigatrees to a new version, the SQLite database should be copied over to the new installation so that your coordinate lookup are retained.

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. Gigatrees is therefore limited in how quickly it can resolve missing coordinates. It generally takes several executions over several days to complete the process for a new database. If Gigatrees hits a restriction for one service, it will try another. If Gigatrees runs into a resctriction for all services, it will stop making requests until the next time it is executed. 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 for any reason.

"Coordinates Page"
Coordinates Page

In order use the geocoding service you must obtain a geocoding key from one of the services listed on the Coordinates configuration page. The page includes clickable links that will take to the services' signup page. The sign up process is simple and free. The signup with MapQuest, go to: https://developer.mapquest.com. To sign up with Location IQ, go to: https://locationiq.org .

Alongwith coordinate resolution, Gigatrees also cleans up displayed location descriptions by inserting state and country names when missing. There are quite a few other minor modifications that it will make to the descriptions, all of which include making certain assumptions about the descriptions provided. This can result in occasional mistakes that can be easily resolved by providing accurate, modern and resolvable location descriptions up front. Location name cleanup occurs at the time of coordinate resolution and can result in the filename for the location being modified to reflect the cleaned up name. If you do not delete all the files from your build folder before execution, this may result in obsolete files being left behind. These obsolete files can be easily located by sorting the build folder by date and removing those files with older dates.


Footnotes:
 [1]Map in the menu
 [2]MapQuest, LocationIQ
 [3]The coordinate database comes preloaded with common state and country names and abbreviations. Users can edit the SQLite database directly to add alternate spellings for these though this is generally not necessary.
  • Last Modified:
Built with Gigatrees 4.5.2