├── .gitignore ├── README.html ├── README.md ├── lib ├── AndroidManifest.xml ├── build.gradle ├── build.xml ├── project.properties ├── res │ ├── drawable │ │ ├── background_pattern.xml │ │ ├── btn_back_gray.xml │ │ ├── btn_back_gray_active.xml │ │ ├── btn_back_green.xml │ │ ├── btn_back_green_active.xml │ │ ├── btn_gray_selector.xml │ │ ├── btn_green_selector.xml │ │ ├── gray.xml │ │ ├── green.xml │ │ ├── overflow.xml │ │ ├── pattern.png │ │ └── shadow.xml │ ├── layout │ │ └── dlg_install_mwm.xml │ └── values │ │ ├── strings.xml │ │ └── styles.xml └── src │ └── com │ └── mapswithme │ └── maps │ └── api │ ├── Const.java │ ├── DownloadMapsWithMeDialog.java │ ├── MWMPoint.java │ ├── MWMResponse.java │ ├── MapsWithMeApi.java │ └── MwmRequest.java ├── readme_to_html.sh ├── sample-app-capitals ├── AndroidManifest.xml ├── build.gradle ├── build.xml ├── project.properties ├── res │ ├── drawable-hdpi │ │ └── ic_launcher.png │ ├── drawable-ldpi │ │ └── ic_launcher.png │ ├── drawable-mdpi │ │ └── ic_launcher.png │ ├── drawable-xhdpi │ │ └── ic_launcher.png │ ├── drawable-xxhdpi │ │ └── ic_launcher.png │ ├── layout │ │ ├── capitals_list_activity.xml │ │ └── city_details_activity.xml │ ├── values-sw720dp-land │ │ └── dimens.xml │ ├── values-v11 │ │ └── styles.xml │ ├── values-v14 │ │ └── styles.xml │ └── values │ │ ├── dimens.xml │ │ ├── strings.xml │ │ └── styles.xml └── src │ └── com │ └── mapswithme │ └── capitals │ ├── CapitalsListActivity.java │ ├── City.java │ └── CityDetailsActivity.java └── site └── images └── dlg.png /.gitignore: -------------------------------------------------------------------------------- 1 | bin/ 2 | gen/ 3 | build/ 4 | .settings/ 5 | 6 | .DS_Store 7 | .classpath 8 | .cproject 9 | .project 10 | local.properties 11 | lint.xml -------------------------------------------------------------------------------- /README.html: -------------------------------------------------------------------------------- 1 |

maps.me Android API: Getting Started

2 | 3 |

Introduction

4 | 5 |

NOTE: We have changed the name of our maps from MapsWithMe to MAPS.ME, but left all references below unchanged.

6 | 7 |

MapsWithMe Android API (hereinafter referred to as "API Library" or just "library") 8 | provides interface for client application to perform next tasks:

9 | 10 | 15 | 16 |

Thus, you can provide two way communication between your application and MapsWithMe, 17 | using MapsWithMe to show points of interest (POI) and providing more information in your app.

18 | 19 |

Please refer to sample application for demo or see 20 | our travel guide apps as an API integration example.

21 | 22 |

Prerequisites

23 | 24 |

It is supposed that you are familiar with Android Development, and you have Android SDK and Eclipse (or another IDE of your choice) installed. 25 | You should be familiar with concept of Intents, library projects, and PendingIntents (recommended) as well. 26 | Your application must target at least android sdk version 9.

27 | 28 |

Integration

29 | 30 |

First step is to clone repository or download it as an archive.

31 | 32 |

When 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. 33 | You 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 MapsWithMeApi methods (more details below).

34 | 35 |

Classes Overview and HOW TO

36 | 37 |

Core classes you will work with are:

38 | 39 | 44 | 45 |

Show Points on the Map

46 | 47 |

The simplest usage:

48 | 49 |
public class MyPerfectActivity extends Activity {
 50 | ...
 51 | 
 52 |   void showSomethingOnTheMap(SomeDomainObject arg)
 53 |   {
 54 |     // Do some work, create lat, lon, and name for point
 55 |     final double lat = ...;
 56 |     final double lon = ...;
 57 |     final String name = ...;
 58 |     // Ask MapsWithMe to show the point
 59 |     MapsWithMeApi.showPointOnMap(this, lat, lon, name);
 60 |   }
 61 | ...
 62 | 
 63 | }
 64 | 
65 | 66 |

For multiple points use MWMPoint class:

67 | 68 |
void showMultiplePoints(List<SomeDomainObject> list)
 69 | {
 70 |   // Convert objects to MMWPoints
 71 |   final MWMPoint[] points = new MWMPoint[list.length];
 72 |   for (int i = 0; i < list.size; i++)
 73 |   {
 74 |     // Get lat, lon, and name from object and assign it to new MMWPoint
 75 |     points[i] = new MWMPoint(lat, lon, name);
 76 |   }
 77 |   // Show all point on the map, you could also provide some title
 78 |   MapsWithMeApi.showPointsOnMap(this, "Look at my points, my points are amazing!", points);
 79 | }
 80 | 
81 | 82 |

Ask MapsWithMe to Call my App

83 | 84 |

We support PendingIntent interaction (just like Android native 85 | NotificationManager does). You should specify ID for each point to 86 | distinguish it later, and PentingIntent that MapsWithMe will send back to 87 | your application when user press "More Info" button :

88 | 89 |
// Here is how to pass points with ID ant PendingIntent
 90 | void showMultiplePointsWithPendingIntent(List<SomeDomainObject> list, PendingIntent pendingIntent)
 91 | {
 92 |   // Convert objects to MWMPoints
 93 |   final MWMPoint[] points = new MWMPoint[list.length];
 94 |   for (int i = 0; i < list.size; i++)
 95 |   {
 96 |     //                                      ||
 97 |     //                                      ||
 98 |     //                                      \/
 99 |     //         Now you should specify string ID for each point
100 |     points[i] = new MWMPoint(lat, lon, name, id);
101 |   }
102 |   // Show all points on the map, you could also provide some title
103 |   MapsWithMeApi.showPointsOnMap(this, "This title says that user should choose some point", pendingIntent, points);
104 | }
105 | 
106 | //Code below shows general way to extract response data
107 | @Override
108 | protected void onCreate(Bundle savedInstanceState) {
109 |     super.onCreate(savedInstanceState);
110 |     setContentView(R.layout.activity_main);
111 |     // Handle intent you specified with PandingIntent
112 |     // Now it has additional information (MWMPoint).
113 |     handleIntent(getIntent());
114 | }
115 | 
116 | @Override
117 | protected void onNewIntent(Intent intent)
118 | {
119 |   super.onNewIntent(intent);
120 |   // if defined your activity as "SingleTop"- you should use onNewIntent callback
121 |   handleIntent(intent);
122 | }
123 | 
124 | void handleIntent(Intent intent)
125 | {
126 |   // Apply MWMResponse extraction method to intent
127 |   final MWMResponse mwmResponse = MWMResponse.extractFromIntent(this, intent);
128 |   // Here is your point that user selected
129 |   final MWMPoint point = mwmResponse.getPoint();
130 |   // Now, for instance you can do some work depending on point id
131 |   processUserInteraction(point.getId());
132 | }
133 | 
134 | 135 |

FAQ

136 | 137 |

How should I detect if user has MapsWithMe installed?

138 | 139 |

MapsWithMeApi.isMapsWithMeInstalled(Context) will return true if user has Lite or Pro version that supports API call installed.

140 | 141 |

Which versions of MapsWithMe support API calls?

142 | 143 |

All versions since 2.4.0 and above support API calls.

144 | 145 |

What will happen if I call for MapsWithMeApi.showPoint() but MapsWithMe application is not installed?

146 | 147 |

Nothing serious. API library will show simple dialog with gentle offer to download MapsWithMe. You can see how it looks like below. Please install us

148 | 149 |

Sample Code and Application

150 | 151 | 155 | 156 |

Support

157 | 158 |

If you have any questions please email to api@mapswith.me.

159 | 160 |
161 | 162 |

API Code License

163 | 164 |

Copyright (c) 2014, MapsWithMe GmbH 165 | All rights reserved.

166 | 167 |

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

168 | 169 | 173 | 174 |

THIS 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.

175 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # maps.me Android API: Getting Started 2 | 3 | ## Introduction 4 | 5 | NOTE: We have changed the name of our maps from MapsWithMe to MAPS.ME, but left all references below unchanged. 6 | 7 | MapsWithMe Android API (hereinafter referred to as *"API Library"* or just *"library"*) 8 | provides interface for client application to perform next tasks: 9 | 10 | * Show one or more points on offline map of [MapsWithMe Application][linkMwm] 11 | * 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 MapsWithMe Application 12 | * Map screen branding : your application's icon and name (or custom title) will be placed at the top. 13 | 14 | Thus, you can provide **two way communication between your application and MapsWithMe**, 15 | using MapsWithMe to show points of interest (POI) and providing more information in your app. 16 | 17 | Please refer to [sample application][linkSampleSource] for demo or see 18 | our [travel guide apps][linkTravelGuides] as an API integration example. 19 | 20 | ## Prerequisites 21 | 22 | It is supposed that you are familiar with Android Development, and you have Android SDK and Eclipse (or another IDE of your choice) installed. 23 | You should be familiar with concept of [Intents][linkIntents], [library projects][linkLibProj], and [PendingIntents][linkPIntent] (recommended) as well. 24 | Your application must target at least *android sdk version 9*. 25 | 26 | ## Integration 27 | First step is to clone [repository][linkRepo] or download it as an archive. 28 | 29 | When 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. 30 | You 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 `MapsWithMeApi` methods (more details below). 31 | 32 | ## Classes Overview and HOW TO 33 | Core classes you will work with are: 34 | 35 | * [com.mapswithme.maps.api.MapsWithMeApi][linkApiClass] - static class with methods such as `showPointOnMap(Activity, double, double, String)` etc. 36 | * [com.mapswithme.maps.api.MWMPoint][linkPointClass] - model of POI, includes lat, lon, name, id, and style data. 37 | * [com.mapswithme.maps.api.MWMResponse][linkRespClass] - helps you to extract response from MapsWithMe by applying `MWMResponse.extractFromIntent(Intent)` to Intent. Contains MWMPoint data. 38 | 39 | ### Show Points on the Map 40 | 41 | The simplest usage: 42 | 43 | public class MyPerfectActivity extends Activity { 44 | ... 45 | 46 | void showSomethingOnTheMap(SomeDomainObject arg) 47 | { 48 | // Do some work, create lat, lon, and name for point 49 | final double lat = ...; 50 | final double lon = ...; 51 | final String name = ...; 52 | // Ask MapsWithMe to show the point 53 | MapsWithMeApi.showPointOnMap(this, lat, lon, name); 54 | } 55 | ... 56 | 57 | } 58 | 59 | For multiple points use [MWMPoint][linkPointClass] class: 60 | 61 | void showMultiplePoints(List list) 62 | { 63 | // Convert objects to MMWPoints 64 | final MWMPoint[] points = new MWMPoint[list.length]; 65 | for (int i = 0; i < list.size; i++) 66 | { 67 | // Get lat, lon, and name from object and assign it to new MMWPoint 68 | points[i] = new MWMPoint(lat, lon, name); 69 | } 70 | // Show all point on the map, you could also provide some title 71 | MapsWithMeApi.showPointsOnMap(this, "Look at my points, my points are amazing!", points); 72 | } 73 | 74 | 75 | ### Ask MapsWithMe to Call my App 76 | 77 | We support PendingIntent interaction (just like Android native 78 | NotificationManager does). You should specify ID for each point to 79 | distinguish it later, and PentingIntent that MapsWithMe will send back to 80 | your application when user press "More Info" button : 81 | 82 | // Here is how to pass points with ID ant PendingIntent 83 | void showMultiplePointsWithPendingIntent(List list, PendingIntent pendingIntent) 84 | { 85 | // Convert objects to MWMPoints 86 | final MWMPoint[] points = new MWMPoint[list.length]; 87 | for (int i = 0; i < list.size; i++) 88 | { 89 | // || 90 | // || 91 | // \/ 92 | // Now you should specify string ID for each point 93 | points[i] = new MWMPoint(lat, lon, name, id); 94 | } 95 | // Show all points on the map, you could also provide some title 96 | MapsWithMeApi.showPointsOnMap(this, "This title says that user should choose some point", pendingIntent, points); 97 | } 98 | 99 | //Code below shows general way to extract response data 100 | @Override 101 | protected void onCreate(Bundle savedInstanceState) { 102 | super.onCreate(savedInstanceState); 103 | setContentView(R.layout.activity_main); 104 | // Handle intent you specified with PandingIntent 105 | // Now it has additional information (MWMPoint). 106 | handleIntent(getIntent()); 107 | } 108 | 109 | @Override 110 | protected void onNewIntent(Intent intent) 111 | { 112 | super.onNewIntent(intent); 113 | // if defined your activity as "SingleTop"- you should use onNewIntent callback 114 | handleIntent(intent); 115 | } 116 | 117 | void handleIntent(Intent intent) 118 | { 119 | // Apply MWMResponse extraction method to intent 120 | final MWMResponse mwmResponse = MWMResponse.extractFromIntent(this, intent); 121 | // Here is your point that user selected 122 | final MWMPoint point = mwmResponse.getPoint(); 123 | // Now, for instance you can do some work depending on point id 124 | processUserInteraction(point.getId()); 125 | } 126 | 127 | ## FAQ 128 | 129 | #### How should I detect if user has MapsWithMe installed? 130 | `MapsWithMeApi.isMapsWithMeInstalled(Context)` will return `true` if user has *Lite* or *Pro* version that supports API call installed. 131 | 132 | #### Which versions of MapsWithMe support API calls? 133 | All versions since 2.4.0 and above support API calls. 134 | 135 | #### What will happen if I call for `MapsWithMeApi.showPoint()` but MapsWithMe application is not installed? 136 | Nothing serious. API library will show simple dialog with gentle offer to download MapsWithMe. You can see how it looks like below. 137 | 138 | ![Please install us](site/images/dlg.png) 139 | 140 | ## Sample Code and Application 141 | 142 | * [Sample Application at Google Play][linkSampleGooglePlay] 143 | * [Sample Application Source Code][linkSampleSource] 144 | 145 | ------------------------------------------------------------------------------- 146 | ## API Code License 147 | Copyright (c) 2019, MY.COM B.V. 148 | All rights reserved. 149 | 150 | Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 151 | 152 | * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 153 | * 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. 154 | 155 | THIS 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. 156 | 157 | [linkMwm]: https://maps.me/ "MAPS.ME" 158 | [linkPIntent]: http://developer.android.com/reference/android/app/PendingIntent.html "PendingIntent" 159 | [linkRepo]: https://github.com/mapswithme/api-android "GitHub Repository" 160 | [linkLibProj]: http://developer.android.com/tools/projects/index.html#LibraryProjects "Android Library Project" 161 | [linkIntents]: http://developer.android.com/guide/components/intents-filters.html "Intents and Intent Filters" 162 | [linkApiClass]: lib/src/com/mapswithme/maps/api/MapsWithMeApi.java "MapsWithMeApi.java" 163 | [linkPointClass]: lib/src/com/mapswithme/maps/api/MWMPoint.java "MWMPoint.java" 164 | [linkRespClass]: lib/src/com/mapswithme/maps/api/MWMResponse.java "MWMResponse.java" 165 | [linkSampleSource]: https://github.com/mapswithme/api-android/tree/master/sample-app-capitals "Api Source Code" 166 | [linkSampleGooglePlay]: http://play.google.com/store/apps/details?id=com.mapswithme.capitals "Api Demo .apk" 167 | [linkTravelGuides]: http://www.guidewithme.com 168 | -------------------------------------------------------------------------------- /lib/AndroidManifest.xml: -------------------------------------------------------------------------------- 1 | 5 | 6 | 7 | 8 | -------------------------------------------------------------------------------- /lib/build.gradle: -------------------------------------------------------------------------------- 1 | apply plugin: 'android-library' 2 | 3 | android { 4 | 5 | // Define these properties in the gradle.properties file in the root project folder 6 | compileSdkVersion propTargetSdkVersion.toInteger() 7 | buildToolsVersion propBuildToolsVersion 8 | 9 | defaultConfig { 10 | minSdkVersion propMinSdkVersion.toInteger() 11 | targetSdkVersion propTargetSdkVersion.toInteger() 12 | } 13 | 14 | sourceSets.main { 15 | manifest.srcFile 'AndroidManifest.xml' 16 | java.srcDirs = ['src'] 17 | res.srcDirs = ['res'] 18 | } 19 | } 20 | -------------------------------------------------------------------------------- /lib/build.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 7 | 8 | 9 | 29 | 30 | 31 | 35 | 36 | 37 | 38 | 39 | 40 | 49 | 50 | 51 | 52 | 56 | 57 | 69 | 70 | 71 | 89 | 90 | 91 | 92 | 93 | -------------------------------------------------------------------------------- /lib/project.properties: -------------------------------------------------------------------------------- 1 | # This file is automatically generated by Android Tools. 2 | # Do not modify this file -- YOUR CHANGES WILL BE ERASED! 3 | # 4 | # This file must be checked in Version Control Systems. 5 | # 6 | # To customize properties used by the Ant build system edit 7 | # "ant.properties", and override values to adapt the script to your 8 | # project structure. 9 | # 10 | # To enable ProGuard to shrink and obfuscate your code, uncomment this (available properties: sdk.dir, user.home): 11 | #proguard.config=${sdk.dir}/tools/proguard/proguard-android.txt:proguard-project.txt 12 | 13 | # Project target. 14 | target=android-21 15 | android.library=true 16 | -------------------------------------------------------------------------------- /lib/res/drawable/background_pattern.xml: -------------------------------------------------------------------------------- 1 | 2 | 6 | -------------------------------------------------------------------------------- /lib/res/drawable/btn_back_gray.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 12 | 13 | -------------------------------------------------------------------------------- /lib/res/drawable/btn_back_gray_active.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 13 | 14 | 15 | 16 | -------------------------------------------------------------------------------- /lib/res/drawable/btn_back_green.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 13 | 14 | -------------------------------------------------------------------------------- /lib/res/drawable/btn_back_green_active.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 13 | 14 | 15 | 16 | -------------------------------------------------------------------------------- /lib/res/drawable/btn_gray_selector.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | -------------------------------------------------------------------------------- /lib/res/drawable/btn_green_selector.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | -------------------------------------------------------------------------------- /lib/res/drawable/gray.xml: -------------------------------------------------------------------------------- 1 | 2 | 4 | 5 | 6 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /lib/res/drawable/green.xml: -------------------------------------------------------------------------------- 1 | 2 | 4 | 6 | 7 | 12 | 13 | 14 | 15 | -------------------------------------------------------------------------------- /lib/res/drawable/overflow.xml: -------------------------------------------------------------------------------- 1 | 2 | 4 | 5 | 6 | -------------------------------------------------------------------------------- /lib/res/drawable/pattern.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mapsme/api-android/baba74f75d4a1bff0473ab6036e9148a10a4472b/lib/res/drawable/pattern.png -------------------------------------------------------------------------------- /lib/res/drawable/shadow.xml: -------------------------------------------------------------------------------- 1 | 2 | 4 | 12 | 13 | -------------------------------------------------------------------------------- /lib/res/layout/dlg_install_mwm.xml: -------------------------------------------------------------------------------- 1 | 2 | 24 | 28 | 29 | 37 | 38 | 47 | 48 |