class Location - jcobban/Genealogy GitHub Wiki

Up: Object-Oriented Access to Database Records

Table of Contents

Source Code

This class is derived from Record to implement the logical interface to a record in the Location table (Locations or tblLR). Each entry in this table contains the description of a Location which may appear in Events.

Fields

This record presents the following fields:

name notes and synonyms
'idlr' Exists to permit multiple records to have the same value of 'location'
'fsplaceid' Family Search location identifier.
'location' 'name' The location name as it appears in descriptions of events.
'used' 1 if the location is referenced by an event.
'sortedlocation' This is the value of 'location' rearranged if necessary so that all of the addresses on a particular street or in a rural concession sort naturally by lot number.
'latitude' a number of degrees as a decimal floating point number between -90.0 and 90.0. For geo-location. For compatibility with Legacy Family Tree it is stored in the database in sDDMMSS.ddd format.
'longitude' a number of degrees as a decimal floating point number between -180.0, for longitude west of the prime meridian through Greenwich, and 180.0 for longitude east of Greenwich. For geo-location. For compatibility with Legacy Family Tree it is stored in the database in sDDDMMSS.ddd format.
'tag1' 0=no, 1=yes. Not used by this implementation but retained for compatibility with Legacy Family Tree.
'shortname' abbreviation used to disambiguate. For example in the sample site "London" is interpreted as "London, ON, CA".
'preposition' override the default 'at'. In particular geographically large locations, such as states or countries, typically specify 'in'.
'notes' Rich text (HTML) notes.
'zoom' This is set to control the map display. This is an extension of the Legacy Family Tree implementation.
'boundary' A set of points defining the geographical boundary of the location as latitude, longitude pairs stored as a string. This is an extension of the Legacy Family Tree implementation. This may include multiple polygons or polylines. In that case the value of the field is an array of strings instead of a single string.
'Verified' Not used by this implementation but retained for compatibility with Legacy Family Tree.
'FSResolved' Not used by this implementation but retained for compatibility with Legacy Family Tree.
'VEResolved' Not used by this implementation but retained for compatibility with Legacy Family Tree.
'qsTag' Not used by this implementation but retained for compatibility with Legacy Family Tree.

Location

The location name should be expressed as a formal address uniquely identifying the location. Basically it should look like a surface mail postal address. However it should be recorded as the address would have been specified at the time of the events. Rural Route or Rural Free Delivery (RFD) route numbers may be used. The location name should not include postal codes, only introduced in most countries after 1950, and it should not reflect administrative reorganizations implemented since 1950. Postal codes and other recent amendments may be recorded in the notes about a location. For example under "195 St James St N, Stamford Centre, Stamford, Welland, ON, CA" one could note "Current address "3805 St James St, Niagara Falls, ON, CA L2J 2P9". In particular note the following recommendations:

  1. Include all relevant levels of the address hierarchy. In the United States of America and Canada, for example, a location may be expressed as street address, village, township, county, state or province, and country. However do not record post office box numbers or descriptive text that does not resolve to a location. For example do not include "House of John Smith" in the location portion of the event. Record that information in the descriptive comment of the event. If you identify, for example from a city directory, the actual address of the individual you can add that to the location.
  2. Lot numbers on streets should be recorded as they appear in the original records. Many municipalities massively renumbered lot numbers after 1950 with the intention of improving fire response. However for those municipalities this means that geolocation services will misinterpret the location.
  3. Be aware that a compass direction associated with a street may not be used to distinguish one part of a street from another, where lot numbers are reused on either side of a major road. Sometime they are short for "East Side" or "North Side". So check out the actual orientation of the street on Google Maps™.
  4. Rural addresses should be recorded as "lot number concession" to avoid creating duplicates. This is arbitrary since both orders are used in original documents. Putting the lot number first makes rural addresses more consistent with urban addresses where the lot number is first. The dynamic data validation for location names rearranges simple "lot 9 con 9" addresses but more complex patterns must be defined manually.
  5. Street names should be recorded as they appear in the original records. Municipal amalgamations since 1950 have caused many street names to change.
  6. Always include the country name, or two character ISO 3166 country code as the last element of an address. This avoids ambiguities. In particular many of the US Postal Service state abbreviations duplicate ISO 3166 country codes. You will save yourself trouble as you expand your research beyond your home country. Note that England, Scotland, Wales, Northern Ireland, and other component states of the United Kingdom, do not have ISO 3166 country codes but rather ISO-3166-2 sub-national identifiers. Also, for obvious reasons, there are no ISO 3166 country codes for countries that no longer exist, such as Prussia. A state like Prussia should be treated as it was between 1871 and 1945 as a component state of Germany. The area formerly occupied by the German state of Prussia is currently divided between the Kaliningrad Oblast of Russia and the Warmia-Masuria województwo of Poland.
  7. The state or province may be identified either by its full name or by its ISO 3166-2 code. For the USA this is the same as the USPS two-character code. For Canada it is the same as the Canada Post two-character code. For each country the Country Table management panel includes a button "States" that displays the interpretation of these codes.
  8. Use consistent abbreviation style. For example either always include the period after an abbreviation or always exclude it. For example consistently use addresses like "Central Ave, St Petersburg, FL, USA" or like "Central Ave., St. Petersburg, Florida, USA". In the demonstration database the period is omitted.
  9. To avoid duplicates either always include the apostrophe in a singular possessive or always omit it. In the demonstration database the apostrophe is omitted. For example "St Marys Anglican Church".

Geo-location services do not currently recognize traditional rural lot descriptions. The geographical location corresponding to such locations must be entered manually. Optionally you can define the boundaries of the lot. It is usually easy to see the actual boundaries of the lot in the satellite view of the location.

SortedLocation

The following are examples of how the field 'sortedlocation' is constructed in order to display locations in the intuitive order by lot number. Note that numeric lot numbers and concession numbers are padded to 2 digits for rural lots and to 4 digits for urban lots.

location sorted location
N ½ lot 7 1RN, Ekfrid, Middlesex, ON, CA 1RN, Ekfrid, Middlesex, ON, CA, lot 07N ½
lot 8 1RN, Ekfrid, Middlesex, ON, CA 1RN, Ekfrid, Middlesex, ON, CA, lot 08
lot 8 con 2, Ekfrid, Middlesex, ON, CA con 02, Ekfrid, Middlesex, ON, CA, lot 08
N ½ lot 10 1RN, Ekfrid, Middlesex, ON, CA 1RN, Ekfrid, Middlesex, ON, CA, lot 10N ½
39 King St, London, ON, CA King St, London, ON, CA, 0039
224 King St, London, ON, CA King St, London, ON, CA, 0224

Boundary

The boundary field contains:

  1. An optional JSON object containing instructions to Google Maps as to how to display the location as a line rather than an area. For example: {"strokeColor":"blue"} specifies to draw the location as a line in blue. At present only the strokeColor and strokeWeight attributes may be set, and the strokeOpacity is set to 0.5. If present this separated from the following specifications by a comma.
  2. Two or more latitude, longitude pairs. Each pair is enclosed in round brackets, and separated from the following pair by a comma. For example (42.903131,-78.907928),(42.935810,-78.912422), ...

Next: new Location($parms)