Nicholas Skinner

After obtaining the map data the next step is to actually use it via a JavaScript library providing standard features such as lines, markers and click/drag functionality as offered by Google Maps.

There are currently 3 main ways to use OpenStreetMap data:

1. Google Maps API - However this would introduce licensing issues which were likely the reason OpenStreetMap data was chosen in the first place.
2. OpenLayers - An open source Google Maps type API.
3. OpenLayers via Mapstraction - The advantage of Mapstraction is that you write code once, and can then easily switch it between one of 9 major mapping providers including Microsoft, Yahoo, Google, MultiMap.

In theory using Mapstraction is an obvious choice leading to a much more portable application. In practise however things are not so simple. I found myself frequently viewing the Mapstraction JavaScript code to find undocumented functions (use of which is not recommended by the documentation). Also unless your application is very simple “if” statement will be needed in various parts of your code that call the Map APIs directly where Mapstraction does not provide the required functionality.

Even with undocumented functions, and “if” statements in the code supporting 3 mapping providers in places I found it necessary to go a step further and actually override Mapstraction functions where it was simply not possible to do what was required otherwise. I am now experiencing an issue whereby markers placed on the map move when changing zoom levels which I have not yet found a solution for. Same code works fine when switched to Google or Multimap. Therefore unless you have a very simple application or you really know what you are doing with JavaScript, and think the benefits of Mapstraction outweigh the extra time spent coding for it, simply using OpenLayers directly may be the best choice.

Using OpenLayers with OpenStreetMap

The process for using OpenLayers is relatively straight forward however involves a number of steps.

1. Download OpenLayers
2. Copy the OpenLayers “build/OpenLayers.js”, and “theme/”, “img/” directories to your webserver, putting them in the same directory (also be sure not to rename OpenLayers.js / change the letter case on the filename or it will not run correctly).
3. Copy the OpenStreetMap JavaScript file to your webserver.
4. Copy the OpenStreetMap HTML example script found on the Wiki to your webserver.
5. Edit the HTML example script such that the paths to the “OpenLayers.js” and “OpenStreetMap.js” JavaScript files point to your local copies.
6. Edit the “OpenStreetMap.js” JavaScript file changing the tile location to be the path where you uploaded your map files to.

Or download a zip file with the above already completed, you just need to the edit the tile location path in “OpenStreetMap.js”.

Then see the OpenLayers documentation and Examples for details on adding markers lines etc to the map.

Also see Part 1: Obtaining mapping Data.

OpenStreetMap is a community mapping project that allows you to upload then later use mapping data in a number of ways. One of their main benefits is providing maps free of the legal / technical limitations present on other services. Google Maps free edition for example can only be used when you provide a service which is “freely accessible to end users“.

The main issue with using OpenStreetMap however is map coverage, since they rely on user submitted data, maps may not be available for your area, however since starting in 2004 they now have good coverage in a number of areas, especially popular tows, and cities.

To make use of OpenStreetMap data in a way similar to the Google API (i.e. such that lines / markers can be displayed on it, and the user can click/drag the map around on screen) two main components are required, the mapping image data itself (i.e. the individual png files making up the area mapping data is required for), and the JavaScript API used to create the interface. It is also possible to just use data from the OpenStreetMap site directly however this would primarily only be suitable for low volume non mission critical applications.

.osm files

The map image data is supplied in the form of .osm files (containing XML describing the map features). There are two main types of file, the large “Planet” file containing all the mapping data OpenStreetMap currently has available for the entire planet (supplied directly by OpenStreetMap), and smaller “Extracts” files provided by contributors each containing only certain areas (i.e. Countries, or parts of countries). Additionally custom .osm files can be generated by using the Java OpenStreetMap Editor tool (”File” > “Download from OSM” then “File” > “Save as” options) however the total size is limited,

Converting .osm files to .png files

To convert the XML .osm files into .png image files that can be displayed by the web browser a rendering tool is required. There are two main tools available: Kosmos which runs on Windows and Mapnik that runs on a number of platforms, they are both very different in terms of what they can do and how easy they are to use.

Kosmos is fairly straight forward to install / use and has both a GUI and command line version available. It comes with a sample .osm file containing the Isle of White. To render the sample it is just of case of using the command line: Kosmos.Console.exe tilegen “..\Samples\Isle of Wight\Isle of Wight.kpr”. To render your own osm files edit the sample .kpr file removing configuration lines that are not required, and changing the location to the .osm file. [Download Example]

Kosmos may occasionally crash while starting up, this is generally due to someone editing the “Kosmos General Purpose Rules” page on the Wiki and failing to correctly test it (Kosmos downloads a copy of this file each time it runs). To stop this from happening, download your own copy of the raw rules file upload it to your web server, and change the “WikiPage” variable in the .kpr file. Kosmost however has a drawback in that it processes .osm files by first reading them into memory, therefore it is limited in the total size of .osm file it can process. For anything but small areas, another tool such as Mapnik is required.

Using Mapnik requires a non trivial setup procedure, for documentation on setting up and using Mapnik see the Mapnik OpenStreetMap Wiki page. As of yet I have not had any success setting this up on two different virtual machines running different OSs for which the Wiki provides setup instructions. My next attempt will involve the Fedors packages / instructions from Passback Mapping.

Also see Part 2: Making use of map data.

Google used to provide a SOAP based API that allowed programmatic access to Google search results. It has since been discontinued, however those that obtained keys prior to December 2006 can still use them.

If you need programmatic access to Google search results, and do not have a SOAP API key it is still available, just under the somewhat misleading title of “Google AJAX Search API”, and in a different format (JSON rather than SOAP/XML).

Google even provide code snippets for accessing it in Flash, Java, and PHP. For details see Google AJAX Search - Non-Javascript Environments.