{"id":20751779,"url":"https://github.com/clarisma/gol-tool","last_synced_at":"2025-06-11T10:07:48.464Z","repository":{"id":64866980,"uuid":"484807746","full_name":"clarisma/gol-tool","owner":"clarisma","description":"Command-line utility for creating and managing Geographic Object Libraries","archived":false,"fork":false,"pushed_at":"2025-03-26T14:08:51.000Z","size":627,"stargazers_count":13,"open_issues_count":67,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-26T15:26:47.074Z","etag":null,"topics":["geodesk","openstreetmap"],"latest_commit_sha":null,"homepage":"https://docs.geodesk.com/gol","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clarisma.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2022-04-23T17:04:48.000Z","updated_at":"2025-03-26T14:08:55.000Z","dependencies_parsed_at":"2024-09-17T13:47:49.865Z","dependency_job_id":"83140e12-f275-40bf-92d0-d2261455e36c","html_url":"https://github.com/clarisma/gol-tool","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clarisma%2Fgol-tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clarisma%2Fgol-tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clarisma%2Fgol-tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clarisma%2Fgol-tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clarisma","download_url":"https://codeload.github.com/clarisma/gol-tool/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251320177,"owners_count":21570534,"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":["geodesk","openstreetmap"],"created_at":"2024-11-17T08:38:13.074Z","updated_at":"2025-04-28T13:34:06.130Z","avatar_url":"https://github.com/clarisma.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://docs.geodesk.com/img/github-header.png\"\u003e\n\n# Geographic Object Librarian (GOL)\n\nUse the GOL command-line utility to:\n\n- build and maintain Geographic Object Libraries (GeoDesk's compact database format for OpenStreetMap features)\n \n- perform [GOQL](http://docs.geodesk.com/goql) queries and export the results in a variety of formats.\n\n## Setup\n\nThe GOL Utility is a cross-platform Java application. You will need to install a 64-bit JVM, Version 16 or above.\n\nApart from a 64-bit CPU, hardware requirements are minimal. The exception is the `gol build` command, which has higher recommended system configurations for reasonable performance.\n\n### Building from source\n\nTo build the latest version from source, you will first need to build and install the [GeoDesk Java library](http://www.github.com/clarisma/geodesk):\n\n```\ngit clone https://github.com/clarisma/geodesk.git\ncd geodesk\nmvn install\ncd ..\n```\n\nThen the GOL tool itself:\n\n```\ngit clone https://github.com/clarisma/gol-tool.git\ncd gol-tool\nmvn install\n```\n\n*If you get weird exceptions during `mvn install`, you should [upgrade Maven](https://maven.apache.org/download.cgi) to version **3.8.5** or above.*\n\nA `gol.bat` (for Windows) and a `gol` shell script are supplied.\n\n**Linux users**: You may have to make the launcher script executable using `chmod u+x gol`. To conveniently use the command from any folder, consider creating a symbolic link on your path, e.g. \u003ccode\u003eln -s \u003ci\u003egol_app_dir\u003c/i\u003e/gol ~/bin/gol\u003c/code\u003e.\n\nIf you experience performance problems or out-of-memory errors, you may need to override the default memory-management settings in the call to `java`. Use option `-Xmx` to explicitly set the maximum heap size, e.g. `-Xmx4g` to allow Java to use 4 GB of heap space. \n\n## Converting OpenStreetMap data into a GOL\n\nUse\n\n```\ngol build world planet-latest.osm.pbf  \n```\n\nto turn a planet file into `world.gol`.\n\nPlease note that converting an OpenStreetMap PBF file into a GOL is a resource-intensive process. A multi-core system with at least 24 GB is recommended for larger datasets. On a 10-core workstation with 32 GB RAM and an NVMe SSD, building a GOL from a 60 GB planet file takes about half an hour. A machine with less memory will manage, but may start paging furiously. Nonetheless, even a dual-core notebook with 8 GB RAM converts a country-size extract such as Germany (3.5 GB) in about 20 minutes (a quality SSD clearly helps on such a machine).\n\nYou should have plenty of disk space available, to accommodate the temporary files and the resulting GOL. 3 to 5 times the size of the PBF is a good rule of thumb, though the ratio could be as high as 10:1 for smaller files.\n\n### Java heap-size settings\n\nIf you get an \"out of memory\" error during the \"compile\" phase, you should increase the maximum heap settings (`-Xmx`) in the launcher script. When you re-run the `build` command, it will continue compiling, you don't have to wait for re-processing of the previous phases.\n\nConversely, you may get better throughput on a low-end machine (8 GB RAM, or less) by adjusting `-Xmx`) downward, to leave more swap space to the OS. \n\n## Using existing tile sets\n\nIf you just want to experiment with the GOL utility, you can download our example tile set. This is an October 2022 snapshot of the complete OpenStreetMap data for Switzerland (about 400 MB).\n\nUse:\n\n```\ngol load -n swiss https://data.geodesk.com/switzerland\n```\n\nThis creates `swiss.gol` and populates it with the Switzerland dataset. GOLs are about 30% larger than the compressed tile sets, so be sure to have sufficient disk space.\n\nYou can also instruct `gol` to download tiles as-needed, by specifying the tile-set URL as a command-line option (`-u=https://data.geodesk.com/switzerland`).\n\n## Querying GOLs\n\nThe GOL utility performs [GOQL](http://docs.geodesk.com/goql) queries, within an optional bounding-box (`-b`) or polygonal area (`-a`).\n\nFor example:\n\n```\ngol query swiss na[amenity=fire_station] -f=geojson\n```\n\nfinds all fire stations in Switzerland and exports the features (nodes or areas) as GeoJSON.\n\nThe command-line utility only supports a subset of GeoDesk's query capabilities. For spatial joins, you will have to submit two commands. For example, to extract all pubs in Bavaria from `germany.gol`, use:\n\n```\ngol query germany a[boundary=administrative][admin_level=4][name:en=Bavaria] -f=poly \u003e bavaria.poly\n```\n\nThis creates a polygon file, which you can then use to restrict the second query (output as CSV with longitude, latitude and name as columns):\n\n```\ngol query germany na[amenity=pub] -a=bavaria.poly -f=csv -t=lon,lat,name \u003e pubs.csv\n```\n\nTo visualize query results on a [Leaflet](http://www.leafletjs.com)-powered slippy map, use the `map` formatting option and open the resulting file in your browser:\n\n```\ngol query germany na[amenity=pub] -a=bavaria.poly -f=map -t=lon,lat,name \u003e pubs.html\n```\n\n\nSee the [full documentation](http://docs.geodesk.com/gol/query) for details. Please note that as the current release is still Early Access, some less-common options are not yet supported.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclarisma%2Fgol-tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclarisma%2Fgol-tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclarisma%2Fgol-tool/lists"}