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
Leave a Reply