Frequently Asked Questions

Common questions and solutions for GLOBUS SDK.

Getting Started

How do I get an API key?

Create a free API key at user.globus.software. For enterprise licensing or evaluation keys, contact [email protected].

What platforms are supported?

• iOS: iOS 13.0 and later (iPhone, iPad, Mac Catalyst)
• macOS: macOS 11.0 and later (AppKit)
• Android: API level 21 (Android 5.0) and later
• Flutter: In active development (contact [email protected] for early access)

Is there a free trial?

Yes! Create a free API key at user.globus.software to evaluate the SDK. Free tier includes:

• Full SDK functionality
• Unlimited development usage
• Map tile downloads (fair use policy)

For production deployment, contact [email protected] for pricing.

---

Installation & Setup

"DefaultStyle.bundle not found" error

iOS:

• Verify GLMap framework is properly linked in your Xcode project
• Check that the framework appears in "Frameworks, Libraries, and Embedded Content"
• Clean build folder (Cmd+Shift+K) and rebuild

Android:

• Ensure implementation 'globus:glmap:1.12.0' is in your build.gradle
• Verify Maven repository is added to settings.gradle:

  maven { url 'https://maven.globus.software/artifactory/libs' }

• Sync Gradle and rebuild

Swift Package Manager installation fails

Common causes:

1. GitHub rate limit: Wait an hour or authenticate with GitHub
2. Xcode version: Requires Xcode 14+ for SPM support
3. Network issues: Check firewall/VPN settings

Solution:

• Try CocoaPods as an alternative: pod 'GLMap'
• Clear SPM cache: File → Packages → Reset Package Caches

CocoaPods installation issues

# Update CocoaPods repo
pod repo update

# If that fails, remove and re-add
pod repo remove trunk
pod setup

Then retry pod install.

---

Map Display

Map is blank or not loading

Possible causes:

1. API key not set or invalid

   // iOS - Verify this is called before creating map view
   GLMapManager.activate(apiKey: "YOUR_API_KEY")

   // Android - Verify Application.onCreate()
   GLMapManager.Initialize(this, "YOUR_API_KEY", null)

2. No internet connection (first launch)

   • Initial tiles require internet download
   • After first load, tiles are cached for offline use

3. Style not loaded

   // iOS - Check return value
   if let stylePath = GLMapManager.shared.resourcesBundle.path(
       forResource: "DefaultStyle",
       ofType: "bundle"
   ) {
       mapView.loadStyle(stylePath)
   } else {
       print("Style not found!") // Debug this
   }

Map renders slowly or stutters

Performance checklist:

• ✅ Use release builds for testing (Debug builds are slower)
• ✅ Limit visible markers (use clustering for 100+)
• ✅ Don't update map position every frame
• ✅ Use GLMapImageGroup for multiple markers

iOS specific:

• Enable Metal API (default)
• Check for background tasks blocking main thread

Android specific:

• Use GLMapView in SurfaceView mode (default)
• Avoid GLMapView in scrollable containers

---

Offline Maps

How do I download offline maps?

Download pre-defined map regions:

iOS:

// Download map data for a specific region
let tasks = GLMapManager.shared.downloadDataSets(
    .map,  // Can also use .navigation, .elevation, or combine with |
    for: mapInfo,
    withCompletionBlock: { task in
        if let error = task.error {
            print("Download failed: \(error)")
        } else {
            print("Download complete!")
        }
    }
)

Android:

// Download map and navigation data
val tasks = GLMapManager.DownloadDataSets(
    mapInfo,
    DataSet.MAP or DataSet.NAVIGATION
)

Download by bounding box (for custom areas):

iOS:

let taskID = GLMapManager.shared.downloadDataSet(
    .map,
    path: destinationPath,
    bbox: bbox,
    progress: { totalSize, downloadedSize, speed in
        let percent = Double(downloadedSize) / Double(totalSize) * 100
        print("Progress: \(percent)%")
    },
    completion: { error in
        if let error = error {
            print("Download failed: \(error)")
        }
    }
)

Android:

val taskID = GLMapManager.DownloadDataSet(
    DataSet.MAP,
    destinationPath,
    bbox
) { error ->
    if (error == null) {
        println("Download complete!")
    }
}

See the DownloadMapsViewController (iOS) or DownloadActivity (Android) demo for complete examples.

How much storage do maps require?

GLOBUS offers 129 pre-defined map regions covering the world. Here are real examples from our map catalog:

Region	Map Data	+ Navigation	+ Elevation	Total
World map (overview)	15 MB	—	—	15 MB
Monaco	1.3 MB	+11.3 MB	+0.1 MB	12.7 MB
Andorra	2.2 MB	+9.6 MB	+0.6 MB	12.4 MB
Luxembourg	21.9 MB	+58.1 MB	+0.8 MB	80.8 MB
Ireland	127.6 MB	+111.6 MB	+9.5 MB	248.7 MB
Bavaria (German state)	322.6 MB	+368.6 MB	+14.7 MB	705.9 MB
Texas (US state)	236.6 MB	+392.0 MB	+46.5 MB	675.1 MB
California (US state)	376.5 MB	+406.0 MB	+100.1 MB	882.6 MB

Data types:

• Map data (.vm) – Vector tiles for rendering (required)
• Navigation data (.rt) – For offline routing (optional, usually 1-1.5× map size)
• Elevation data (.ele) – For topographic features (optional, usually 5-25% of map size)

Large countries (Germany, France, Spain, Italy) are divided into 16-26 states/regions for more efficient downloads.

Can I download specific areas instead of full regions?

Yes! GLOBUS supports bounding box (bbox) downloads for downloading only the exact area you need.

Benefits:

• Smaller downloads for focused areas (city, route corridor)
• Faster downloads
• Less storage usage
• Perfect for route-based or city-specific apps

Important limitation:

• ❌ Bbox downloads do NOT include search indexes (offline search won't work)
• ✅ Map rendering works perfectly
• ✅ Offline routing works (if you download navigation data for the bbox)

When to use bbox vs pre-defined regions:

Use Case	Recommendation
Need offline search	✅ Use pre-defined regions
City-focused app, no search needed	✅ Use bbox
Route corridor for navigation	✅ Use bbox
General-purpose map app	✅ Use pre-defined regions

Example bbox download:

// iOS - Download specific area
let bbox = GLMapBBox(
    min: GLMapGeoPoint(lat: 37.7, lon: -122.5),
    max: GLMapGeoPoint(lat: 37.8, lon: -122.4)
)

let taskID = GLMapManager.shared.downloadDataSet(
    .map,  // or .navigation, .elevation
    path: "/path/to/save/map.vm",
    bbox: bbox,
    progress: { totalSize, downloadedSize, speed in
        print("Downloaded: \(downloadedSize) / \(totalSize)")
    },
    completion: { error in
        if error == nil {
            // Download complete - add the dataset
            GLMapManager.shared.addDataSet(.map, path: "/path/to/save/map.vm", bbox: bbox)
        }
    }
)

// Android - Download specific area
val bbox = GLMapBBox(/* ... */)
val taskID = GLMapManager.DownloadDataSet(
    DataSet.MAP,
    "/path/to/save/map.vm",
    bbox
) { error ->
    if (error == null) {
        // Download complete - add the dataset
        GLMapManager.AddDataSet(DataSet.MAP, "/path/to/save/map.vm", bbox)
    }
}

Can I download maps programmatically on first launch?

Yes, but be mindful of user data usage. Best practices:

1. Download only user's current region or area
2. Ask permission before downloads >50 MB
3. Show download progress
4. Offer Wi-Fi-only option for large downloads

// iOS - Check for Wi-Fi
import Network
let monitor = NWPathMonitor()
monitor.pathUpdateHandler = { path in
    if path.usesInterfaceType(.wifi) {
        // Safe to download large regions
    }
}

---

Routing & Navigation

Routing requires downloading navigation data?

Yes. Offline routing requires:

1. Map data (.vm files) – For map display
2. Routing data (.rd files) – For route calculation

Download both for the region you need. Map data alone only enables map display, not routing.

How accurate is offline routing?

GLOBUS uses Valhalla, the same routing engine used by:

• Mapbox
• Strava
• Many major mapping platforms

Routing quality is identical to online services, just calculated on-device.

Can I calculate routes online?

Yes! You can:

1. Use Valhalla API (self-hosted or third-party)
2. Send route requests to your backend
3. Create GLRoute from JSON response

See the demo apps for examples of creating routes from Valhalla JSON responses.

---

Troubleshooting Specific Errors

iOS: "dyld: Library not loaded"

Cause: Dynamic framework not embedded.

Solution:

1. Select your app target in Xcode
2. Go to "General" tab
3. Under "Frameworks, Libraries, and Embedded Content"
4. Ensure GLMap is set to "Embed & Sign" (not "Do Not Embed")

Android: "ClassNotFoundException: GLMapView"

Cause: ProGuard/R8 is stripping GLMap classes.

Solution: Add to proguard-rules.pro:

-keep class globus.glmap.** { *; }
-keepclassmembers class globus.glmap.** { *; }

Android: Crash on app startup with "UnsatisfiedLinkError"

Cause: Native libraries not included or wrong ABI.

Solution:

1. Check build.gradle includes correct dependencies
2. Verify ndk.abiFilters if you're filtering ABIs:

   defaultConfig {
       ndk {
           abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
       }
   }

iOS: Build fails with "Module 'GLMap' not found"

Cause: Framework search paths incorrect.

Solution:

• SPM: Remove package and re-add
• CocoaPods: Run pod deintegrate && pod install
• Manual: Check "Framework Search Paths" in Build Settings

---

Performance & Optimization

How can I improve map rendering performance?

Best practices:

1. Use appropriate zoom levels

   // Don't zoom too far out with detailed data
   mapView.mapZoomLevel = 12 // Good for city-level

2. Limit marker count

   • Use clustering for 100+ markers
   • Only show markers in current viewport

3. Optimize tile loading

   • Pre-download maps for offline use
   • Don't mix too many online tile sources

4. Profile your app

   • iOS: Use Instruments (Time Profiler)
   • Android: Use Android Studio Profiler

Map uses too much memory

Common causes:

1. Too many loaded map packages

   • Unload unused maps: GLMapManager.shared.removeMap(withID: mapID)

2. Large marker images

   • Use SVG instead of large PNGs
   • Resize images before loading

3. Memory leaks in callbacks

   • Use [weak self] in closures (Swift)
   • Use WeakReference for listeners (Kotlin)

---

Getting More Help

Where can I find code examples?

Demo Apps:

• iOS (Swift) – 25+ examples
• iOS (SwiftUI)
• iOS (Objective-C)
• Android (Kotlin)
• Android (Java)

Documentation:

• Tutorials – Step-by-step guides
• API Reference
• MapCSS Reference

How do I report bugs?

1. Check demo apps – Does the issue occur in demo apps?
2. Create minimal reproducible example
3. Submit issue:
   • Email: [email protected]
   • Include: Platform, SDK version, code snippet, error logs

Do you offer support?

Yes! Support options:

• Email support: [email protected] (all users)
• Priority support: Available with enterprise licenses
• Custom development: Contact [email protected]

---

Licensing & Pricing

What's included in the free tier?

• Full SDK functionality
• Unlimited development/testing
• Map tile downloads (fair use)
• Access to all demo apps

When do I need a paid license?

Production apps require a commercial license. Contact [email protected] for:

• Volume pricing
• Enterprise agreements
• Custom SLAs
• On-premise tile server licensing

Can I use GLOBUS in open-source projects?

Contact [email protected] to discuss licensing options for open-source projects.

---

Still have questions? Email us at [email protected] – we're here to help!