Google Map module

From PGVWiki
(Redirected from Add Google maps)
Jump to navigation Jump to search

The Google Map module allows users to add maps to their family data.

Figure 1. A screen capture (Xenea theme) showing the "map" tab of an individual and the type of information available following the installation of the Google Map module and the addition of relevant information.

Note: This is quite separate from the map icons that can be displayed on individual pages. They are generated from specific LAT/LONG tags added to places in a GEDCOM file.

The module shows additional information for individuals – see Figure 1. There is an additional tab shown on the page for every individual, a map derived from Google Maps, and a table of the events being mapped on this page.

Each map marker may be clicked to show data attached to that particular place. If more than one event took place at the marker location, the additional events are shown with tabs.

Software

If you are using v4.0, you will need to download the software from the Files/Modules section at http://sourceforge.net/project/showfiles.php?group_id=55456 Be aware that the software is still under development, and that it may change from time to time. Notes will be posted in the Discussion forum when there are significant changes.

In v4.1 and later, the Googlemap module (in appropriate folders) is included in the full download. If you want to be aware of the most recent postings about this (or any other PhpGedView developments) visit the Subversion area at http://sourceforge.net/svn/?group_id=55456

When you download v4.0, you will get these files:

Figure 2. Some caption needed

The ‘extra’ folder should not be uploaded. The files in it are lists of places that you can import through the ‘Edit Place Locations’ feature.

Copy the googlemap.php and googlemap_readme.txt to your PGV ‘modules’ folder on your web site using FTP or whatever method you prefer, in my case it was >>> /public_html/yourdomainname/phpgedview/modules/

Copy the rest of the Google map files and folders (such as languages, places, and etc …) to >>> /public_html/yourdomainname/phpgedview/modules/googlemap/ (if googlemap folder does not exist create it then copy the contents over)

Set the attributes (chmod) of the ‘modules’ folder and its contents to ‘777’ 

Note: For early versions of PGV (4.1 and earlier) you MIGHT want to update the version of admin.php in the root directory .
Go to http://phpgedview.svn.sourceforge.net/viewvc/phpgedview/trunk/phpGedView/
and get a fresh copy, but ensuring it is no later than about March 2007..
Later versions include many other changes incompatible with early versions of PGV..
Upload this to replace the one already on your server..
The ONLY benefit of doing this is to gain one-click access to the Google Map Module config file from PGV's admin panel..
Without the change you can still access the file, but only from the Map tab of an individual who has valid map data. This change is NOT NECESSARY after PGV 4.1.

Special note for PGV3.3.8 users:  Go to the root directory of your PGV installation,
and rename ‘individual.php’ to ‘zindividual.php’ (or any different name).
Then copy ‘individual-3.3.8.php’ to ‘individual.php’ in its place

API (application programming interface) KEY

To enable a connection to Google Maps, you need to obtain a key from Google.

Go to http://www.google.com/apis/maps/signup.html. This is the Google map site, and you will need to become a Google member to go to the next step. So, sign on. Google are not aggressive phishers, and they will probably never bother you.

Once you have done that, you can log in. Google will ask you where your PhpGedView installation is, so type in www.xxxx.yyyy.zz/yourplace, altered to reflect your own URL. Select a point in your installed tree that would allow one key to be used for multiple instances (should you have more than one).

When you get your key, take a copy. In Windows, highlight it, then Ctrl+C - don’t try to copy it by typing – you will get it wrong! And, for security, open Notepad, paste in the key, and save the file for future reference. Mac and Linux users should also save a copy.

Starting the process

You can now open PhpGedView. Log in as Admin. While you are doing this, the Googlemap module will be creating a new table (‘placelocation’) in the database on your server. See the Technical Section below for details of its structure and contents.

The Administration menu will open, and down the bottom you will see the Googlemap configuration entry. Select ‘Manage Googlemap configuration’. If the configuration option does not appear, double check to make sure you have the ‘config.php’ file that you created.

Figure 3. Some caption needed

This opens a new window:

Figure 4. Some caption needed

Set Enable Googlemap to ‘Yes’ and paste in your API key. If your data is largely one-country-centric (eg all your data relates to England) then type ‘England’ in Default level value box. Save the configuration. You can revisit this and improve the specification as you get more experience.

At this point, log off from PhpGedView. Then log on again, and check that the page for each individual has a Map tab, although it will be greyed out. If not, go back to the beginning….but, as a first part of the recovery, copy the file defaultconfig.php to your server, and rename it to config.php (this will mean you have both config.php and defaultconfig.php in that folder). And also check the Googlemap configuration to make sure your key has not been ‘lost’ somehow.

Now go back to the top of the page and try again…

You are now ready to include map data in your file. Before you do, go back and reset the attributes (chmod) of the ‘modules’ folder to ‘644’.

For a more detailed explanation of what all the items mean, see the Technical Section below. 

Mac users with Safari might find that maps do not display, giving an error message that maps are
not available at this zoom level. The workaround is to reset your user preferences to "All"
instead of "Personal facts and details" This is in the GEDCOM configuration under
Display & Layout - Default tab to show on individual page.

Making the maps work…

This next stage can be somewhat involved, so some explanations are required.

Getting Location Data

Location data may be obtained in various ways.

Some well-known sources include:

You may need to inspect any data you acquire to verify that they fit one of the following conventions:

Co-ordinates

Traditionally, co-ordinates have been quotes in degrees, minutes (60 to the degree) and seconds (60 to the minute), and written as 33° 44’ 55”. You can enter these in most computer programs without the symbols – 33 44 55, or you can decimalize them to 33.7486 (in case you are wondering how, multiply minutes by 60, add the seconds, then divide the sum by 3600. Add the degrees).

Plus and minus: North and East are positive figures, South and West are negative – for example -23.456 144.666 equates to 23.456S 144.666E

Alpha: inclusion of N, S, E or W eg 23.456S 144.666E. The alphas can lead or trail.

Remember that latitudes can be no more than plus or minus 90 degrees, and longitudes no more than plus or minus 180 degrees.

There are various other ways of defining a place on the surface of the earth. You don’t to know any more than the information provided here to be able to locate a place with Googlemap.

Places

In this instance, place names are quoted in descending order of importance (in the geographical sense) and comma-separated. You only need to enter a specific place once in the edit place locations – the software will re-use it as often as required. Read the Technical Section to see how the Googlemap module handles place data.

Drill Down Locations

For a full explanation of the placename hierarchy, see the Technical Section. But here is an outline of how it works.

To give a locale for an event, it might be sufficient to quote a location such as England. The co-ordinates would then be sufficient to show a map like this:

Figure 5. Some caption needed

All you want to do is indicate the principal geographic descriptor that illustrates where an event took place. For this level of detail, you would select ‘country’ (see Fig. 7 below) when searching for the location.

The matching co-ordinates would be relatively ‘crude’ as W0.1 N51.5 and the zoom level 4. This will put the marker close to the middle of the UK land mass.

To move in closer, you would choose either ‘city’ or ‘neighbourhood’, zoom level 6 to 8 (to suit your taste!) and the co-ordinates would be more refined : W0.0603 and N51.525 would take you to the East End of London.

What do you provide?

The information in your home application probably needs some housekeeping, as there will possibly be variations in your data. The syntax is literal. Make up a ‘places’ file (most home-use applications do this for you) and check-read it for variations of any place. Correct duplications (or close-to-duplications) at this stage.

Remember that the ‘places’ are nested and ‘Bethnal Green’ will be in the ‘London’ ‘folder,’ and ‘London’ will be in the ‘England’ ‘folder.’ Also try to remember to be consistent. If you use place names such as ‘London’, ‘London, England’ and ‘London, Eng.’, you will end up with three different ‘places (or folders) for that one location.

Data from applications (TMG, Legacy, etc)

Newer versions of commercial genealogy applications try to include place location data, even though the GEDCOM standard does not specify how this is to be done. As a result (and you should check whatever application you use) you may not be able to use GEDCOM-generated co-ordinates directly from your applications.

A recent post (http://sourceforge.net/tracker/index.php?func=detail&aid=1527087&group_id=55456&atid=477081) showed a way to handle information from TMG.

Taking in External Data

  • Hand-edit the ‘placelocation’ table: For the very experienced among you. A table layout is shown in the Technical Section below
  • Use the PhpGedView software to add a place – see below
  • Make a comma-separated table by hand, or with an application like Excel, and import it (see the Technical Section for information about this)
  • If your home application stores place/co-ordinate data, check that it exports to one of the accepted forms noted above

Adding places one by one to your GEDCOM file (not recommended)

This method is included so that you may have an idea of how a GEDCOM stores place data. You do not need the Googlemap module to use this procedure.

Events can have places ‘attached’ to them, so you can add places to events by hand. This is tedious, and not recommended as a general approach. The process does not allow one place entry to be used by many individual events.

The co-ordinates for an event can only be added directly to a GEDCOM file. The correct way to do this is for a PLAC record:

2 PLAC <Placename>
3 MAP (Make sure you use the ‘3 MAP’ record after a PLAC record.)
4 LONG <Longitude>
4 LATI <Latitude>

The MAP, LONG and LATI lines should be added directly after the PLAC line.

In the ‘edit’ function pop-up window, there is a ‘+’ (plus sign) under ‘Place’ where you can select a country, state, county, and city that exists in your PhpGedview ‘place’ file. This can help avoid duplications by various spellings or versions of the same place. The PhpGedView configuration allows for ‘expanded’ editing if that option is selected.

This method places 4 icons in line with the event, wherever it is shown. These give you the option of using Mapquest, Google Maps, Multimap or Terraserver. You do not get a Map tab.

Add a place using PhpGedView Googlemap module (recommended method)

Forenote: the Google Map module is designed to work with locations in tree-like fashion. If we were to consider a suburb of London, the tree would take the order 'England, London, Hackney'. This is not how we enter place names in our family data, but it is how we manage the Google Map module. This will give access to useful place lookup features as we build up map information. It will help you find groups of people from the same locale. And it conforms to the GEDCOM specification, a feature of PhpGedView.

And, BEFORE you start with any mapping endeavours, review your data. Make sure spelling is consistent, there are no 'almost' duplicates, places are in their right country, and the places you describe are in true tree fashion. Only then will the module make it easy for you to connect family data with Google Maps.

This feature uses new database tables to store place text and location information. Existing places can be imported and location information can be added using graphic tools (zoom/click on map) or specific location data.

The location information is held outside the GEDCOM (and can be shared between GEDCOMs in PGV) and location data is entered only once for each place. Backup of location data is available by export of each new place database table to a text file (separated with ";"). Bulk additions can be performed by text file import (with reservations for specific place structure and spelling).

Using the tree structure mentioned above, we start to build location data from the top down – which, in 99% of cases, will mean starting by entering a country. When that is done, we move to the next layer (state, county, whatever is appropriate for your locale.)

Using your owner's rights, go to the Administrator menu and (down the bottom) click on "Edit geographic place locations". The top left of screen will now look like this:

Figure 6a. Some caption needed

The words "Top Level" tell you that this is the highest level in your tree. As you add levels, this line will expand and serve as a navigation means.

Click on 'Add place', and we will enter our top level, using England as the country.

Figure 6b. Some caption needed

This opens the mapping dialog, and we type 'England' in the type box, click 'Country' to give it a level, then click Search.

If you are connected to the internet, the mapping script will search a site named Geonames, where information on 2.2 million places is stored. If found, details will be filled in on the form for you. You can always visit the site yourself (http://www.geonames.org/) If in doubt about which place you really mean, you will be shown options. Select the appropriate one, and click on 'Use this value' The dialog becomes (note that the zoom level has been altered to give a better visual result):

Figure 6c. Some caption needed

You can save this. Now you will have an entry.

Figure 6d. Some caption needed

Note that the location, England, is clickable. And note the red X, which indicates that this location can be deleted without any problems.

Having clicked on England you go around the loop again…now you are working within England (see the line that indicates the level you are on?), which has no places to show.

Figure 6e

Now you want to enter London….so click on 'Add place' and go back to the top of this section.

The red X has been mentioned. As you add levels to the hierarchy, only the lowest level items will show the X. Places higher up the tree will not, because there are lower entries that depend on them. If you want to delete something using the X, you will have to begin down the tree and work up – delete suburb, then city, then state, then country would be the order of work.

Confused about the order of things, and how to show items in your data?

The top-down tree structure used here is not the way we actually enter data. We work from highest detail to the lowest – street address to suburb to city to….country. That could also be described as lowest to highest, in the social order of things. So the various concepts of data construction might not be clear, and could take a bit of getting used to. Don't change what you do with your family data, but the mapping model works in reverse to it.

Don't leave out levels. Different countries have different management structures using different terms, and these may not accord with the terms used in the Google Map module. So ignore them if they don't "fit" your needs – just start at the country level (no problem there) and work down one level at a time. This also applies if you build a file outside PhpGedView for eventual import.

Ignoring the tree structure

This may be contradictory, but you can ignore the tree structure if you wish.

You could enter your family data as Hackney London England – which your home application and PhpGedView will see as one place name, made of 3 words. That's not a problem – in the mapping module, just use the identical string, and one will find the other. But now you will need to figure out the co-ordinates for yourself. No data will be 'nested'.

And you will be restricted in how you can use geography to help work with your family data. For example, you couldn't figure out who lived in any suburb of London, or who lived in England. And, of course, there might be the confusion factor. If the string is just one long line, does everyone know what it means? Eg 66 St Martins St St Martins Someplace Somewhere is not very readable.

If everyone lives/lived in one country, why would you enter the name of the country? Is it a gimme? If you ignore the tree, you might make it easier for yourself. That's an individual decision for everyone to make.

Import from current (or all) GEDCOM(s)

These two options will populate the ‘placelocation’ table with all the places you already have in your GEDCOM file. BUT – it will not have LAT / LONG coordinates for them You still need to edit each place to add that information. See ‘You can edit and delete stuff…’ below.

Import from file

This option allows you to import place data, including all necessary fields for the ‘placelocation’ table, from pre-prepared text files. You can either create your own, or use the ones provided in the ‘modules/googlemap/extra’ folder. If you have a lot of places from the countries available as text files it is the fastest and easiest way to populate the maps.

However – you will need to check that your PLAC tags, in your GEDCOM file EXACTLY match the places included in these files, in respect of spelling and hierarchy – meaning, do you have every town in the right county and / or state?

You can edit and delete stuff…..

This is self-explanatory. Click on ‘Edit’ and you will get a window like Figure 8. Fix what needs to be fixed, then Save.

The red X is for delete. If the X is grey (or there is no X), it indicates that this entry has subordinate entries. If you plan to clear the topmost entry, you need to clear the lower entries first. Read the Technical Section below if you want to know more on this.

Figure 8. Some caption needed

Technical Section

Place data for the GoogleMaps module is stored in its own table, separate from the normal PGV places table. It has this structure:

Table 1: placelocation
Field Def Desc
pl_id int(11) Incremented index
pl_parent_id int(11) Ref to higher level ‘parent’
pl_level int(11) Place in descriptor ‘tree’
pl_place varchar(255) The place
pl_long varchar(30) Longitude
pl_lati varchar(30) Latitude
pl_zoom int(4) Googlemap zoom
pl_icon varchar(255) Omit for standard icon

The data is stored in a separate table so that it can be used by multiple GEDCOMs. Also when you clear a GEDCOM the location data is kept and will be used when you import your GEDCOM again.

Places

In practice, all ‘places’ are defined as descriptors, an ordered way of telling how to find a location that has a name. A descriptor takes the form ‘MyCountry; MyState; MyCounty; My City; MyPlace’ These are identified by their equivalent ‘level’:

Country = level 0
State = level 1
County = level 2
City = level 3
Place = level 4

When searching for a place name in the table, the application ‘drills down’ as detailed in the descriptor, taking items in sequence until they reach the desired ‘level’ for the intended use. Note that items are separated with ";"

When you set up a definition for a place, you specify it in the same way. To point to the place you really want to reference, you add ‘level’ to the mix. So now your descriptor looks like:
‘Level; MyCountry; MyState; MyCounty; MyCity; MyPlace’.

The level points to the item from the descriptor that you want to use. In this example, MyCountry would be level 0, MyPlace would be level 4.

The longitude, latitude, zoom and icon variables are simply added on the end.

The final location descriptor would have this appearance:
‘Level; MyCountry; MyState; MyCounty; MyCity; MyPlace; MyLongitude; MyLatitude; MyZoom; MyIcon’

You can omit any part of the location descriptor, but not the ‘,’ that separates the items. You have to work backwards from the end of the place sequence, so you could have (leaving out MyPlace):
‘Level; MyCountry; MyState; MyCounty; MyCity;; MyLongitude; My Latitude; My Zoom; My Icon’

The corollary to this is that you need to consider the sequence of places when you import data for any source. You need to build from the start of the place sequence, so you would have, in order:
‘Level; MyCountry;;;; MyLongitude; MyLatitude; MyZoom; MyIcon’
‘Level; MyCountry; MyState;;; MyLongitude; MyLatitude; MyZoom; MyIcon’
‘Level; MyCountry; MyState; MyCounty;; MyLongitude; MyLatitude; MyZoom; MyIcon’
…and so on

The ‘placelocation’ table stores place records in 8 fields, designed to store each place name only once, with a cross-reference to its parent (next higher level) stored in the pl_parent_id field. The pl_id which this cross reference relates to is an automatically generated sequential index number.

A typical structure, stored in this table, might therefore be: [Note – some columns have been ignored for display purposes only]

pl_id pl_parent_id pl_level pl_place pl_long pl_lati
1 0 0 USA W100.00 N39.00
6 1 1 California W119.300 N36.000
7 6 2 Los Angeles W118.230 N34.05
8 7 3 Beverley Hills W118.400 N34.07
25 8 4 135 Copley Place W118.4224 N34.0767

Note that there are 9 fields in the descriptor. This is fixed, and if you plan to build a file to import, make sure that you have 9 fields in every line, and that you use ";" to separate data items.

Googlemap configuration – what the items mean

Refer to Figure 4

The first entry simply turns the Googlemap feature on or off.

The second entry is the Googlemap API key.

The third entry is the type of display – plain map, Satellite, or a combination (hybrid) of these two.

The fourth item sets the size of the map when it is displayed on screen. The default (600 by 400 pixels) can be adjusted to suit your needs.

The fifth item is the zoom level. Level 0 is country (low detail), the maximum is high detail. Note that at high level, some satellite data is not available.

Precision: this sets the number of decimal places to be used. A country probably needs one decimal point, a town or city 3. The third decimal place moves the pointer in increments of about 110m accuracy. The 6th decimal place is about 0.1m (4 inch) accuracy.

Retrieved from "https://wiki.phpgedview.net/en/index.php?title=Google_Map_module&oldid=11952"