{"id":13412996,"url":"https://github.com/paulmach/osm","last_synced_at":"2025-04-13T00:46:40.239Z","repository":{"id":3869865,"uuid":"50883366","full_name":"paulmach/osm","owner":"paulmach","description":"General purpose library for reading, writing and working with OpenStreetMap data","archived":false,"fork":false,"pushed_at":"2024-05-06T08:58:37.000Z","size":11641,"stargazers_count":399,"open_issues_count":6,"forks_count":51,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-13T00:46:27.210Z","etag":null,"topics":["golang","openstreetmap","osm","osmpbf","xml"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paulmach.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-02-02T00:59:03.000Z","updated_at":"2025-04-09T04:23:26.000Z","dependencies_parsed_at":"2024-01-08T15:03:04.993Z","dependency_job_id":"56268584-7c4a-4706-9686-3251e6c9295e","html_url":"https://github.com/paulmach/osm","commit_stats":{"total_commits":272,"total_committers":11,"mean_commits":"24.727272727272727","dds":"0.34558823529411764","last_synced_commit":"e652b501b3d4575e1aecea7cf92903445877a965"},"previous_names":["paulmach/go.osm"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulmach%2Fosm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulmach%2Fosm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulmach%2Fosm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulmach%2Fosm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paulmach","download_url":"https://codeload.github.com/paulmach/osm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248650434,"owners_count":21139672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","openstreetmap","osm","osmpbf","xml"],"created_at":"2024-07-30T20:01:32.100Z","updated_at":"2025-04-13T00:46:40.209Z","avatar_url":"https://github.com/paulmach.png","language":"Go","funding_links":[],"categories":["Geographic","地理","位置信息与地理GEO处理库","Relational Databases"],"sub_categories":["Search and Analytic Databases","Advanced Console UIs","检索及分析资料库","SQL 查询语句构建库"],"readme":"# osm [![CI](https://github.com/paulmach/osm/workflows/CI/badge.svg)](https://github.com/paulmach/osm/actions?query=workflow%3ACI+event%3Apush) [![Go Report Card](https://goreportcard.com/badge/github.com/paulmach/osm)](https://goreportcard.com/report/github.com/paulmach/osm) [![Go Reference](https://pkg.go.dev/badge/github.com/paulmach/osm.svg)](https://pkg.go.dev/github.com/paulmach/osm)\n\nThis package is a general purpose library for reading, writing and working\nwith [OpenStreetMap](https://osm.org) data in Go (golang). It has the ability to:\n\n-   read/write [OSM XML](https://wiki.openstreetmap.org/wiki/OSM_XML)\n-   read/write [OSM JSON](https://wiki.openstreetmap.org/wiki/OSM_JSON),\n    a format returned by the Overpass API.\n-   efficiently parse [OSM PBF](https://wiki.openstreetmap.org/wiki/PBF_Format) data files available at\n    [planet.osm.org](https://planet.osm.org/)\n\nMade available by the package are the following types:\n\n-   Node\n-   Way\n-   Relation\n-   Changeset\n-   Note\n-   User\n\nAnd the following “container” types:\n\n-   OSM - container returned via API\n-   Change - used by the replication API\n-   Diff - corresponds to [Overpass Augmented Diffs](https://wiki.openstreetmap.org/wiki/Overpass_API/Augmented_Diffs)\n\n## List of sub-package utilities\n\n-   [`annotate`](annotate) - adds lon/lat, version, changeset and orientation data to way and relation members\n-   [`osmapi`](osmapi) - supports all the v0.6 read/data endpoints\n-   [`osmgeojson`](osmgeojson) - OSM to GeoJSON conversion compatible with [osmtogeojson](https://github.com/tyrasd/osmtogeojson)\n-   [`osmpbf`](osmpbf) - stream processing of `*.osm.pbf` files\n-   [`osmxml`](osmxml) - stream processing of `*.osm` xml files\n-   [`replication`](replication) - fetch replication state and change files\n\n## Concepts\n\nThis package refers to the core OSM data types as **Objects**. The Node, Way,\nRelation, Changeset, Note and User types implement the `osm.Object` interface\nand can be referenced using the `osm.ObjectID` type. As a result it is possible\nto have a slice of `[]osm.Object` that contains nodes, changesets and users.\n\nIndividual versions of the core OSM Map Data types are referred to as **Elements**\nand the set of versions for a give Node, Way or Relation is referred to as a\n**Feature**. For example, an `osm.ElementID` could refer to \"Node with id 10 and\nversion 3\" and the `osm.FeatureID` would refer to \"all versions of node with id 10.\"\nPut another way, features represent a road and how it's changed over time and an\nelement is a specific version of that feature.\n\nA number of helper methods are provided for dealing with features and elements.\nThe idea is to make it easy to work with a Way and its member nodes, for example.\n\n## Scanning large data files\n\nFor small data it is possible to use the `encoding/xml` package in the\nGo standard library to marshal/unmarshal the data. This is typically done using the\n`osm.OSM` or `osm.Change` \"container\" structs.\n\nFor large data the package defines the `Scanner` interface implemented in both the [osmxml](osmxml)\nand [osmpbf](osmpbf) sub-packages.\n\n```go\ntype osm.Scanner interface {\n\tScan() bool\n\tObject() osm.Object\n\tErr() error\n\tClose() error\n}\n```\n\nThis interface is designed to mimic the [bufio.Scanner](https://golang.org/pkg/bufio/#Scanner)\ninterface found in the Go standard library.\n\nExample usage:\n\n```go\nf, err := os.Open(\"./delaware-latest.osm.pbf\")\nif err != nil {\n\tpanic(err)\n}\ndefer f.Close()\n\nscanner := osmpbf.New(context.Background(), f, 3)\ndefer scanner.Close()\n\nfor scanner.Scan() {\n\to := scanner.Object()\n\t// do something\n}\n\nscanErr := scanner.Err()\nif scanErr != nil {\n\tpanic(scanErr)\n}\n```\n\n**Note:** Scanners are **not** safe for parallel use. One should feed the\nobjects into a channel and have workers read from that.\n\n## Working with JSON\n\nThis library supports reading and writing [OSM JSON](https://wiki.openstreetmap.org/wiki/OSM_JSON).\nThis format is returned by the Overpass API and can be optionally returned by the\n[OSM API](https://wiki.openstreetmap.org/wiki/API_v0.6#JSON_Format).\n\nIf performance is important, this library supports third party \"encoding/json\" replacements\nsuch as [github.com/json-iterator/go](https://github.com/json-iterator/go).\n\nThey can be enabled with something like this:\n\n```go\nimport (\n  jsoniter \"github.com/json-iterator/go\"\n  \"github.com/paulmach/osm\"\n)\n\nvar c = jsoniter.Config{\n  EscapeHTML:              true,\n  SortMapKeys:             false,\n  MarshalFloatWith6Digits: true,\n}.Froze()\n\nosm.CustomJSONMarshaler = c\nosm.CustomJSONUnmarshaler = c\n```\n\nThe above change can have dramatic performance implications, see the benchmarks below\non a large OSM Change object.\n\n```\nbenchmark                            old ns/op     new ns/op     delta\nBenchmarkChange_MarshalJSON-12       604496        461349        -23.68%\nBenchmarkChange_UnmarshalJSON-12     1633834       1051630       -35.63%\n\nbenchmark                            old allocs    new allocs    delta\nBenchmarkChange_MarshalJSON-12       1277          1081          -15.35%\nBenchmarkChange_UnmarshalJSON-12     5133          8580          +67.15%\n\nbenchmark                            old bytes     new bytes     delta\nBenchmarkChange_MarshalJSON-12       180583        162727        -9.89%\nBenchmarkChange_UnmarshalJSON-12     287707        317723        +10.43%\n```\n\n## CGO and zlib\n\nOSM PBF data comes in blocks, each block is zlib compressed. Decompressing this\ndata takes about 33% of the total read time. [DataDog/czlib](https://github.com/DataDog/czlib) is\nused to speed this process.\nSee [osmpbf/README.md](osmpbf#using-cgoczlib-for-decompression) for more details.\n\nAs a result, a C compiler is necessary to install this module. On macOS this may require\ninstalling pkg-config using something like `brew install pkg-config`\n\nCGO can be disabled at build time using the `CGO_ENABLED` ENV variable.\nFor example, `CGO_ENABLED=0 go build`. The code will fallback to the stdlib implementation of zlib.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulmach%2Fosm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaulmach%2Fosm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulmach%2Fosm/lists"}