This is the first installment of a two part article by Chris Duncan about the Plug & Play Maps web service. The second part will be published on Wednesday 17th.

Plug & Play Maps is a free web service that lets you embed interactive thematic maps in your web pages with a single line of code that indicates the data you want to map and the way you want to display it. The service offers a number of automatic features and defaults that deliver highly informative, interactive, and intuitive maps to your web visitors with a minimum of effort and configuration on your part. This two part article will show you how to use the service to create a simple thematic map on your web page, and explores some of the many options for tailoring your map and data display.

A thematic map goes beyond just showing where things are – it shows how something varies from place to place by using symbols that change color, size, shape, or transparency to reflect the variations. Thematic maps let your data tell a story in an intuitive, visually engaging way – for examples and ideas, explore the gallery of live Plug & Play Maps, or do a search for thematic maps on the web.

Plug & Play Maps builds thematic maps on top of Google Maps by using data values you provide (in a file or a list) and mapping them with icons, charts, lines, or polygon areas that can vary in color or weight according to your instructions; it also creates a legend item for each data layer that shows how the layer's features are displayed, lets you turn the data layer on and off, and lets you zoom to the whole feature set. Typically, your instructions are just a short statement indicating the data you want to map and how you want to display it. For example, dropping the following line into your web page will automatically create a map showing the recent swine flu epidemic cases on a state-by-state basis using colored polygons:

ERROR [include_code_listing plugin]: File Not Found (/usr/www/users/winwaed/geowebguru/img/2009/pnp_script1.html)

Here is an image of the resulting Plug & Play Maps control:

 (see this map live)

This simple example shows all the essential elements^* for creating an embedded thematic map in your web page: the plugandplaymaps.com web service, the data you want to map (in this case, in a file), and your instructions for how to display the data and legend. In the following sections, we take a closer look at each of these elements and how they work together to create the map (if you are impatient to create your own map, you can get started with the Plug & Play Maps interactive Designer, which lets you pick mapping options from a form to generate a map and the corresponding script tag to copy and paste into your web page).

^* Actually, there is one additional required element: a Google Maps script tag with a keycode to enable Google Maps on your website; if you don't already have one, you can get your keycode and Google Maps script here to copy and paste into your web pages, either in the head section or just above the Plug & Play Maps script tag.

The Plug & Play Maps Web Service

In simplest terms, the Plug and Play Maps web service (the http://www.plugandplaymaps.com/js/ part of the script) is a Javascript generator – it creates the Javascript code required for a browser to create the map element, fill it with a Google Map, initialize the map, add the data symbols, and build the map legend. In other words, it's like hiring a web developer to write a piece of custom code that calls the Google Maps API (application programming interface) to add the map and data, plus all the work involved in scaling your data properly and building the legend.

Unlike hiring a programmer, however, using Plug & Play Maps is free, and even better, the program it "writes" stays up to date with any changes you make to your data or to the way you ask for the map to be drawn. Every time someone visits your web page, your current data file is read and rendered as a new, up-to-date map. If you want to change the way the data are displayed, add another data layer, or make other changes to your map, just change your Plug & Play Maps script tag and the new map is programmed automatically for all subsequent visits to your site.

The Data for Your Map

Plug & Play Maps lets you focus on the thing you know best – the data you want to map. The service can work with data in a wide variety of formats, so you probably already have something sitting on your computer that's ready to go. Or perhaps you want to map someone else's data – the web is full of data in a variety of formats, and if you find something you like you can include it in your map. Data formats currently supported include:

• CSV (comma-separated values – a common text format for spreadsheet data)
• KML (keyhole markup language – a common XML format for Google Earth data)
• DBF (database file – a common format for database and spreadsheet tables)
• SHP (shapefile – a common format for mapping with a Geographic Information System)
• JSON (Javascript Object Notation – a common text format for data interchange)

Plug & Play Maps needs to be able to see the data in order to generate the mapping code. This means that the data must be available over the web. If your data are in a file in any of the above formats, then the file must be available from a publicly accessible web address (such as the http://www.gismatters.com/ppm/swineflu.csv in the example above). You tell Plug & Play Maps the address of your datafile, and it reads that file to generate the Javascript that creates the map.

Aside: You can also send the data directly within the Plug & Play Maps script tag in your web page using the JSON format. This approach has some advantages (gives maximum control over your map, and is easier to generate dynamically if you create your web pages from a database) and some disadvantages (the data has to make an extra trip so the performance may suffer, and if you have a large volume of data it may be truncated due to script URL length limits imposed by web servers and routers). For this article we only discuss file-based data – see the Plug & Play Maps How To page for more information on passing JSON data directly in the script.

Whatever the format of your data, Plug & Play Maps needs to be able to figure out where to put the features on the map – in other words, to determine the feature latitude and longitude coordinates required to position something on a Google Map. How this happens depends on the file or data format. For KML and SHP files, the location information is already embedded in the file, so there's nothing more to consider. For CSV, DBF, or JSON data, if you don't explicitly tell it what data item name to use for locating features, Plug & Play Maps will look for some common item names and use them automatically when it finds one. These automatically-recognized names include:

• "lat" and "lon" (or "lng" or "long") – two data items giving the location of each feature
• "latitude" and "longitude" – same as above
• "latlon" or "latlng" – a single data item giving the lat, lon values separated by a comma
• "coord" or "coordinate" – same as above
• "latlons" or "latlngs" – for lines and polygons, a series of latlons separated by a bar "|"
• "coords" or "coordinates" – same as above
• "encoded" – line or polygon coords that have been pre-encoded for Google Maps
• "address" – a full or partial street address
• "ST" – 2-letter state codes for the 50 states and the District of Columbia
• "CCISO" or "CCFIPS" – 2-letter ISO 3166-1 country codes or FIPS country codes

If your feature coordinates are in a column or field with a different name, you can either rename it according to the list above, or you can tell Plug & Play Maps in the script tag what the item name is, for example: &latlngitem=Location, or &latitem=Y&lonitem=X, or &addressitem=Street.

There's more to discuss on this topic, but before we go any further, let's take a look at a specific example. Let's look at the file used to create the map of swine flu cases at the top of this article. That map pointed to a CSV file located on the GISmatters web server, and you can open or download that file on the web if you like. Here are the first few lines of the file:

ERROR [include_code_listing plugin]: File Not Found (/usr/www/users/winwaed/geowebguru/img/2009/pnp_sample.csv)

A CSV file is just a table, often exported from a spreadsheet program like Excel, in which each row of the table appears as one line in the file, and each column of the table is separated from the others by a comma (if the information for a particular row and column contains a comma, then it should be enclosed in quotes, e.g., "100 Main St, Amherst, MA" for a street address column). For Plug & Play Maps to interpret the data, the first line has to provide the column names. In this case, the second column is named ST, so it will be used to automatically map the data values to state points or outlines, using state and country location data built in to Plug & Play Maps.

If you want to map by street address, there are several things to consider: First, the addresses will be converted to latitude, longitude coordinates by calling Google's geocoding service. This process can be time-consuming, so the data on your map may not load very quickly, which may frustrate your visitors. Second, because of the way the geocoding service gets called and returns results, sometimes data are lost in transit and never appear on the map. Third, the geocoder may not be able to successfully locate one or more addresses, or it may locate them incorrectly, so your map display may be incomplete or inaccurate. If you want your map to render quickly and reliably and you plan to use addresses, it may be better to convert them before-hand to latitude, longitude coordinates using a geocoding service such as Batch Geocode. Note that you can enter a partial address, such as  a City, State combination or a Zip code, and get back a mid-point coordinate that can be used to position a marker, so this approach can be used to make thematic maps by city or zip code.

In the second part of this article, Chris Duncan will show you how to control the actual data display to produce visually engaging maps.

About Dr Chris Duncan