Step by Step First Application

Getting started with the Woosmap Android SDK

  1. Creating your first Application
  2. Adding a Map View

This guide will show you how to set up the Woosmap Android SDK and display a simple map. This is a step-by-step guide that assume no previous knowledge of Android development.

Creating your first Application

Android Development Tools

To create our Android app we will need some environment configuration and tools. Luckily everything can be done by just downloading and installing Android Studio on your machine. If you leave all configuration by default it will prepare everything for you.

Starting a new Project

Once started you will be welcomed by a first panel inviting you to create or open a project.

Android Studio First Panel

You can click a new project, it’ll then ask you to pick a template: let’s start with an Empty Views Activity.

Android Studio Template Selection

Now it’s time to configure the basics of your project, give it a name as well as a package name. We recommend to use Kotlin as a programming language but if you rather go with Java instead, no worries, this tutorial will provide you with both code samples. The minimum SDK version is up to you, older version means that you might have to handle more ways to do the same thing for compatibility purpose but covers more existing phone that aren’t updated. Our SDK can be used with Android API 21 and above (Android 5.0 Lollipop).

Android API Version and Android Platform Versions are different. You can find more information and a compatibility list here

When it comes to the Build Configuration Language we highly recommend to keep Kotlin DSL.

Android Studio Project Configuration

Once done Android Studio will create all the files for your project and start indexing and downloading the template’s dependencies. It might take a little time depending on your disk and network speed. Eventually you will see something very similar to the next image.

Android Studio Ready

Configuring the project to use Woosmap Android SDK

Before we start we’ll need to talk about Gradle if you are already familiar with it, you can skip the next part.


Android projects are configured and built by a tool named Gradle. It fulfills a similar role that you might have encountered using tools like Make, NPM, etc… However, Gradle gets configured mostly by code and this code-configuration highly depends on which plugins are activated. In our case the biggest one is the Android Gradle Plugin also known as AGP. By using Android Studio’s template our project comes with a set of files already all preconfigured, including AGP, which will allow us to build a simple application.

It’s important to note the structure of Gradle’s files:

Android Studio has an Android View and a Project View. The former is the default and tends to help focus while developing, the latter is a representation of how the files are laid out on disk.

Gradle Files

We strongly recommend to use Kotlin for Gradle scripts. Luckily since Android Studio 2022.3.1 it’s the default but if you are on an existing project and want to learn how and why make the switch follow this guide.

Adding Woosmap Android SDK to the project dependencies

Add our repository in your configuration in order for Gradle to be able to download the SDK as a dependency. At the root of your project in your settings.gradle.kts add the following :

Add our Maven repository
        dependencyResolutionManagement {
    repositories {
        maven {
            url = uri("")

        dependencyResolutionManagement {
    repositories {
        maven {
            url ""


Then you can add the dependency to our SDK in your gradle’s build.gradle.kts module-level file

Add the dependency
        dependencies {

        dependencies {
    implementation "com.woosmap:sdk:0.9.0"


Create your API Key

In order to use our service from a mobile, you will need to create a Private API Key with the proper restriction in the console. If you don’t know how, you can follow the directions specified in the API Key documentation

You will need to provide two information from your application to create the API Key:

Configure your API Key

In order to authenticate your application you will need to add a meta-data information to specify your private key in the AndroidManifest.xml in your application’s tag like so:

        <!-- ... -->
            android:value="YOUR PRIVATE KEY HERE" />


Adding a Map View

Open your res/layout/activity_main.xml and make sure to switch into code view. The default view contains only a TextView setup to take the whole application screen, we’re going to replace it with a MapView instead.

        android:layout_height="match_parent" />

        <?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android=""

        app:layout_constraintTop_toTopOf="parent" />



In your activity’s code you can then obtain and manipulate the MapView.

import android.os.Bundle
import com.woosmap.sdk.MapView
import com.woosmap.sdk.geometry.LatLng

class MainActivity : AppCompatActivity() {

    private lateinit var mapView: MapView

    override fun onCreate(savedInstanceState: Bundle?) {
        mapView = findViewById(
        mapView.zoomLevel = 3.0 = LatLng(47.7724413, 12.4833043)

import com.woosmap.sdk.MapView;
import com.woosmap.sdk.geometry.LatLng;

import android.os.Bundle;

public class MainActivity extends AppCompatActivity {

    private MapView MapView;

    protected void onCreate(Bundle savedInstanceState) {

        MapView = findViewById(;
        MapView.setCenter(new LatLng(47.7724413, 12.4833043));


You’re all set, you can start the application on your phone or the emulator and should see something like the picture below.

Woosmap Demo Screenshot

Was this article helpful?
Have more questions? Submit a request