{"id":18737531,"url":"https://github.com/organicmaps/api-android","last_synced_at":"2025-04-12T19:32:25.310Z","repository":{"id":38028164,"uuid":"324829721","full_name":"organicmaps/api-android","owner":"organicmaps","description":"Offline Maps API for Android","archived":true,"fork":false,"pushed_at":"2024-08-03T10:00:27.000Z","size":648,"stargazers_count":28,"open_issues_count":5,"forks_count":11,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-26T14:04:14.076Z","etag":null,"topics":["android","api","maps","url"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/organicmaps.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"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},"funding":{"github":"organicmaps","liberapay":"OrganicMaps","custom":["https://organicmaps.app/donate"]}},"created_at":"2020-12-27T19:04:31.000Z","updated_at":"2025-03-19T05:08:24.000Z","dependencies_parsed_at":"2024-01-06T09:34:21.749Z","dependency_job_id":"6dca61f7-9dad-4867-aafb-75a8b126e245","html_url":"https://github.com/organicmaps/api-android","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/organicmaps%2Fapi-android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/organicmaps%2Fapi-android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/organicmaps%2Fapi-android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/organicmaps%2Fapi-android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/organicmaps","download_url":"https://codeload.github.com/organicmaps/api-android/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248621294,"owners_count":21134800,"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":["android","api","maps","url"],"created_at":"2024-11-07T15:25:36.658Z","updated_at":"2025-04-12T19:32:24.957Z","avatar_url":"https://github.com/organicmaps.png","language":"Java","funding_links":["https://github.com/sponsors/organicmaps","https://liberapay.com/OrganicMaps","https://organicmaps.app/donate"],"categories":[],"sub_categories":[],"readme":"# Organic Maps Android API: Getting Started\n\n## Introduction\n\nOrganic Maps Android API (hereinafter referred to as *\"API Library\"* or just *\"library\"*)\nprovides interface for client application to perform next tasks:\n\n* Show one or more points on offline map of [Organic Maps app][linkOM]\n* Come back to the client application after selecting specific point on the map, by sending [PendingIntent][linkPIntent] with point data when user asks for more information by pressing \"More Info\" button in Organic Maps app\n* Map screen branding : your application's icon and name (or custom title) will be placed at the top.\n\nThus, you can provide **two way communication between your application and Organic Maps**,\nusing Organic Maps to show points of interest (POI) and providing more information in your app.\n\nPlease refer to [sample application][linkSampleSource] for demo.\n\n**Note**: this library provides convenience wrappers for [deep links](https://omaps.app/api). Your application can also use deep links directly without including the library as a dependency. You can look at the library implementation for ideas on how to do that.\n\n## Prerequisites\n\nIt is supposed that you are familiar with Android Development.\nYou should be familiar with concept of [Intents][linkIntents], [library projects][linkLibProj], and [PendingIntents][linkPIntent] (recommended) as well.\n\nOrganic Maps works from *Android SDK version 21 (Android 5)* and above\n\n## Integration\nFirst step is to clone [repository][linkRepo] or download it as an archive.\n\nWhen your are done you find two folders: *lib* and *sample-app-capitals*. First one is a library project that you should add to your project.\nYou don't need any additional permissions in your AndroidManifest.xml to use API library, so you can write real code straight away, calling for different `Api` methods (more details below).\n\n## Classes Overview and HOW TO\nCore classes you will work with are:\n\n* [app.organicmaps.api.Point][linkPointClass] - model of POI, includes lat, lon, name, id, and style data.\n* [app.organicmaps.api.PickPointResponse][linkRespClass] - helps you to extract response from Organic Maps by applying `Response.extractFromIntent(Intent)` to Intent. Contains Point data.\n\n### Show Points on the Map\n\nThe simplest usage:\n\n    public class MyPerfectActivity extends Activity {\n    ...\n\n      void showSomethingOnTheMap(SomeDomainObject arg)\n      {\n        // Do some work, create lat, lon, and name for point\n        final double lat = ...;\n        final double lon = ...;\n        final String name = ...;\n        // Ask Organic Maps to show the point\n        Api.showPointOnMap(this, lat, lon, name);\n      }\n    ...\n\n    }\n\nFor multiple points use [Point][linkPointClass] class:\n\n    void showMultiplePoints(List\u003cSomeDomainObject\u003e list)\n    {\n      // Convert objects to OM Points\n      final Point[] points = new Point[list.length];\n      for (int i = 0; i \u003c list.size; i++)\n      {\n        // Get lat, lon, and name from object and assign it to new Point\n        points[i] = new Point(lat, lon, name);\n      }\n      // Show all point on the map, you could also provide some title\n      Api.showPointsOnMap(this, \"Look at my points, my points are amazing!\", points);\n    }\n\n\n### Ask Organic Maps to Call my App\n\nWe support PendingIntent interaction (just like Android native\nNotificationManager does). You should specify ID for each point to\ndistinguish it later, and PendingIntent that Organic Maps will send back to\nyour application when user press \"More Info\" button :\n\n    // Here is how to pass points with ID ant PendingIntent\n    void showMultiplePointsWithPendingIntent(List\u003cSomeDomainObject\u003e list, PendingIntent pendingIntent)\n    {\n      // Convert objects to Points\n      final Point[] points = new Point[list.length];\n      for (int i = 0; i \u003c list.size; i++)\n      {\n        //                                      ||\n        //                                      ||\n        //                                      \\/\n        //         Now you should specify string ID for each point\n        points[i] = new Point(lat, lon, name, id);\n      }\n      // Show all points on the map, you could also provide some title\n      Api.showPointsOnMap(this, \"This title says that user should choose some point\", pendingIntent, points);\n    }\n\n    //Code below shows general way to extract response data\n    @Override\n    protected void onCreate(Bundle savedInstanceState) {\n        super.onCreate(savedInstanceState);\n        setContentView(R.layout.activity_main);\n        // Handle intent you specified with PandingIntent\n        // Now it has additional information (Point).\n        handleIntent(getIntent());\n    }\n\n    @Override\n    protected void onNewIntent(Intent intent)\n    {\n      super.onNewIntent(intent);\n      // if defined your activity as \"SingleTop\"- you should use onNewIntent callback\n      handleIntent(intent);\n    }\n\n    void handleIntent(Intent intent)\n    {\n      // Apply Response extraction method to intent\n      final Response mwmResponse = Response.extractFromIntent(this, intent);\n      // Here is your point that user selected\n      final Point point = mwmResponse.getPoint();\n      // Now, for instance you can do some work depending on point id\n      processUserInteraction(point.getId());\n    }\n\n## FAQ\n\n#### Which versions of Organic Maps support API calls?\n\nAll versions since 2022-07-26 and above support API calls.\n\n#### What will happen if I call for `Api.showPoint()` but Organic Maps application is not installed?\n\nNothing serious. API library will show simple dialog with gentle offer to download Organic Maps. You can see how it looks like below.\n\n![Please install us](site/images/dlg.png)\n\n## Sample Code and Application\n\n* [Sample Application Source Code][linkSampleSource]\n\n-------------------------------------------------------------------------------\n## API Code License\n\nCopyright (c) 2024, Organic Maps OÜ.\n\nCopyright (c) 2019, MY.COM B.V.\n\nCopyright (c) 2013, MapsWithMe GmbH.\n\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:\n\n* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.\n* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n[linkOM]: https://organicmaps.app/ \"Organic Maps\"\n[linkPIntent]: https://developer.android.com/reference/android/app/PendingIntent.html \"PendingIntent\"\n[linkRepo]: https://github.com/organicmaps/api-android \"GitHub Repository\"\n[linkLibProj]: https://developer.android.com/tools/projects/index.html#LibraryProjects \"Android Library Project\"\n[linkIntents]: https://developer.android.com/guide/components/intents-filters.html \"Intents and Intent Filters\"\n[linkApiClass]: lib/src/main/java/app/organicmaps/api/OrganicMapsApi.java \"OrganicMapsApi.java\"\n[linkPointClass]: lib/src/main/java/app/organicmaps/api/Point.java \"Point.java\"\n[linkRespClass]: lib/src/main/java/app/organicmaps/api/PickPointResponse.java  \"PickPointResponse.java\"\n[linkSampleSource]: https://github.com/organicmaps/api-android/tree/master/sample-app-capitals \"Api Source Code\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forganicmaps%2Fapi-android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forganicmaps%2Fapi-android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forganicmaps%2Fapi-android/lists"}