Frederik Ramm Jochen Topf and Steve Chilton

OpenStreetMap Using and Enhancing the Free of

T A B L E O F C O N T E N T S Published in 2011 by UIT Cambridge Ltd. PO Box 145 Cambridge CB4 1GQ Tel: +44 1223 302 041 Web: www.uit.co.uk

ISBN 978-1-906860-11-0

Copyright © 2011 UIT Cambridge Ltd. All rights reserved.*

The right of Steve Chilton, Frederik Ramm, and Jochen Topf to be identified as the authors of this work have been asserted by them in accordance with the Copyright, Designs and Patents Act 1988.

The programs and instructions in this book have been included for their instructional value. Neither the publisher nor the authors offer any warranties or representations in respect of their fitness for a particular purpose, nor do they accept any liability for any loss or damage arising from their use.

The publication is designed to provide accurate and authoritative information in regard to the subject matter covered. Neither the publisher nor the authors make any representation, express or implied, with regard to the accuracy of information contained in this book, nor do they accept any legal responsibility or liability for any errors or omissions that may be made. This work is supplied with the understanding that UIT Cambridge Ltd and its authors are supplying information, but are not attempting to render engineering or other professional services. If such services are required, the assistance of an appropriate professional should be sought.

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. UIT Cambridge Ltd acknowledges trademarks as the property of their respective owners.

10 9 8 7 6 5 4 3 2 1

* Exception: All in this book are works derived from OpenStreetMap data. They are © OpenStreetMap contributors, and published under the Attribution-Share Alike 2.0 license: http://creativecommons.org/licenses/by-sa/2.0/ Table of Contents

Part I: Introduction 1 Making the Free ...... 3 1.1 The of ...... 4 1.2 Free is more than Free of Charge...... 4 1.3 Bitmaps, Vector Data, Geodata...... 5 1.4 OpenStreetMap and Geographic Information Systems...... 6 2 OpenStreetMap on the Web...... 9 2.1 The OpenStreetMap Web Site...... 9 2.2 OpenStreetBugs...... 12 2.3 OpenRouteService and YourNavigation...... 13 2.4 The Best of OSM...... 15 2.5 National and Regional Resources...... 16 3 The OpenStreetMap Community...... 19 3.1 Your OpenStreetMap Account...... 19 3.2 Mailing Lists and Forums...... 22 3.3 Keeping Track – Trac and Subversion...... 22 3.4 The OpenStreetMap Chat on IRC...... 23 3.5 Mapping Parties...... 23 3.6 Meetings and Conferences...... 24 3.7 The OpenStreetMap Foundation and its Local Chapters...... 24

Part II: OpenStreetMap for Contributors 4 On the Road with Your GPS Device...... 27 4.1 The Global Positioning System...... 27 4.2 The GPS Signal...... 28 4.3 Satellite Visibility and Positional Fix...... 28 4.4 Differential GPS...... 29 4.5 Is GPS Accurate Enough?...... 30 4.6 GPS Receiver Designs...... 31 4.7 Choosing a GPS for OSM...... 32 4.8 Types of GPS Data...... 34

VII Table of Contents

4.9 GPS Data Formats...... 35 4.10 GPSBabel...... 36 4.11 Handling the GPS Unit...... 37 5 Mapping Practice...... 39 5.1 A Typical Mapping Example...... 39 5.2 Notes and Recordings...... 46 5.3 Working with the Map...... 47 5.4 Working with Aerial Imagery...... 49 5.5 More Mapping Tips...... 50 6 The Data Model...... 51 6.1 Basic Object Types...... 51 6.2 The OSM XML Format...... 56 6.3 Modeling Areas...... 57 6.4 Tracks and Trackpoints...... 57 6.5 History of the OSM Data Model...... 58 6.6 Future Development...... 59 7 Map Features – What We Map...... 61 7.1 Roads and Railways...... 64 7.2 Forests, Lakes, and Rivers...... 72 7.3 Coastline and Islands...... 73 7.4 Buildings and Land Use Areas...... 74 7.5 Villages, Cities, and Borders...... 76 7.6 Other Points of Interest...... 76 7.7 Annotations and Missing Information...... 77 7.8 Links...... 78 7.9 Data Sources...... 78 7.10 A Practical Example...... 79 7.11 Tagging Priorities...... 81 8 Advanced Map Features...... 83 8.1 Complex Polygons...... 83 8.2 Boundaries and Land Area...... 85 8.3 Addresses and House Numbers...... 86 8.4 Routes...... 88 8.5 Public Transport...... 89 8.6 Turn Restrictions...... 92 8.7 Life Cycle Concepts, History, and Construction ...... 93 8.8 Ways Parallel to Roads...... 95 8.9 Other Kinds of Relations...... 96 8.10 Who Else Maps, and How?...... 97

VIII Table of Contents

9 Potlatch, the Online Flash Editor...... 99 9.1 First Steps...... 99 9.2 Editing Tags...... 102 9.3 Creating Nodes and Ways...... 103 9.4 Editing Nodes and Ways...... 105 9.5 Saving Changes...... 105 9.6 Reverting Changes...... 106 9.7 Relations in Potlatch...... 106 9.8 Working with GPS Tracks...... 107 9.9 Background Images...... 108 9.10 Additional Functionality ...... 108 9.11 Upcoming – Potlatch 2...... 108 10 JOSM, the Offline Java Editor...... 109 10.1 Installing and Running JOSM...... 110 10.2 Loading Local Files into JOSM...... 111 10.3 Loading Data from the OSM Server...... 117 10.4 Editing the Map...... 120 10.5 Uploading Changes to the OSM Server...... 127 10.6 Saving Changes to a File...... 131 10.7 Creating and Modifying Relations...... 132 10.8 JOSM Plugins...... 135 11 Other Editors...... 139 11.1 Merkaartor...... 139 11.2 Mapzen...... 145 11.3 Vespucci...... 146 11.4 Mapzen POI Collector...... 148 11.5 Osm2go...... 149 12 Tools for Mappers...... 151 12.1 Data Layer and Data Browser...... 151 12.2 OSM Inspector...... 152 12.3 ITO OSM Mapper...... 154 12.4 Further Tools...... 155 13 License Issues when Mapping...... 157 13.1 What Data can be Used?...... 157 13.2 Copying from Other Maps...... 158 13.3 Satellite and Aerial Imagery...... 159 13.4 Importing Data...... 160 13.5 A Change in the License?...... 160

IX Table of Contents

Part III: Making and Using Maps 14 Using OpenStreetMap on Web Pages...... 163 14.1 Anatomy of a Web Map...... 163 14.2 The Tile Server...... 166 14.3 The Tiles@Home Project...... 168 14.4 Using OSM with Maps...... 171 14.5 Using OSM with OpenLayers...... 173 14.6 CloudMade Maps...... 175 15 Accessing OSM Data...... 177 15.1 Downloading Data from the OSM API...... 178 15.2 Downloading Data Using Planet Dumps...... 179 16 Making Maps with Osmarender...... 181 16.1 Scalable Vector Graphics...... 181 16.2 Osmarender and XSLT...... 182 16.3 Running Osmarender...... 184 16.4 An Introduction to the Rules File...... 185 16.5 The Rules File in Detail...... 188 16.6 Writing Your Own Map Styles...... 195 16.7 Special Osmarender Tags...... 201 16.8 Drawing Bézier Curves...... 201 17 Drawing Maps with Mapnik...... 203 17.1 Installing PostgreSQL and PostGIS...... 204 17.2 Importing OSM Data into the PostGIS Database...... 205 17.3 Projections...... 206 17.4 Slim Mode and Updates...... 207 17.5 Installing Mapnik...... 207 17.6 Anatomy of a Map Style File...... 208 17.7 Your First Mapnik OSM Map...... 210 17.8 Making Standard OpenStreetMap Maps With Mapnik...... 213 17.9 Performance Considerations in Map Style Files...... 216 17.10 Cascadenik...... 218 18 Making Maps With Kosmos...... 219 18.1 Installation...... 219 18.2 Starting Kosmos and Loading Data...... 219 18.3 Choosing a Map Style...... 221 18.4 Defining Your Own Map Styles...... 222 18.5 The Kosmos Tile Server...... 222 18.6 Printing and Exporting Bitmaps with Kosmos...... 224 18.7 Maperitive...... 224

X Table of Contents

19 Navigation and Mobile Use...... 225 19.1 Basics...... 225 19.2 Pre-Processing OSM Data for Routing...... 226 19.3 Garmin GPS Units...... 227 19.4 Web-based Route Planning...... 230 19.5 Offmaps (iPhone)...... 231 19.6 Roadee (iPhone)...... 231 19.7 Skobbler (iPhone)...... 231 19.8 GpsMid (J2ME)...... 231 19.9 AndNav2 (Android)...... 231 19.10 ...... 232 19.11 Traveling Salesman...... 232 19.12 pgRouting...... 233 19.13 Gosmore...... 233 20 License Issues When Using Data...... 235 20.1 Who is the Owner of OpenStreetMap Data?...... 235 20.2 Collective Works and Derived Works...... 236 20.3 Do I Have to Publish?...... 237 20.4 Can I Sell OpenStreetMap Data?...... 238 20.5 What Happens if I Disregard the License?...... 238 20.6 Is the License Legally Binding?...... 238 20.7 The Open Database License...... 239

Part IV: Hacking OpenStreetMap 21 Writing Software for OSM...... 243 21.1 Working with Large Amounts of Data...... 243 21.2 Finding Your Way through the Subversion Repository...... 244 22 The OpenStreetMap API...... 247 22.1 Creating, Retrieving, Updating, and Deleting Objects...... 248 22.2 Creating or Modifying Multiple Objects at once...... 250 22.3 Requesting all Objects in an Area...... 251 22.4 Other Methods of Access...... 252 22.5 Working with Changesets...... 254 22.6 Uploading and Downloading GPS Tracks...... 258 22.7 Accessing User Data...... 259 22.8 Capabilities Request...... 260 22.9 Authorization with OAuth...... 261 22.10 Development and Testing APIs...... 262

XI Table of Contents

23 Other APIs and Web Services...... 263 23.1 XAPI...... 263 23.2 Name Finder...... 265 23.3 Nominatim...... 267 23.4 GeoNames...... 268 24 Osmosis, the Universal Tool...... 269 24.1 Common Command Line Options...... 271 24.2 Reading and Writing XML Files...... 271 24.3 Reading and Writing Databases...... 271 24.4 Creating and Processing Change Files...... 274 24.5 Filtering by Geography or Tags...... 277 24.6 Merging and Multiplying Data Streams...... 278 24.7 Other Tasks...... 279 24.8 Processing Old Data Files...... 280 24.9 Osmosis Plugins...... 281 24.10 Alternatives to Osmosis...... 281 25 Advanced Editing...... 283 25.1 Large-Scale Changes Using the Editor...... 284 25.2 Undeleting Objects...... 284 25.3 Making Automated Changes ...... 286 25.4 Reverting Changes...... 287 26 Import and Export...... 291 26.1 General Data Import Issues...... 291 26.2 Importing Shapefiles...... 292 26.3 Data Export...... 293 26.4 Exporting Bitmap and Vector Images...... 295 27 Running an OSM Server...... 297 27.1 Running Your Own API Server...... 297 27.2 The API SQL Schema...... 299 27.3 Running Your Own Tile Server...... 305 27.4 The Osm2pgsql SQL Schema...... 307

Appendix A. Introduction to Geodesy...... 311 B. Mapping the World...... 315

Index...... 326 Directory of OSM Tags...... 335

XII