root/branches/workshop/FOSS4G2008/Docs/04_openstreetmap.chapter

= About OpenStreetMap =

"OpenStreetMap is a project aimed squarely at creating and providing free 
geographic data such as street maps to anyone who wants them." 
"The project was started because most maps you think of as free actually have 
legal or technical restrictions on their use, holding back people from using 
them in creative, productive or unexpected ways." 
[Source: http://wiki.openstreetmap.org/index.php/Press]

OpenStreetMap uses a topological data structure:

 * Nodes are points with a geographic position.
 * Ways are lists of nodes, representing a polyline or polygon.
 * Relations are groups of nodes, ways and other relations which can be assigned certain properties.
 * Tags can be applied to nodes, ways or relations and consist of name=value pairs.
 
This is how nodes, ways and relations are described in the OpenStreetmap XML
file:

{{{           
<?xml version='1.0' encoding='UTF-8'?>
<osm version='0.5' generator='JOSM'>
  ...
  <node id='252791067' timestamp='2008-03-18T19:45:06+00:00' user='Russell Cloran' visible='true' lat='-33.9291602' lon='18.4251865'>
    <tag k='created_by' v='JOSM' />
  </node>
  <node id='252791066' timestamp='2008-03-18T19:45:05+00:00' user='Russell Cloran' visible='true' lat='-33.9305174' lon='18.4265772'>
    <tag k='created_by' v='JOSM' />
  </node>
  <node id='252791065' timestamp='2008-03-18T19:45:04+00:00' user='Russell Cloran' visible='true' lat='-33.930418' lon='18.4231201'>
    <tag k='created_by' v='JOSM' />
  </node>
  ...
  <node id='260366643' timestamp='2008-04-28T10:59:11+01:00' user='Adrian Frith' visible='true' lat='-33.9287313' lon='18.415251'>
    <tag k='created_by' v='JOSM' />
    <tag k='name' v='South African Museum' />
    <tag k='tourism' v='museum' />
  </node>
  ...
  <way id='26358722' timestamp='2008-08-17T15:41:55+01:00' user='Adrian Frith' visible='true'>
    <nd ref='288787699' />
    <nd ref='288787695' />
    <tag k='highway' v='residential' />
    <tag k='name' v='Guinea Fowl Crescent' />
  </way>
  <way id='26358723' timestamp='2008-08-17T15:41:56+01:00' user='Adrian Frith' visible='true'>
    <nd ref='288787696' />
    <nd ref='288787723' />
    <nd ref='288787724' />
    <nd ref='288787728' />
    <nd ref='288787725' />
    <nd ref='288787677' />
    <tag k='highway' v='residential' />
    <tag k='name' v='Old Farm Road' />
  </way>
  ...
  <relation id='27924' timestamp='2008-08-17T09:53:48+01:00' user='Adrian Frith' visible='true'>
    <member type='way' ref='4994378' role='outer' />
    <member type='way' ref='5022484' role='innner' />
    <tag k='type' v='multipolygon' />
  </relation>
  <relation id='22713' timestamp='2008-07-27T22:49:25+01:00' user='Adrian Frith' visible='true'>
    <member type='way' ref='25817796' role='outer' />
    <member type='way' ref='25817797' role='inner' />
    <tag k='type' v='multipolygon' />
  </relation>
  ...
</osm>
}}}

The OSM data can be downloaded from OpenStreetMap website using an API 
(see http://wiki.openstreetmap.org/index.php/OSM_Protocol_Version_0.5),
or with some other OSM tools, for example JOSM editor.

Note: The API has a download size limitation, which can make it a bit
inconvenient to download extensive areas with many features.

When using the osm2pgrouting converter (see later), we take only nodes and ways 
of types and classes specified in "mapconfig.xml" file to be converted to 
pgRouting table format:

{{{
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <type name="highway" id="1">
    <class name="motorway" id="101" />
    <class name="motorway_link" id="102" />
    <class name="motorway_junction" id="103" />
    ...
    <class name="road" id="100" />
  </type>    
  <type name="junction" id="4">
    <class name="roundabout" id="401" />
  </type>  
</configuration>  
}}}

Detailed description of all possible types and classes can be found here:
http://wiki.openstreetmap.org/index.php/Map_features.

For Cape Town the OpenStreetMap data is very comprehensive with many details.
A compilation of the greater Cape Town area created with JOSM is available as
capetown_20080829.osm.