MAPCAT blog MAPCAT blog MAPCAT blog MAPCAT blog MAPCAT blog

How to create an easy Android application with MAPCAT?

The MAPCAT map APIs help you visualize and activate any location-based data on any platform and device. In this article our developer team helps you with developing an Android map app using the MAPCAT map API. Our assets were built in order to provide you easy integration and easy switch from other services. Follow the below steps and visualize beautiful OpenStreetMap-based vector map tiles in any language easily.

The author 

 

 

 

Ádám Papp

Software Engineer

Basic map elements

Let’s start with the assets you will need.
For the easier use, the digital map is cut into smaller parts, so-called tiles. These tiles include the map data for the given area. For the map visualization you will also need a new stylesheet, that enables our app to display the data stored in the tiles.

MAPCAT Visualization API provides stylesheets for the visualization based on the parameters given. Please request your API key on www.mapcat.com for free or by choosing the right plan.

MAPCAT Android SDK is a framework that handles both the stylesheet downloading and the map visualization, using the MAPCAT Visualization API key.

The MAPCAT map API serves out both raster and vector tiles, the MAPCAT Android SDK visualizes the map by using vector tiles.

Example Application

You can create this simple Android map application (shown in the picture above) in few minutes, by following the next steps.

Configure a new project

Make a new blank project. In the example we have used Android Studio as developer environment, but you can use other tools to create this example app. 

Don’t forget to choose the “Phone and Tablet” option when setting the “Target Android Device”. Set the minimum Android API level to at least 15. At the “Add an Activity to Mobile” step pick an empty activity.

You can find the MAPCAT Android SDK -needed for application- in the Maven Central.  Add the MavenCentral constructor  to the project’s build.gradle file repository list.

(SCRIPT:
// Top-level build file where you can add configuration options common to all sub-projects/modules.
buildscript {
   repositories {
       google()
       jcenter()
   }
   dependencies {
       classpath 'com.android.tools.build:gradle:3.1.1'
       // NOTE: Do not place your application dependencies here; they belong
       // in the individual module build.gradle files
   }
}
allprojects {
   repositories {
       google()
       jcenter()
       mavenCentral()
   }
}
task clean(type: Delete) {
   delete rootProject.buildDir
}
/SCRIPT)

Add the next lines to our applications build.gradle file dependence list :

implementation 'com.mapcat.mapcatsdk:mapcat-android-sdk:1.0.7'
implementation 'com.mapbox.mapboxsdk:mapbox-android-services:2.2.9'
(SCRIPT:
apply plugin: 'com.android.application'
android {
   compileSdkVersion 27
   defaultConfig {
       applicationId "com.example.mapcat.mapcattestapp"
       minSdkVersion 15
       targetSdkVersion 27
       versionCode 1
       versionName "1.0"
       testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
   }
   buildTypes {
       release {
           minifyEnabled false
           proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
       }
   }
}
dependencies {
   implementation fileTree(dir: 'libs', include: ['*.jar'])
   implementation 'com.android.support:appcompat-v7:27.1.1'
   implementation 'com.android.support.constraint:constraint-layout:1.1.0'
   implementation 'com.mapcat.mapcatsdk:mapcat-android-sdk:1.0.7'
   implementation 'com.mapbox.mapboxsdk:mapbox-android-services:2.2.9'
   testImplementation 'junit:junit:4.12'
   androidTestImplementation 'com.android.support.test:runner:1.0.1'
   androidTestImplementation 'com.android.support.test.espresso:espresso-core:3.0.1'
}
/SCRIPT)
Then, we need to add following line to the AndroidManifest.xml file within the app:
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

(SCRIPT
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
   package="com.example.mapcat.mapcattestapp">
   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   <application
       android:allowBackup="true"
       android:icon="@mipmap/ic_launcher"
       android:label="@string/app_name"
       android:roundIcon="@mipmap/ic_launcher_round"
       android:supportsRtl="true"
       android:theme="@style/AppTheme">
       <activity android:name=".MainActivity">
           <intent-filter>
               <action android:name="android.intent.action.MAIN" />
               <category android:name="android.intent.category.LAUNCHER" />
           </intent-filter>
       </activity>
   </application>
</manifest>
/SCRIPT)

After this the SDK can be used to visualize the MAPCAT map.

Map Visualization

In the activity_main.xml layout file change “Hello World” text to (TextView content) this:

<com.mapcat.mapcatsdk.maps.MapView 
android:id="@id/mapView" 
android:layout_width="match_parent" 
android:layout_height="match_parent"/>

For the initialization of MAPCAT map do the following steps.

Define a private variable for mapView. Then, in the onCreate () method, create a Mapcat instance using the API key we mentioned earlier. Finally, invite the initMAPCATMap function on mapView.

private MapView mapView;
@Override 
protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
Mapcat.getInstance(this, "< Your MAPCAT Visualization API key >"); 
setContentView(R.layout.activity_main); 
mapView = (MapView) findViewById(R.id.mapView); 
mapView.initMapcatMap(new LayerOptions(false, false)); 
mapView.onCreate(savedInstanceState); 
MapViewInitHandler.registerListener(this);
}

As you can see in the code above, the initMapcatMap () method parameter requires a LayerOptions object to control the display of cycling routes. The following pictures shows the same area with different bicycle road settings.

To handle errors from the MAPCAT Visualization API (such as trying to use a bad API key or network failure) we need both MapViewInitHandler class and MapViewInitListener interface from the MAPCAT Android SDK. With the help of the MapViewInitHandler, register our running application in the onCreate () method and also  in the onDestroy () method.

By implementing the MapViewInitError and onMapViewInitSuccess functions of the MapViewInitListener, we can manage the responses from the MAPCAT Visualization API.

@Override
public void onMapViewInitError(final String error) {
Log.i("MAPINIT", "Error: " + error);
}
@Override
public void onMapViewInitSuccess() {
Log.i("MAPINIT", "Success");
}

To use this application, we also have to implement the following functions in MainActivity as follows:

@Override
public void onStart() { 
super.onStart(); 
mapView.onStart(); 
} 
@Override
public void onResume() { 
super.onResume(); 
mapView.onResume(); 
} 
@Override
public void onPause() { 
super.onPause(); 
mapView.onPause();
} 
@Override
public void onStop() { 
super.onStop(); 
mapView.onStop(); 
} 
@Override
public void onLowMemory() { 
super.onLowMemory(); 
mapView.onLowMemory(); 
} 
@Override
protected void onDestroy() { 
super.onDestroy(); 
mapView.onDestroy(); 
MapViewInitHandler.unregisterListener(this);
} 
@Override
protected void onSaveInstanceState(Bundle outState) { 
super.onSaveInstanceState(outState); 
mapView.onSaveInstanceState(outState); 
}

Setting the map language

You can easily change the language of the map texts using the setLanguage () function of the mapView variable. The parameter of the function is a two-letter language code corresponding to ISO 639-1. 

With the following code line, you can change the map language to Chinese at the end of the onCreate () method

mapView.setLanguage(“zh”);

Assistance

Now, your Android map app is hopefully up and running.
In case you need further assistance with the MAPCAT APIs, please check our developer site or contact us with your questions at support@mapcat.com

 

Facebook
Google+
LINKEDIN
INSTAGRAM
PINTEREST
Try our API for free

Leave a Reply

Your email address will not be published.

I am not a robot *