Skip to main content

Frequently asked questions

Setup​

How do I get an API key?​

Create an application at user.globus.software/apps and copy its API key. Complete SDK activation before creating a map view or using native-backed APIs, including geometry without a map view.

Which platforms are supported?​

  • iOS 15 and later, including Mac Catalyst
  • macOS 12 and later
  • Android API 21 and later
  • GLMapCore build support for watchOS 10 and later

The Android reference application uses compileSdk 37 and targetSdk 37.

Which installation path should I use?​

  • New iOS applications: Swift Package Manager, starting at 2.2.0
  • Existing Objective-C applications: CocoaPods remains available
  • Android: globus:glmap:2.2.0, with optional glsearch and glroute artifacts

See Get started for exact configuration. Existing applications should also read the 2.2.0 migration notes.

Can I use geometry, search, or routing without a map view?​

Yes. Use the SwiftPM GLMapCore product or Android globus:glmapcore:2.2.0 for geometry, storage, and downloads. Search and Route depend on Core, not the renderer. Add GLMap / globus:glmap explicitly if you also need map rendering.

Headless Swift clients import GLMapCore and GLMapCoreSwift; existing Map clients can keep import GLMapSwift. Android Core classes retain their globus.glmap package names. See setup without a map view.

What does a failed activation mean?​

On Apple platforms, GLMapManager.activate returns false if required resources are missing or the storage path is not writable. On Android, GLMapManager.Initialize returns false if cache/storage setup fails; module or native-library loading failures can throw. Do not use the SDK until initialization succeeds.

These results are not API-key validation. Check resources and storage first; investigate service authorization errors separately. Android initializes all included modules through GLMapManager.Initialize; a separate Search initialization call is not needed.

Map display​

Why is the map blank?​

Check these boundaries in order:

  1. SDK activation succeeded before the map view was created.
  2. Online tile downloading is enabled when the app expects online tiles.
  3. The default-style resources are available, or your custom style loaded successfully. Both platforms load the default style automatically.
  4. The requested position is covered by an embedded, downloaded, or online map source.

Online tile downloading is disabled by default:

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

Does the application need a separate default-style dependency?​

No. The iOS SPM package contains DefaultStyle.bundle. The Android globus:glmap:2.2.0 artifact depends on the exact matching globus:glmap-defaultstyle:2.2.0 artifact.

Both platforms load the default style when the map view is created. Parse and set a style explicitly only for custom resources or options.

Do I need to release native resources on Android?​

Yes. Call map.dispose() when the map screen is permanently destroyed. Search result lists, every independently owned result object, and GLMapViewState instances must also be closed when no longer needed.

How do I get useful Android native crash reports?​

The release AARs retain SDK native symbols and file/line information. Configure your application's native-symbol uploader, such as the Sentry Gradle integration, to upload symbols during your app build. The application build strips the binaries packaged for users. There is no separate SDK symbols ZIP to download, and GLMap does not upload crash reports or symbols on your behalf.

Search and routing​

How do online and offline search differ?​

GLSearchRequest represents both online and offline requests. Text, locales, categories, ranking center, result objects, and display fields use the same model on both transports.

Use startOnline or startOffline, cancel obsolete autocomplete requests, and expect completion exactly once. See the search tutorial.

Does spelling correction work offline?​

No. Fuzzy spelling corrections are provided by the online search service. Offline mobile search does not include fuzzy matching and continues to use downloaded maps without a connection.

For online corrections, supply a meaningful search center. In 2.2, GLSearchRequest.visibleArea can also provide viewport context; it is not a strict bounding-box filter. Read what typo-tolerant search can do for your app.

What must be downloaded for offline operation?​

  • Map rendering and offline search use registered map data.
  • Offline route calculation additionally needs navigation data.
  • 3D terrain additionally needs elevation data.

The Swift and Kotlin demos contain complete download flows.

Is Android 17 supported?​

Yes. The Android 17 startup fix introduced in GLMap 2.0 remains included in 2.2. The release validation includes a dedicated startup smoke app with targetSdk 37.

Help​