Getting Started with OpenLayers

OpenLayers is a pure JavaScript library for displaying map data in most modern web browsers, with no server-side dependencies. OpenLayers implements a (still-developing) JavaScript API for building rich web-based geographic applications, similar to the Google Maps and MSN Virtual Earth APIs, with one important difference -- OpenLayers is Free Software, developed for and by the Open Source software community.

Class Reference Documentation

Creating Your First Map

The OpenLayers API has two concepts which are important to understand in order to build your first map: 'Map', and 'Layer'. An OpenLayers Map stores information about the default projection, extents, units, and so on of the map. Inside the map, data is displayed via 'Layer's. A Layer is a data source -- information about how OpenLayers should request data and display it.

Crafting HTML

Building an OpenLayers viewer requires crafting HTML in which your viewer will be seen. OpenLayers supports putting a map inside of any block level element -- this means that it can be used to put a map in almost any HTML element on your page.

In addition to a single block level element, it is also required to include a script tag which includes the OpenLayers library to the page.

<html>
<head>
  <title>OpenLayers Example</title>
    <script
    src="http://openlayers.org/api/OpenLayers.js"></script>
    </head>
    <body>
      <div style="width:100%; height:100%" id="map"></div>
</body>
</html>
Ex. 1: Example of HTML for creating OpenLayers Map

Creating the Map Viewer

In order to create the viewer, you must first create a map. The OpenLayers.Map constructor requires one argument: This argument must either be an HTML Element, or the ID of an HTML element. This is the element in which the map will be placed.

var map = new OpenLayers.Map('map');
Ex. 2: Map Constructor

The next step to creating a viewer is to add a layer to the Map. OpenLayers supports many different data sources, from WMS to Yahoo! Maps to WorldWind. In this example, the WMS layer is used. The WMS layer is an example provided by MetaCarta.

var wms = new OpenLayers.Layer.WMS(
  "http://labs.metacarta.com/wms/vmap0", 
  {'layers':'basic'} );
map.addLayer(wms);
Ex. 3: Layer Constructor

The first parameter in this constructor is the URL of the WMS server. The second argument is an object containing the parameterss to be appended to the WMS request.

Finally, in order to display the map, you must set a center and zoom level. In order to zoom to fit the map into the window, you can use the zoomToMaxExtent function, which will zoom as close as possible while still fitting the full extents within the window.

Putting it All Together

The following code block puts all the pieces together to create an OpenLayers viewer.

<html>
<head>
  <title>OpenLayers Example</title>
    <script
    src="http://openlayers.org/api/OpenLayers.js"></script>
    </head>
    <body>
      <div style="width:100%; height:100%" id="map"></div>
      <script defer="defer" type="text/javascript">
        var map = new OpenLayers.Map('map');
        var wms = new OpenLayers.Layer.WMS( "OpenLayers WMS", 
            "http://labs.metacarta.com/wms/vmap0", {layers: 'basic'} );
        map.addLayer(wms);
        map.zoomToMaxExtent();
      </script>

</body>
</html>
Ex. 4: Full HTML and Javascript for simple WMS browser

Adding an Overlay WMS

WMS layers have the capability to be overlaid on top of other WMS layers in the same projection. There are several ways to mark a layer as an overlay, rather than a base layer. With WMS, the best way to do this is by setting the 'transparent' parameter to 'true'. The example here uses a political borders WMS to demonstrate overlaying a transparent WMS:

    var twms = new OpenLayers.Layer.WMS( "World Map", 
        "http://world.freemap.in/cgi-bin/mapserv?", 
        { map: '/www/freemap.in/world/map/factbooktrans.map', 
          transparent: 'true', layers: 'factbook', 
          format: 'png'} );
    map.addLayer(twms);
Ex. 5: How to add a transparent WMS overlay to your map.

Using Google Maps

In order to create a Google Map inside the OpenLayers interface, you must first include the Google Maps script tag for your domain: this allows you to specify your Google Maps API key.

  <script src="http://maps.google.com/maps?file=api&v=2&key=YourKey"
        type="text/javascript"></script>
Ex. 6: Example script URL for Google Maps

Once you have included your Google Maps script tag, you only need to add a new layer type to the map:

  var google = new OpenLayers.Layer.Google( "Google", { type: G_HYBRID_MAP } );
  map.addLayer(google);
Ex. 7 Creating a Hybrid Map, and adding it to the map

The default Google Map type is the road map. G_SATELLITE_MAP is also supported, in addition to G_HYBRID_MAP.