{"id":16225746,"url":"https://github.com/macfja/citiesborder","last_synced_at":"2026-04-26T22:31:51.511Z","repository":{"id":145406330,"uuid":"93391651","full_name":"MacFJA/CitiesBorder","owner":"MacFJA","description":"Extract cities border from OpenStreetMap","archived":false,"fork":false,"pushed_at":"2017-08-13T10:01:07.000Z","size":12,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-28T00:37:32.125Z","etag":null,"topics":["border","city","map","openstreetmap","osmosis"],"latest_commit_sha":null,"homepage":null,"language":"Java","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/MacFJA.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2017-06-05T10:13:51.000Z","updated_at":"2017-06-14T12:36:36.000Z","dependencies_parsed_at":"2023-04-28T12:04:16.282Z","dependency_job_id":null,"html_url":"https://github.com/MacFJA/CitiesBorder","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MacFJA/CitiesBorder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MacFJA%2FCitiesBorder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MacFJA%2FCitiesBorder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MacFJA%2FCitiesBorder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MacFJA%2FCitiesBorder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MacFJA","download_url":"https://codeload.github.com/MacFJA/CitiesBorder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MacFJA%2FCitiesBorder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32315711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T21:09:39.134Z","status":"ssl_error","status_checked_at":"2026-04-26T21:09:21.240Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["border","city","map","openstreetmap","osmosis"],"created_at":"2024-10-10T12:46:08.313Z","updated_at":"2026-04-26T22:31:51.494Z","avatar_url":"https://github.com/MacFJA.png","language":"Java","readme":"CitiesBorder\n============\n\nThis library (and command line tool) allow you to get the border of cities.  \nA city border is the geometric shape that define the outer line of a city at the administrative level. The border is defined by a list of GPS location which, when connected together, draw the outline of a city.\n\nInstallation\n------------\n\nClone the project:\n```\ngit clone https://github.com/MacFJA/CitiesBorder.git\n```\nInstall the project into your local Maven repository:\n```\ncd CitiesBorder/\nmvn clean\nmvn install\n```\nRemove the source:\n```\ncd ..\nrm -r CitiesBorder/\n```\nAdd the dependency in your Maven project:\n```xml\n\u003cproject\u003e\n    \u003c!-- ... --\u003e\n    \u003cdependencies\u003e\n        \u003c!-- ... --\u003e\n        \u003cdependency\u003e\n            \u003cgroupId\u003eio.github.macfja\u003c/groupId\u003e\n            \u003cartifactId\u003ecities-border\u003c/artifactId\u003e\n            \u003cversion\u003e1.0.1\u003c/version\u003e\n        \u003c/dependency\u003e\n        \u003c!-- ... --\u003e\n    \u003c/dependencies\u003e\n    \u003c!-- ... --\u003e\n\u003c/project\u003e\n```\n\nDependencies\n------------\n\nAll dependencies are **optional**.  \nBecause If you do not intend to use the CLI, the CLI argument parser is useless for you.  \nSame thing, if you don't intend to transform raw PBF to XML (because you already have a CitiesBorder file or a generated Xml file), all dependencies to Osmosis are not necessary for you.\n\nUsage\n-----\n\n### Create a lite OSM Xml\n\nBecause, by default, the OSM file contains a lots of information that are not needed for getting the border of a city, we run Osmosis first to reduce the number of elements.\n\nTo do so you have 2 possibilities:\n\n - Get the Osmosis tool and run a command\n - Execute a pre-configured Osmosis command inside this library\n\nThe Osmosis parameters configured in the library are:\n\n - `--read-pbf file=$INPUT_FILE_PATH`\n - `--tf accept-relation admin_level=$ADMINISTRATION_LEVEL`\n - `--tf accept-relation ref:INSEE=*`\n - `--used-way`\n - `--used-node`\n - `--write-xml $OUTPUT_FILE_PATH`\n\nThe **INSEE** parameters is for finding cities in France (it's a national city identification code, similar to a ZipCode, but it's more precise).\n\nThe method to call in the library is:\n```java\nio.github.macfja.citiesborder.Worker.runOsmosis(String outputPath, String inputPath, int administrationLevel)\n```\n\n### Transform Xml OSM file into a CitiesBorder file\n\nTo transform the OSM Xml file into a much compact file (for more detail about the file format, see below) you can use the method:\n```java\nio.github.macfja.citiesborder.Worker.runBuildCitiesBorderFile(String inputPath, String outputPath, boolean append)\n```\n\n### Search city into CitiesBorder file\n\nTo search a city (and get its border) you can use the method:\n```java\nio.github.macfja.citiesborder.Worker.search(String inputPath, String name)\n```\n\nCitiesBorder file format\n------------------------\n\nThe CitiesBorder file is a very simple file format.  \nThe content is divided into cities, which are divided into 2 main part: the city header, and the list of GPS position.\n\nThe whole file is compressed with GZip.\n\n### Format definition\n\n```bnf\nFileFormat   ::= 0*(CITY)\nCITY         ::= CITY_HEADER \"\\n\" GPS_LIST\nCITY_HEADER  ::= \"{\" 1*(\u003cCHAR\u003e) \"}:\" 1*(\u003cDIGIT\u003e)\nGPS_LIST     ::= 1*( GPS_POSITION  \"\\n\" )\nGPS_POSITION ::= LAT \" \" LON\nLAT          ::= 1*(\u003cDIGIT\u003e) \".\" 1*(\u003cDIGIT\u003e) ; A GPS latitude\nLON          ::= 1*(\u003cDIGIT\u003e) \".\" 1*(\u003cDIGIT\u003e) ; A GPS longitude\n```\n\nThe number after the name of the city is the number of char for all GPS position (`\\n` included). It's for retrieving or skip data (which allow us to rapidly read the file as the majority of the file is GPS data).\n\n### Example\n\n```\n{Lannoy}:639\n50.663547 3.2092917\n50.6635639 3.2093238\n50.664 3.2101538\n50.6659982 3.2139546\n50.6660288 3.2139043\n50.6660893 3.2138047\n50.6667942 3.2148888\n50.6675158 3.2137095\n50.6676128 3.2136204\n50.6678023 3.2131893\n50.6680804 3.212179\n50.6680804 3.212179\n50.6681387 3.2119827\n50.6682581 3.2113993\n50.6683653 3.2108751\n50.6685022 3.2105947\n50.6685022 3.2105947\n50.6681897 3.2102959\n50.6671891 3.2077656\n50.6672082 3.2077477\n50.6665476 3.2062119\n50.6664682 3.2060274\n50.6663932 3.205832\n50.6663794 3.2057961\n50.663547 3.2092917\n50.663747 3.2089819\n50.665149 3.2070008\n50.6652317 3.2070023\n50.6661605 3.2059508\n50.6662971 3.2058326\n50.6663794 3.2057961\n{Beaurain}:768\n50.1818918 3.5445628\n50.1816404 3.545618\n50.1816663 3.5469924\n50.1831404 3.5479035\n50.1827674 3.5490806\n50.1828224 3.5515172\n50.1840922 3.552798\n50.1711761 3.558626\n50.1721295 3.5561344\n50.1718745 3.555307\n50.1713492 3.5551178\n50.172746 3.5511654\n50.1723348 3.5508619\n50.1743752 3.5465735\n50.1740406 3.5461546\n50.1751985 3.5434273\n50.1780552 3.5439677\n50.1799378 3.5440147\n50.1807972 3.5446813\n50.1818918 3.5445628\n50.1840922 3.552798\n50.1835394 3.5530961\n50.1824564 3.5548128\n50.1815223 3.5553422\n50.1812211 3.5554197\n50.1805283 3.5563805\n50.1792652 3.5570292\n50.1786376 3.5569708\n50.1779876 3.5564441\n50.1775252 3.5562623\n50.1761873 3.5562286\n50.1749867 3.5561133\n50.1749752 3.5572187\n50.1739328 3.5576603\n50.1739446 3.559149\n50.1733293 3.5605369\n50.1711761 3.558626\n```\n\nLimitation\n----------\n\n - If two (or more) cities have the same name, the first found will be return by the search function.\n - As the library was first written for the France context, the Osmosis transformation included in the library only work with cities of France.\n - The way that library read OSM Xml can be very memory unefficient on a large Xml file.\n - The transformation from Xml to CitiesBorder file assume that the Xml first contains all `\u003cnode\u003e`, then all `\u003cway\u003e` and finally all `\u003crelation\u003e` (if it's not the case, the code will lead to an uncomplete file)","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacfja%2Fcitiesborder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmacfja%2Fcitiesborder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacfja%2Fcitiesborder/lists"}