Getting Started

Getting started with MapsGL is quick and easy and requires that you have an active Xweather Flex subscription (opens in a new tab). Also, check out our demo project (opens in a new tab) for a more in-depth example of integrating the MapsGL SDK with your app.

Supported Mapping Libraries

MapsGL SDK for Android currently supports integration with the following third-party mapping libraries:

Library + Version	Controller
Mapbox GL (opens in a new tab), version v11.3.0+	`MapboxMapController`

Installing

Our MapsGL SDK for Android is distributed as an AAR package that can be used with Android Studio. You can install the MapsGL SDK by adding the AAR package to your project's dependencies.

Follow the series of steps outlined below to get started using the Xweather MapsGL SDK for Android:

Create an Xweather account

Sign up for an Xweather Flex subscription (opens in a new tab) and setup your access keys as described in our Xweather Weather API's getting started guide (opens in a new tab). We offer a free developer account (opens in a new tab) for you to give our weather API a test drive.

Include the MapsGL SDK

Open your project's settings.gradle file and add a new maven {...} definition inside the dependencyResolutionManagement.repositories block and include the MapsGL repository:

pluginManagement {
    repositories {
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

Next, add the MapsGL SDK dependency to your project's app-level build.gradle Gradle configuration file:


dependencies {
    implementation 'com.github.vaisala-xweather:mapsgl-android-sdk:v1.0.1'
}

Set up a map view

Set up an interactive map instance using a supported third-party mapping library if your application does not have one already.

Set up MapsGL with your map

Set up your Xweather account access keys (opens in a new tab) for the SDK and create a map controller instance that corresponds to the mapping library you are using (see below).

Once you've completed the above installation steps, you can use the following Kotlin code snippet to get started quickly using Mapbox in your project. Make sure you also have Mapbox SDK set up in your project according to their Getting Started guide (opens in a new tab).

package com.example.basicmapsglproject
 
import android.os.Bundle
import android.view.ViewTreeObserver
import androidx.appcompat.app.AppCompatActivity
import com.example.basicmapsglproject.databinding.ActivityMainBinding
import com.mapbox.maps.MapLoadedCallback
import com.mapbox.maps.Style
import com.mapbox.maps.extension.style.layers.properties.generated.ProjectionName
import com.mapbox.maps.extension.style.projection.generated.projection
import com.mapbox.maps.extension.style.projection.generated.setProjection
import com.xweather.mapsgl.config.weather.account.XweatherAccount
import com.xweather.mapsgl.map.mapbox.MapboxMapController
import com.xweather.mapsgl.style.ParticleDensity
import com.xweather.mapsgl.style.ParticleTrailLength
import com.xweather.mapsgl.config.weather.WeatherService
 
class MainActivity : AppCompatActivity() {
 
    private lateinit var mapController: MapboxMapController
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
 
        setContentView(R.layout.activity_main)
 
        // Set up your Xweather account and access keys for the SDK
        var xweatherAccount = XweatherAccount(
            getString(R.string.xweather_client_id),
            getString(R.string.xweather_client_secret)
        )
 
        var binding = ActivityMainBinding.inflate(layoutInflater)
        setContentView(binding.root)
        var mapView = binding.mapView
 
        // Add functionality and data to your map once the controller's `load` event has been triggered:
        val mapLoadedCallback = MapLoadedCallback {
            // Add a Sample or Raster Layer:
            mapController.addWeatherLayer(WeatherService.Temperatures(mapController.service))
         
            // Add a Particle Layer:
            mapController.addWeatherLayer(WeatherService.WindParticles(mapController.service))
        }
 
        binding.mapView.viewTreeObserver.addOnGlobalLayoutListener(object : ViewTreeObserver.OnGlobalLayoutListener {
            override fun onGlobalLayout() {
                binding.mapView.viewTreeObserver.removeOnGlobalLayoutListener(this)
 
                // Create a map controller that corresponds to the selected mapping library, passing in your `mapView` and `xweatherAccount` instances.
                mapController = MapboxMapController(mapView, baseContext, xweatherAccount,this@MainActivity)
 
                with(mapController) {
                    mapboxMap.loadStyle(Style.LIGHT)
                    mapboxMap.setProjection(projection(ProjectionName.MERCATOR))
                    mapboxMap.subscribeMapLoaded(mapLoadedCallback)
                }
            }
        })
    }
}

Managing Weather Data

Adding and removing weather layers once you've created your map instance is simple. You'll need to use the weather layer configurations and provide any desired overrides to the default configuration.

Refer to the Weather Data documentation for more information on adding and removing weather data with your map.

Weather Layers Map Controller