Creating and Editing EventMaps

Work on this project has been supported by the
NEH Digital Humanities Fellowship FX 50009 08
with additional support from Colgate University.


EventMap Applications

An EventMap application consists of a sequence of events located in space and time and annotated with web pages. (See the MAPs site for examples.) To create such an application, the following kinds of information are needed:

  1. The title of the application, its date of creation or last revision, the creator(s), and a description. The description will become a "greeting page" that will appear in the annotation space when the application is invoked.
  2. A list of events, each with a title, start date, end date (can be the same), location and its coordinates, and a description. Other attributes can be added, as explained below.
  3. Additional information on how the events are to be displayed on the map. The kinds of displays available are: points (markers), polylines, polygons, and overlays. Markers, polylines and polygons can be color-coded according to the values of some event attribute. For markers, the creators can contribute their own set of icons to be displayed on the map. For overlays, the creators must provide a set of images that will become "ground overlays" on the map.

All this information can be presented in a Google spreadsheet from which the application is automatically compiled. The spreadsheet can be created directly in the browser as a Google Spreadsheet, or as an MS Excel document to be imported into Google.

Creating an EventMap Application: Outline

The main steps in creating an EventMap application are as follows.

The rest of the work in preparing your EventMap is similar to authoring in the traditional scholarship sense: creating texts, possibly with images and multimedia, to express the content you wish to express.

The structure of the spreadsheet

The spreadsheet that defines an application must consist of one or more pairs of tables. The first such pair defines the basics of the application as specified in points 1 and 2 above. Additional pairs of table provide additional information. The first table in each pair has exactly two lines in it that provide metadata (attributes and their values) for the table that follows. We will call those two-row tables metatables. The first attribute of a metatable is id. It identifies this particular pair of tables .Tables are separated from each other by one or more blank lines.

Application Description and Event Descriptions

The most important table pair, and the only one that is required, is the first pair. Its metatable usually goes in rows A and B starting in column 1. Its first line lists the attributes of the entire application (as specified in item 1 above) and their data types. For instance, it may look like this:

id:text title:text date:text creator:text description:single
Unique ID Chronicles of Trivia 2008-03-17 Jane Doe; Joe Schmoe This sequence of maps shows the major battles of the War of the Trivial Succession; consult Trivia websites for more detail.



The Events Table

After a blank line, the second table defines events as specified in item 2 above. Its first line lists the attributes of events and their data types, with text as default. The lines that follow define events, one per line. For instance:

label title start end location lat:number lon:number description:single
FirstBattle First Battle 1245-10-22 1245-11-20 The Central Plateau 155.2 73.11 The First Battle lasted more than a month and resulted in a draw.
SecondBattle Second Battle 1247-11-04 1247-12-07 The Slippery Slope 149.5 73.22 The Second Battle effectively ended the war.


This example shows the minimal number of attributes. The label field must be a word or short phrase that is unique within the label column of this table. (The id of the previous table must be unique within the entire website.) If two labels are the same, the program will add a suffix to them to make them unique: FirstBattle_a, FirstBattle_b.


The start and end date fields follow the same conventions as the date in the first table. In this application there are two coordinate fields (lat and lon) because this application is about point events. The description field offers exactly the same options as the corresponding field in the first table.

Additional Attributes

Many applications have additional attributes. An eventType attribute is frequently useful for classifying, color-coding and filtering events so that only events of a specific type are displayed. See the MAPs site for examples of additional attributes.

Polylines, Polygons, and Overlays

If your application displays polylines or polygons for each event, you need to specify the geometry (polyline or polygon) in the metatable, and a sequence of points for each event. The convention for specifying a sequence of points is to create a single column called points for coordinates (not two columns, as in the example above); each cell in that column will contain a sequence of lat-lon pairs with spaces between the numbers within each pair and semicolons between pairs, e.g.,

34.2 73.5; 29.87 70.18; 30.99 75.6

If you have an "event" unfolding in discontinuous regions (polygons) then we have to consider it as a collection of simultaneous events described on separate lines of the spreadsheet.

For overlays, which are rectangular images that are superimposed on the map, you need four columns labeled North, East, South, West, to indicate where the image is placed.. You also need to provide a URL or local file reference for the image. Note that Google maps cannot handle overlays specified by four points (four pairs of coordinates) that do not form a rectangle.


Geocoding and Georeferencing

The process of finding coordinates for locations is called geocoding. The process of matching the corners of an overlay to specific points on the map is called georeferencing. Both kinds of data can be specified in the events table of the application or they can be placed in a separate table pair as the next section explains.

Other Table Pairs

Other table pairs follow the same metatable - table pattern. They provide additional information, such as icons to use for map markers or geodata information for place names. Several id's are reserved for common uses. Their names always begin with the underscore character, e.g., _icon. Here is an example of a geocoding table:

placeName lat lon
Kabul;Kabol 34.533 69.166
London 51°30'28"N 0°07'41"W



From Spreadsheet to EventMap

If the spreadsheet has been prepared in Excel, the first step is to import it into a Google spreadsheet.

The Google spreadsheet is processed by the Google2JSON program (see next section) that converts its content into the JavaScript Object Notation (JSON) format.

The JSON text is parsed by the EventMap program to create the EventMap application.

In the EventMap application, titles and descriptions will appear as a web page in the annotation space on the left. There is some default formatting applied to it that can be overridden by a stylesheet or explicit markup. Map-related elements of the spreadsheet will appear as Google map overlays (markers, polylines, polygons, ground overlays).

Google to JSON

In more precise detail, Google Spreadsheets can be published the way blogs are published, in the XML format called Atom. This is known as "an Atom feed." To create an ATOM feed for your spreadsheet proceed as follows:

At this point, you are ready to generate the URL for your ATOM feed. Click the Generate URL button, and select and copy the generated URL. Close the dialog window and proceed to the script sub-folder within your EventMap application folder. Click on Google2JSON.html. The page will show a blank text area and an input text box under it that says "Paste Spreadsheet Feed URL here or select from the list below." Paste the URL you have copied from the Google spreadsheet into the input box and click Submit Query. The textarea will contain the text for your config.js file. Click in the textarea, Select All, and Copy. Open a text editor (Notepad, Textpad, Wordpad, BBEdit), paste the contents of the text area and save as the config.js file in your EventMap application folder. Your application is ready to use.

If your spreadsheet is edited then you have to re-generate the config.js file. For that eventuality, you should save the URL of your spreadsheet's ATOM feed somewhere. The best way to do it may be to add it to the dropdown list on the Google2JSON page. Next time your spreadsheet is edited, open the page, select your spreadsheet and click Submit Query. As before, copy the contents of the textarea, and paste them into your config.js file, replacing its earlier content.

Technical Note

Google Spreadsheets have a programming interface that makes it possible to collect the data from the field and process it upon receipt by a function that is automatically invoked when the data arrives (a "callback function"). This centerpiece function converts Atom XML data into a structured text in the formal notation called JSON (JavaScript Object Notation). EventMap components, including the TimeMap and the annotations, work from this JSON text. It can be found in the file config.js in each application directory.

All EventMap code is free and open source.

Editing the Application

Google spreadsheets can be shared with other users, giving them rights to change the application. Two most common actions are: add an event (a row in the spreadsheet), or edit an event description. This can be done directly in the shared spreadsheet. We are working on a convenient user interface to submit data for entering into the spreadsheet.