Skip to main content

Your First Map

Learn how to display a map in your iOS or Android app using GLOBUS SDK.

What You'll Build​

A simple app that displays an interactive map centered on a specific location. Users will be able to pan, zoom, and explore the map.

Time to complete: ~10 minutes

Prerequisites​

Choose Your Platform​

📱 iOS (Swift)

Step 1: Import GLMap​

In your view controller file:

import UIKit
import GLMap
import GLMapSwift

Step 2: Create Map View​

Add a GLMapView property to your view controller:

class ViewController: UIViewController {
    var mapView: GLMapView!

    override func viewDidLoad() {
        super.viewDidLoad()

        // Create and configure map view
        mapView = GLMapView(frame: view.bounds)
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(mapView)
    }
}

The default map style loads automatically. You only need to load a style if you're using a custom one.

Step 3: Set Initial Camera Position​

Position the map at a specific location and zoom level:

override func viewDidLoad() {
    super.viewDidLoad()

    mapView = GLMapView(frame: view.bounds)
    mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
    view.addSubview(mapView)

    // Set initial position - San Francisco
    mapView.mapGeoCenter = GLMapGeoPoint(lat: 37.7749, lon: -122.4194)
    mapView.mapZoomLevel = 12
}

Complete Code​

Here's the complete view controller:

import UIKit
import GLMap
import GLMapSwift

class ViewController: UIViewController {
    var mapView: GLMapView!

    override func viewDidLoad() {
        super.viewDidLoad()

        // Create map view
        mapView = GLMapView(frame: view.bounds)
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(mapView)

        // Set initial position
        mapView.mapGeoCenter = GLMapGeoPoint(lat: 37.7749, lon: -122.4194)
        mapView.mapZoomLevel = 12
    }
}

Run Your App​

Build and run your app. You should see an interactive map of San Francisco!

🤖 Android (Kotlin)

Step 1: Add Map View to Layout​

Create or open your layout file (activity_main.xml):

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <globus.glmap.GLMapView
        android:id="@+id/map_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
</FrameLayout>

Step 2: Initialize Map View​

In your MainActivity.kt:

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

class MainActivity : AppCompatActivity() {
    private lateinit var mapView: GLMapView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Get reference to map view
        mapView = findViewById(R.id.map_view)
    }
}

The default map style loads automatically. You only need to load a style if you're using a custom one.

Step 3: Set Initial Camera Position​

Position the map at a specific location:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    mapView = findViewById(R.id.map_view)

    // Set initial position - San Francisco
    mapView.renderer.setMapGeoCenter(MapGeoPoint(37.7749, -122.4194))
    mapView.renderer.mapZoom = 12f
}

Complete Code​

Here's the complete activity:

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

class MainActivity : AppCompatActivity() {
    private lateinit var mapView: GLMapView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Initialize map view
        mapView = findViewById(R.id.map_view)

        // Set initial position - San Francisco
        mapView.renderer.setMapGeoCenter(MapGeoPoint(37.7749, -122.4194))
        mapView.renderer.mapZoom = 12f
    }
}

Run Your App​

Build and run your app. You should see an interactive map of San Francisco!

Understanding the Code​

GLMapView​

GLMapView is the main view component that displays the map:

  • iOS: Subclass of UIView
  • Android: Custom view extending View

Map Styles​

GLOBUS uses MapCSS for styling. The default style loads automatically and includes:

  • Vector tile rendering rules
  • Colors, fonts, and icons
  • Zoom-level specific rendering

To use a custom style, call mapView.loadStyle(path) after creating the map view (see MapCSS Reference)

Camera Position​

The map camera is controlled by two properties:

  • mapGeoCenter (iOS) / setMapGeoCenter() (Android)

    • Sets the geographic center point
    • Uses GLMapGeoPoint / MapGeoPoint with latitude/longitude

  • mapZoomLevel (iOS) / mapZoom (Android)

    • Controls zoom level (0-20+)
    • Higher values = more zoomed in
    • Level 12 is good for city-level view

Coordinate Systems​

// iOS
let center = GLMapGeoPoint(lat: 37.7749, lon: -122.4194)
mapView.mapGeoCenter = center
// Android
val center = MapGeoPoint(37.7749, -122.4194)
mapView.renderer.setMapGeoCenter(center)

Note: Latitude is first, longitude is second (unlike some mapping SDKs).

Try It Out​

Experiment with different locations and zoom levels:

LocationLatitudeLongitudeZoom
San Francisco37.7749-122.419412
London51.5074-0.127811
Tokyo35.6762139.650312
Sydney-33.8688151.209312

Troubleshooting​

Map is blank or shows loading:

  • Check your API key is valid
  • Ensure internet connectivity for initial tile download
  • Tiles are cached after first download for offline use

App crashes on launch:

  • Ensure GLMapManager.activate() (iOS) or GLMapManager.Initialize() (Android) is called before creating map view
  • Check the Get Started Guide for proper initialization

Custom style not loading:

  • Verify the style bundle path is correct
  • Ensure the style bundle is included in your app's resources
  • For iOS: Check that the style bundle is in your target's "Copy Bundle Resources"
  • For Android: Ensure the style bundle is in assets folder

What's Next?​

Now that you have a working map, try these tutorials:

More Resources​