{"id":17945337,"url":"https://github.com/westnordost/osmapi","last_synced_at":"2025-04-04T17:06:15.718Z","repository":{"id":52354820,"uuid":"55868746","full_name":"westnordost/osmapi","owner":"westnordost","description":"Java client for the OSM API 0.6","archived":false,"fork":false,"pushed_at":"2025-01-20T10:59:35.000Z","size":659,"stargazers_count":100,"open_issues_count":0,"forks_count":19,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-28T16:05:57.256Z","etag":null,"topics":["java","osm","osm-api"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/westnordost.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":"2016-04-09T21:56:31.000Z","updated_at":"2025-03-25T07:45:22.000Z","dependencies_parsed_at":"2023-11-22T03:24:26.157Z","dependency_job_id":"9c3bfcd3-17b7-4df9-aa9a-917d7fb31cf0","html_url":"https://github.com/westnordost/osmapi","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/westnordost%2Fosmapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/westnordost%2Fosmapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/westnordost%2Fosmapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/westnordost%2Fosmapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/westnordost","download_url":"https://codeload.github.com/westnordost/osmapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247217175,"owners_count":20903009,"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":["java","osm","osm-api"],"created_at":"2024-10-29T06:43:05.145Z","updated_at":"2025-04-04T17:06:15.698Z","avatar_url":"https://github.com/westnordost.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# osmapi\r\n\r\nosmapi is a client for the [OSM API 0.6](http://wiki.openstreetmap.org/wiki/API_v0.6).\r\n\r\nIt is well tested (test coverage over 90%) and being used by [StreetComplete](https://github.com/westnordost/StreetComplete), thus actively maintained. It does not have any dependencies.\r\n\r\nNote, the OSM API, particularly the part to download the map data, is intended only for editing the map. It's not made for pulling larger amounts of data or data analysis of certain map features. If this is what you intend to do, the [Overpass API](https://wiki.openstreetmap.org/wiki/Overpass_API) is what you will want to use. I created a basic Java client for the Overpass API here, it builts upon this library: [osmapi-overpass](https://github.com/westnordost/osmapi-overpass).\r\n\r\n## Copyright and License\r\n\r\n© 2016-2025 Tobias Zwick. This library is released under the terms of the [GNU Lesser General Public License](http://www.gnu.org/licenses/lgpl-3.0.html) (LGPL).\r\n\r\n## Installation\r\n\r\nDepending on which part of the API you use, you can only include what you need:\r\n\r\n\u003ctable\u003e\r\n\u003ctr\u003e\u003cth\u003eClass\u003c/th\u003e\u003cth\u003eDependency\u003c/th\u003e\u003cth\u003eDescription\u003c/th\u003e\u003c/tr\u003e\r\n\u003ctr\u003e\u003ctd\u003eCapabilitiesApi\u003c/td\u003e\u003ctd\u003e\u003cpre\u003ede.westnordost:osmapi-core:3.1\u003c/pre\u003e\u003c/td\u003e\u003ctd\u003eGetting server capabilities\u003c/td\u003e\u003c/tr\u003e\r\n\u003ctr\u003e\u003ctd\u003ePermissionsApi\u003c/td\u003e\u003ctd\u003e\u003cpre\u003ede.westnordost:osmapi-core:3.1\u003c/pre\u003e\u003c/td\u003e\u003ctd\u003eGetting user permissions\u003c/td\u003e\u003c/tr\u003e\r\n\u003ctr\u003e\u003ctd\u003eMapDataApi\u003c/td\u003e\u003ctd\u003e\u003cpre\u003ede.westnordost:osmapi-map:3.1\u003c/pre\u003e\u003c/td\u003e\u003ctd\u003eGetting map data, querying single elements and their relations toward each other and uploading changes in changesets\u003c/td\u003e\u003c/tr\u003e\r\n\u003ctr\u003e\u003ctd\u003eMapDataHistoryApi\u003c/td\u003e\u003ctd\u003e\u003cpre\u003ede.westnordost:osmapi-map:3.1\u003c/pre\u003e\u003c/td\u003e\u003ctd\u003eGetting the history and specific versions of elements\u003c/td\u003e\u003c/tr\u003e\r\n\u003ctr\u003e\u003ctd\u003eNotesApi\u003c/td\u003e\u003ctd\u003e\u003cpre\u003ede.westnordost:osmapi-notes:3.1\u003c/pre\u003e\u003c/td\u003e\u003ctd\u003eGetting finding, creating, commenting on and solving notes\u003c/td\u003e\u003c/tr\u003e\r\n\u003ctr\u003e\u003ctd\u003eGpsTracesApi\u003c/td\u003e\u003ctd\u003e\u003cpre\u003ede.westnordost:osmapi-traces:3.2\u003c/pre\u003e\u003c/td\u003e\u003ctd\u003eGetting, uploading, updating and deleting GPS traces and trackpoints\u003c/td\u003e\u003c/tr\u003e\r\n\u003ctr\u003e\u003ctd\u003eChangesetsApi\u003c/td\u003e\u003ctd\u003e\u003cpre\u003ede.westnordost:osmapi-changesets:3.1\u003c/pre\u003e\u003c/td\u003e\u003ctd\u003eFinding changesets, changeset discussion, subscription and data\u003c/td\u003e\u003c/tr\u003e\r\n\u003ctr\u003e\u003ctd\u003eUserApi\u003c/td\u003e\u003ctd\u003e\u003cpre\u003ede.westnordost:osmapi-user:3.1\u003c/pre\u003e\u003c/td\u003e\u003ctd\u003eGetting user information\u003c/td\u003e\u003c/tr\u003e\r\n\u003ctr\u003e\u003ctd\u003eUserPreferencesApi\u003c/td\u003e\u003ctd\u003e\u003cpre\u003ede.westnordost:osmapi-user:3.1\u003c/pre\u003e\u003c/td\u003e\u003ctd\u003eManaging user preferences\u003c/td\u003e\u003c/tr\u003e\r\n\u003ctr\u003e\u003ctd\u003eMessagesApi\u003c/td\u003e\u003ctd\u003e\u003cpre\u003ede.westnordost:osmapi-messages:1.0\u003c/pre\u003e\u003c/td\u003e\u003ctd\u003eSend and receive messages\u003c/td\u003e\u003c/tr\u003e\r\n\u003c/table\u003e\r\n\r\nTo include everything, add [`de.westnordost:osmapi:5.2`](https://mvnrepository.com/artifact/de.westnordost/osmapi/5.2) as a Maven dependency or download the jar from there.\r\n\r\n### Android\r\n\r\nOn Android, you need to exclude kxml2 from the dependencies in your `gradle.kts` since it is already built-in, like so:\r\n\r\n```kotlin\r\nconfigurations {\r\n    all {\r\n        // it's already included in Android\r\n        exclude(group = \"net.sf.kxml\", module = \"kxml2\")\r\n        exclude(group = \"xmlpull\", module = \"xmlpull\")\r\n    }\r\n}\r\n```\r\n\r\nThis library uses classes from the Java 8 time API, like [`Instant`](https://developer.android.com/reference/java/time/Instant) etc., so if your app supports Android API levels below 26, you need to enable [Java 8+ API desugaring support](https://developer.android.com/studio/write/java8-support#library-desugaring).\r\n\r\n## Basic Usage\r\n\r\nEverything revolves around the OsmConnection, this is the class that talks to the Api. Specify where to reach the Api, how the client should identify itself towards the server etc.\r\nIf you plan to make calls that can only be made by a logged in user, such as uploading map data, the OAuth 2.0 access token (third parameter) needs to be specified.\r\n\r\n```java\r\n    OsmConnection osm = new OsmConnection(\r\n        \"https://api.openstreetmap.org/api/0.6/\",\r\n        \"my user agent\", null\r\n    );\r\n```\r\n\r\nYou can call `osm.makeRequest(...)` yourself to talk with the RESTful Api and write your own ApiRequestWriter and ApiResponseReader to write/read the request.\r\nIt is more convenient however to use the appropriate class to do that for you and return the data you are interested in. See the table above for which classes are available.\r\n\r\nFor example...\r\n\r\n### Create a note\r\n\r\n```java\r\n    Note myNote = new NotesApi(osm).create(position, \"My first note\");\r\n```\r\n\r\n### Comment a changeset\r\n\r\n```java\r\n    ChangesetInfo changeset = new ChangesetsApi(osm).comment(id, \"Nice work!\");\r\n```\r\n\r\n### Get user info\r\n\r\n```java\r\n    UserInfo user = new UserApi(osm).get(id);\r\n```\r\n\r\n### Download map data\r\n\r\n```java\r\n    MapDataApi mapApi = new MapDataApi(osm);\r\n    mapApi.getMap(boundingBox, myMapDataHandler);\r\n```\r\n\r\nmyMapDataHandler implements MapDataHandler whose methods are called as the elements are parsed, think SAX parser. I.e. if you download 10MB of data, then the elements start arriving at the handler as the data comes in so that you can process them on the fly.\r\n\r\n```java\r\n    /** This class is fed the map data. */\r\n    public interface MapDataHandler\r\n    {\r\n        void handle(Bounds bounds);\r\n\r\n        void handle(Node node);\r\n        void handle(Way way);\r\n        void handle(Relation relation);\r\n    }\r\n```\r\n\r\n## Combine with data processing library\r\n[Read this](Combine_With_Data_Processing_Libraries.md) if you want to use this library in conjunction with a data processing library like Osmosis, osm4j or have your own map data structures already.\r\n\r\n## Troubleshooting\r\n\r\nIf you are getting the exception\r\n```\r\nsun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target.\r\n```\r\n, try updating your Java SDK. Openstreetmap.org uses Let's Encrypt certificates which are not trusted in earlier versions of Java by default. [Read more here](https://stackoverflow.com/questions/34110426/does-java-support-lets-encrypt-certificates).\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwestnordost%2Fosmapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwestnordost%2Fosmapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwestnordost%2Fosmapi/lists"}