Skip to content
General purpose library for reading, writing and working with OpenStreetMap data
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
annotate annotate: expose IsReverse Dec 10, 2018
internal remove To prefix from some methods Mar 9, 2018
osmapi osmapi: reset default datasource url after tests Sep 14, 2018
osmgeojson osmgeojson: fix panic if missing multiple outers Nov 25, 2018
osmpbf osmpbf: ensure decoding is done in correct order after restart Dec 14, 2018
osmtest add tests to subpackages Mar 7, 2018
osmxml add more test coverage to core types Mar 9, 2018
replication replication: remove ChangesetSeqNum from SeqNum interface Mar 18, 2018
testdata add some extra test coverage Mar 6, 2018
.gitignore Add version, minor v, csID to relation members Sep 26, 2016
.travis.yml
LICENSE.md add license Feb 16, 2017
README.md Fix example code that panics on wrong error value Dec 8, 2018
bounds.go updates for orb refactor Nov 11, 2017
bounds_test.go more test coverage for core package Mar 8, 2018
change.go remove To prefix from some methods Mar 9, 2018
change_test.go remove To prefix from some methods Mar 9, 2018
changeset.go make test function names consistent Feb 24, 2018
changeset_test.go more test coverage for core package Mar 8, 2018
datasource.go more test coverage for core package Mar 8, 2018
datasource_test.go remove To prefix from some methods Mar 9, 2018
diff.go fixup xmling of osm diffs Mar 19, 2018
diff_test.go fixup xmling of osm diffs Mar 19, 2018
element.go add more test coverage to core types Mar 9, 2018
element_test.go add more test coverage to core types Mar 9, 2018
feature.go FeatureID: don't panic if invalid type Dec 10, 2018
feature_test.go FeatureID: don't panic if invalid type Dec 10, 2018
json.go refactor to include Users and Notes Feb 23, 2018
marshal.go fixup some type usages Dec 3, 2017
marshal_test.go make test function names consistent Feb 24, 2018
node.go fixup semantics of Object and ObjectID Feb 24, 2018
node_test.go more test coverage for core package Mar 8, 2018
note.go fix linter errors Mar 9, 2018
note_test.go add json struct tags for notes and users Mar 8, 2018
object.go add more test coverage to core types Mar 9, 2018
object_test.go add more test coverage to core types Mar 9, 2018
osm.go fixup xmling of osm diffs Mar 19, 2018
osm_test.go add more test coverage to core types Mar 9, 2018
polygon.go refactor to include Users and Notes Feb 23, 2018
polygon_test.go fixup semantics of Object and ObjectID Feb 24, 2018
relation.go fix ApplyUpdatesUpTo for out of order updates Mar 12, 2018
relation_test.go fix ApplyUpdatesUpTo for out of order updates Mar 12, 2018
tag.go add AnyInteresting function to Tags object Oct 6, 2018
tag_test.go add AnyInteresting function to Tags object Oct 6, 2018
update.go annotate: work on a single child at a time Jan 7, 2018
update_test.go annotate: work on a single child at a time Jan 7, 2018
user.go add json struct tags for notes and users Mar 8, 2018
user_test.go add json struct tags for notes and users Mar 8, 2018
way.go way: add bound method returning orb.Bound Nov 27, 2018
way_test.go way: add bound method returning orb.Bound Nov 27, 2018

README.md

osm Build Status Go Report Card Godoc Reference

This package is a general purpose library for reading, writing and working with OpenStreetMap data in Go (golang). It has the ability to read OSM XML and PBF data formats available at planet.osm.org or via the v0.6 API.

Made available by the package are the following types:

  • Node
  • Way
  • Relation
  • Changeset
  • Note
  • User

And the following “container” types:

List of sub-package utilities

  • annotate - adds lat/lon, version, changeset and orientation data to way and relation members
  • osmapi - supports all the v0.6 read/data endpoints
  • osmgeojson - OSM to GeoJSON conversion compatible with osmtogeojson
  • osmpbf - stream processing of *.osm.pbf files
  • osmxml - stream processing of *.osm xml files.
  • replication - fetch replication state and change files

Concepts

This package refers to the core OSM data types as Objects. The Node, Way, Relation, Changeset, Note and User types implement the osm.Object interface and can be referenced using the osm.ObjectID type. As a result it is possible to have a slice of []osm.Object that contains nodes, changesets and users.

Individual versions of the core OSM Map Data types are referred to as Elements and the set of versions for a give Node, Way or Relation is referred to as a Feature. For example, an osm.ElementID could refer to "Node with id 10 and version 3" and the osm.FeatureID would refer to "all versions of node with id 10." Put another way, features represent a road and how it's changed over time and an element is a specific version of that feature.

A number of helper methods are provided for dealing with features and elements. The idea is to make it easy to work with a Way and it's member nodes, for example.

Scanning large data files

For small data it is possible to use the encoding/xml package in the Go standard libray to marshal/unmarshal the data. This is typically done using the osm.OSM or osm.Change "container" structs.

For large data the package defines the Scanner interface implemented in both the osmxml and osmpbf sub-packages.

type osm.Scanner interface {
	Scan() bool
	Object() osm.Object
	Err() error
	Close() error
}

This interface is designed to mimic the bufio.Scanner interface found in the Go standard library.

Example usage:

f, err := os.Open("./delaware-latest.osm.pbf")
if err != nil {
	panic(err)
}
defer f.Close()

scanner := osmpbf.New(context.Background(), f, 3)
defer scanner.Close()

for scanner.Scan() {
	o := scanner.Object()
	// do something
}

scanErr := scanner.Err()
if scanErr != nil {
	panic(scanErr)
}

Note: Scanners are not safe for parallel use. One should feed the objects into a channel and have workers read from that.

You can’t perform that action at this time.