Skip to main content

Get started

Create an API key at user.globus.software/apps, then choose a platform. The examples use Porto as the initial map position.

iOS​

Swift Package Manager is the reference iOS integration for GLMap.

Add the package​

In Xcode, select File → Add Package Dependencies and enter:

https://github.com/GLMap/GLMapSwift.git

Select Up to Next Major Version starting at 2.1.0. Add these products as needed:

  • GLMap — map rendering and Swift extensions
  • GLSearch — online and offline search
  • GLRoute — online and offline routing

For a manifest-based project:

.package(
    url: "https://github.com/GLMap/GLMapSwift.git",
    from: "2.1.0"
)

Activate GLMap​

Call activation once before creating a map view:

import GLMap
import GLMapSwift
import UIKit

@main
final class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _: UIApplication,
        didFinishLaunchingWithOptions _: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        GLMapManager.activate(apiKey: "YOUR_API_KEY")
        GLMapManager.shared.tileDownloadingAllowed = true
        return true
    }
}

Online tile downloading is disabled by default. Keep it disabled in an offline-only application.

Display a map​

GLMapView automatically loads DefaultStyle.bundle from the SPM resources configured during activation:

import GLMap
import GLMapSwift
import UIKit

final class MapViewController: UIViewController {
    private let map = GLMapView()

    override func viewDidLoad() {
        super.viewDidLoad()

        map.frame = view.bounds
        map.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(map)

        map.mapGeoCenter = GLMapGeoPoint(lat: 41.1579, lon: -8.6291)
        map.mapZoomLevel = 12
    }
}

Use GLMapStyleParser only to load a custom style or change style options. See Your first map.

The complete reference project is SwiftDemo.

CocoaPods​

CocoaPods remains available for existing Objective-C integrations. New Swift applications should use Swift Package Manager.

Android​

The Android reference project uses Kotlin, compileSdk 37, and targetSdk 37. The libraries support Android API 21 and later.

Add the repository and dependencies​

In settings.gradle:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://maven.globus.software/artifactory/libs") }
    }
}

In the application module's build.gradle:

android {
    compileSdk 37

    defaultConfig {
        minSdk 21
        targetSdk 37
    }
}

dependencies {
    implementation "globus:glmap:2.1.0"
    implementation "globus:glsearch:2.1.0" // optional
    implementation "globus:glroute:2.1.0"  // optional
}

globus:glmap:2.1.0 pulls the matching default style automatically. Do not add a separate style version.

Activate GLMap​

import android.app.Application
import globus.glmap.GLMapManager
import globus.glsearch.GLSearch

class App : Application() {
    override fun onCreate() {
        super.onCreate()

        check(GLMapManager.Initialize(this, "YOUR_API_KEY", null)) {
            "GLMap initialization failed. Check the API key and free storage."
        }
        GLMapManager.SetTileDownloadingAllowed(true)

        // Required only when the application uses GLSearch.
        GLSearch.Initialize(this)
    }
}

Register the class in AndroidManifest.xml:

<application
    android:name=".App"
    ... />

Display a map​

Android loads the default style when GLMapView is created:

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import globus.glmap.GLMapView
import globus.glmap.MapGeoPoint

class MapActivity : AppCompatActivity() {
    private lateinit var map: GLMapView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        map = GLMapView(this)
        setContentView(map)
        map.renderer.mapGeoCenter = MapGeoPoint(41.1579, -8.6291)
        map.renderer.mapZoom = 12.0
    }

    override fun onDestroy() {
        map.dispose()
        super.onDestroy()
    }
}

The complete reference project is kotlinDemo.

Before switching to airplane mode​

The setup above enables online tile downloads. To use the same application offline, download the required regional data first, then select offline search and routing explicitly.

1. Download the region and the data you need​

In either reference app, open Offline Data → Download Maps and select the region covering your test area. The setup on this page and the Route Building examples start in Porto, Portugal; download the region containing Porto to use their default coordinates.

FeatureRequired offline data
Map displayMap dataset
Address and POI searchThe same map dataset; no separate search download
Route calculationNavigation dataset
Terrain and elevation displayAdditional elevation data for the features you enable

The reference download screens request all available datasets for the selected region. In your application, select only the datasets your features need:

The Search screen in each reference app uses a bundled Montenegro map and starts in Podgorica. To test your downloaded Porto map instead, change the search example's center to the Porto coordinates above. The separate Download BBox example downloads a small area in Florence; it does not cover Porto. Keep the data coverage and example coordinates aligned.

2. Check readiness for each dataset​

Wait for each required download to finish successfully. A visible map, a completed map download, or an entry under On Device does not establish that navigation data is ready.

  • iOS: observe GLMapInfo.stateChanged and inspect info.state(for: .map) and info.state(for: .navigation). Check task.error in each download completion callback.
  • Android: use GLMapManager.StateListener and inspect info.getState(GLMapInfo.DataSet.MAP) and info.getState(GLMapInfo.DataSet.NAVIGATION). Check the task error in onFinishDownloading.

For a fresh successful download, each required dataset should report downloaded on iOS or DOWNLOADED on Android. An already installed dataset can instead report needUpdate / NEED_UPDATE: local data is present, but a newer snapshot is available. Download progress reaching 100% alone is not the readiness check.

These checks apply to regional downloads managed by GLMapManager. The bounding-box example additionally registers each downloaded file with the manager before reporting success.

3. Select offline operations​

Disable automatic map tile fetching in your application:

GLMapManager.shared.tileDownloadingAllowed = false
GLMapManager.SetTileDownloadingAllowed(false)

This setting controls map tiles. Search and routing have their own choice of transport:

4. Try fresh requests without a connection​

Turn on airplane mode and ensure Wi-Fi is also off. Within the downloaded region:

  1. Pan and zoom to an area you have not just viewed.
  2. Search for an address or POI you have not just searched for.
  3. Change a route endpoint and calculate a new route.
  4. Restart the application and repeat to check that it uses the installed data.

For a cross-region route, download navigation data covering a usable path between the endpoints, including intermediate regions. Having data around both endpoints alone is not enough. If the downloaded graph has no usable connecting path, offline routing cannot complete the route; handle the request's error callback. With partial coverage, a successful route may differ from the route available with complete data. Offline routing cannot fetch missing graph data from the network.

Map updates are published as full snapshots once a month; delta updates are not currently available. Downloading an update does not interrupt offline use of the installed data.

Next steps​