<Locations>

Gigatrees supports two types of Maps: Population Distribution maps and Location maps.

Location Maps

Each location in your database will have its own location page and will use a Google map to display the location marker based on its description, or if they're known, its latitude and longitude. Gigatrees will look for coordinates in non-standard GEDCOM location records ( PLAC, _PLAC_DEFN, _LOC and _PLAC) and in standard GEDCOM location coordinate fields ( PLAC.MAP ). In most cases, coordinates are not required for Google to draw the map correctly, but in those rare cases where it errs, users may use this option to force appropriate coordinates.

When creating location pages, Gigatrees will cleanup the location descriptions using recognized international counties (and their ISO abbreviations) and country states (and their ISO abbreviations), which for most users is seemless. If however you are an international user or a non-English speaker, you may want to add new or modify existing counties and states, or, God forbid, disable the cleanup altogether.

Population Distribution Maps

Origin Maps and Ancestor 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 displays an information window showing the location name, the coordinates, and links to the persons found at that location. Population distribution maps are only displayable online, so you must enable the <Database>.

The map display is controlled by the googlemaps plugin. Technical users can modify the gigatrees-maps.js 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 as long as the names remain consistent.

Google requires an API key to display the map. If you see any of the following errors, the API key is missing or misconfigured, or you are attempting to view the map offline: 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. The API key allows Google to restrict lookups to 25,000 per day for free uses (more than enough). You will need to set a restriction under HTTP Referrers for your domain path. This restriction will prevent web scrapers from discovering your API key and using up your allotment of free queries.

Geocoding

In order to use the population distribution maps, all locations must have coordinates associated with them. Most of us, of course, do not have or add coordinates manually. Gigatrees supports configuring automatic geocoding that will query a free server to resolve any missing coordinates found while processing.

To obtain an API Key for LocationIQ, go to 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.

Gigatrees supports the standard and non-standard GEDCOM location records mentioned above. If it finds coordinates for a location it will use them otherwise, it will check to see if coordinates for that location have already been added to the default locations file ( config\geodata.sqlite ). If it does not find coordinates in the location file and if the geocoding service has an API/Geocoding Key configured it will query the service using the location description. When it gets a positive result, it saves the coordinates into the location file, otherwise 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 service 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 service each time you run the application. It is important, therefore, that the location descriptions provided by your genealogy database can be resolved. Genealogists tend to enter their location descriptions in the format they appear 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 Gigatrees to a new version, the location file ( config/geodata.sqlite ) 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 different folder so that it will not be overwritten when upgrading.

The coordinate lookup service that Gigatrees uses, throttles requests by limiting how often they can be queried and how many queries are permitted per hour and per day. LocationIQ limits queries to 10,000 per month. Gigatrees 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 Gigatrees runs into a restriction, 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 service. You can monitor the geocoding progress in the build log (and the User Dashboard), which will tell you when the process is complete, or if it aborted, the reason. You can configure Gigatrees to limit the maximum number of queries to perform each time it runs using the <MaxCoordQueries> option.

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 fields, or using the <Location> option.

Example

<Locations>
   <LocationFile>                config\geodata.sqlite      </LocationFile>              
   <AcceptLang>                  en                         </AcceptLang>            
   <MaxCoordQueries>             500                        </MaxCoordQueries>       
   <LocationIQGeocodingKey>      dksdgjwpeogmwmg            </LocationIQGeocodingKey>
   <GoogleMapsApiKey>            dksdgjwpeogmwmg            </GoogleMapsApiKey>      

   <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>
   
   <CleanupLocationDescriptions> true </CleanupLocationDescriptions>
   
   <Country>
     <Name>      Canada       </Name>
     <Code>      CAN          </Code>
     <Preferred> true         </Preferred>
   </Country>	
   
   <State>
     <Name>      Newfoundland  </Name/t>
     <Code>      NL            </Code>
     <Country>   CAN           </Country>
     <Preferred> false         </Preferred>
   </State>
   
   <State>
     <Name>      Newfoundland and Labrador </Name/t>
     <Code>      NL                        </Code>
     <Country>   CAN                       </Country>
     <Preferred> true                      </Preferred>
   </State>
</Locations>

Options