Many developers lose hours to a blank gray map, a crash on screen rotation, or a location dot that never appears. Most of those problems trace back to outdated tutorials and credential mistakes.
This Kotlin-first guide covers choosing an approach, securing credentials, embedding the map, adding markers and user location, fixing common failures, and knowing when a different architecture fits better.
Key Takeaways
- Pick your provider and required capabilities before adding any dependency.
- Rendering a map and reading device location are separate features with separate permissions.
- A basic embedded map covers many apps; search, directions, and live tracking need extra services.
- Test key restrictions, lifecycle recreation, poor networks, and costs before release.
How to Implement Maps in an Android App
Step 1: Define the map experience and choose a provider
Start by listing what the app actually needs: a plain interactive map, markers, clustering, place search, geocoding, directions, live tracking, custom styling, offline use, or route optimization. Each extra feature usually means another service and another meter.
The Google Maps SDK for Android is a practical starting point for most apps. Per the Google setup documentation, it requires Android 6.0 (API 23) or higher and compileSdk 34 or higher, plus Google Play services on the device or emulator. Check current pricing and requirements in the official docs before you commit.
You also have a lighter choice: skip the embedded map and launch an external maps app with an Android intent. Embedding gives you in-app control. An intent takes far less effort but limits customization and workflow control.
Step 2: Create the project and secure the API credentials
Follow this order:
- Create or select a Cloud project and enable billing.
- Enable only the SDKs you need, such as Maps SDK for Android.
- Create an API key in the Credentials page.
- Add an application restriction: your package name plus the signing certificate's SHA-1 fingerprint.
- Add an API restriction limiting the key to the enabled services.
For distributed builds, remember that release certificates and Play App Signing fingerprints differ from your debug keystore. Use separate keys or restrictions for development and production where practical.
Keep keys out of source control. Google's Secrets Gradle Plugin reads an excluded local properties file and exposes values to BuildConfig and the manifest. That keeps keys out of your repository, but it does not make them secret inside a shipped APK, so restrictions still matter.
If a key leaks, rotate it. Rotation creates a new key with the old restrictions, and both keys work during migration. Installed apps keep the old key until users update, so monitor old-key usage before you delete it.
Step 3: Add the SDK and configure the Android app
Use the current official coordinates rather than a version copied from an old tutorial. At the time of writing, the Maps dependency is:
dependencies {
implementation("com.google.android.gms:play-services-maps:20.1.0")
}
Jetpack Compose projects can use com.google.maps.android:maps-compose:8.4.0 instead, which provides GoogleMap composables. Verify both versions against the official docs.
In the manifest, add the key metadata inside <application>:
<meta-data
android:name="com.google.android.geo.API_KEY"
android:value="${MAPS_API_KEY}" />
The ${MAPS_API_KEY} placeholder pulls from your build configuration. Current Maps SDK integration does not require WRITE_EXTERNAL_STORAGE, so don't add legacy storage permissions. Location permissions apply only when you access the user's location, not when you display a map.
Step 4: Add the map surface and initialize it safely
Place a SupportMapFragment (or MapView) in your layout, then request the map asynchronously. Google's SupportMapFragment handles the map lifecycle for you, and the callback runs on the main thread.
class MapActivity : AppCompatActivity(), OnMapReadyCallback {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_map)
val fragment = supportFragmentManager
.findFragmentById(R.id.map) as SupportMapFragment
fragment.getMapAsync(this)
}
override fun onMapReady(map: GoogleMap) {
val sample = LatLng(39.9612, -82.9988) // demo coordinates only
map.moveCamera(CameraUpdateFactory.newLatLngZoom(sample, 12f))
}
}
Only touch the GoogleMap object inside onMapReady. Keep demo coordinates separate from real user or business data. LatLng takes latitude first, then longitude; latitude clamps to [-90, 90] and longitude normalizes to [-180, 180].
If you use a raw MapView, forward every lifecycle call: onCreate, onStart, onResume, onPause, onStop, onDestroy, onSaveInstanceState, and onLowMemory. To survive rotation, save the camera position in onSaveInstanceState() and restore it in onCreate(). In Compose, rememberCameraPositionState handles configuration changes and process death.
Step 5: Add markers, location, and production behavior
Markers. Call addMarker(MarkerOptions) with a position, title, and optional snippet. Keep a stable identifier for each marker so you can update or remove it later instead of redrawing everything. For large sets, use the utility library's ClusterManager, which groups markers when zoomed out and separates them as users zoom in.
User location. Showing the blue dot requires location permission, a location provider, and enabled device location settings. Build it in layers:
- Explain the feature before requesting permission.
- Use
shouldShowRequestPermissionRationale()to decide whether to show an educational prompt after a denial. - On Android 12+, request fine and coarse together, since users may grant only approximate location.
- Check device settings separately with
SettingsClient.checkLocationSettings(). - Use
getCurrentLocation()when you need a fresh fix;getLastLocation()can return null or stale data.
Device location is sensitive data under Google Play policy. You need an accessible privacy policy and accurate Data safety disclosures, and a prominent in-app disclosure when use may exceed user expectations.
Failure states. Show a clear message for load failures, no network, invalid coordinates, denied permissions, and quota or authorization errors. A blank map misleads users.
Testing. Run the full flow on emulators (with the Play icon) and physical devices. Cover multiple screen sizes, rotation, offline mode, granted and denied permissions, and both debug and release signing.
When to Use an Embedded Map and What You Need
Embed a map when users need to see locations, pick a point, inspect markers, or work with geographic data without leaving your app. Complexity jumps when you add features such as:
- Turn-by-turn navigation
- High-frequency live tracking
- Large marker sets or offline maps
- Address search and route calculation
- Tight control over data and cost
Equipment and system requirements
- Current Android Studio and a working Gradle build
- Android API 23+ target range and
compileSdk34+ - A provider account with the mapping SDK enabled
- A restricted API key
- A device or emulator with Google Play services and network access
Inputs and conditions
- Valid WGS84 latitude and longitude values
- A defined initial camera position
- Marker data with stable identifiers
- A plan for missing or stale location data
- Any styling or attribution assets the provider requires
Skills and compliance
You should be comfortable with Kotlin, Activity and Fragment lifecycles, runtime permissions, and secret management. Also review the provider's terms and attribution rules, and prepare privacy disclosures if you collect location.
Key Parameters That Affect Map Results
A map can render fine and still deliver a poor experience. Four parameters decide most outcomes.
Provider, SDK, and enabled services
The provider determines map data, styling, search, routing, coverage, licensing, and quotas. The Maps SDK SKU for Android has unlimited free usage but still requires billing, according to Google's pricing list. Static images are metered differently: 10,000 free events per month, then $2 per 1,000 in the first paid tier. Match services to real needs and check current pricing before launch.
API-key restrictions and project configuration
A missing, misconfigured, or unrestricted key causes authorization failures, surprise charges, or exposure. Validate package-name and fingerprint restrictions in both debug and release builds, monitor usage per service, and test rotation.
Lifecycle, camera state, and readiness
Map objects arrive asynchronously and can be destroyed with the Activity or Fragment view. Initialize only through the callback, avoid null or destroyed references, restore camera state deliberately, and prevent duplicate listeners or repeat requests.
Location, coordinate quality, and data volume
Swapped latitude and longitude, stale GPS readings, or thousands of unoptimized markers make a map look wrong or feel slow. Validate coordinates, show loading or accuracy states, request only the precision you need, and cluster or load by viewport. Google's clustering demo uses 2,000 markers, but that is an example, not a documented performance limit. Profile on real devices.
Common Mistakes and Troubleshooting
Most map failures come from stale setup instructions, credential errors, lifecycle misuse, or treating location access as part of rendering.
Common mistakes
- Copying legacy tutorials: replace old dependencies, manifest entries, permissions, and callbacks with current equivalents.
- Leaving keys unrestricted or committed: apply restrictions, limit enabled APIs, use secure build config, and inspect release artifacts.
- Requesting location up front: explain the feature first, ask in context, and keep the map useful when users decline.
- Rendering every marker at once: use stable IDs, clustering, viewport loading, and batched updates.
Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
| Blank gray map or auth error | Wrong manifest key, disabled billing or SDK, incorrect SHA-1 restriction | Run adb logcat -e "Google Maps Android API", confirm the active build variant, test release credentials |
| Crash or null map | Accessing the map before the ready callback, or holding a destroyed Fragment view | Initialize in the callback, clear view references, avoid double initialization |
| No user location | Permission denied, device location off, null last-known fix | Check permission and settings, show a fallback, request a fresh location |
| Slow panning or high usage | Too many markers, frequent redraws, extra services | Profile rendering, cluster, cache, batch updates, review quotas |
Alternatives to Embedding an Interactive Map
The right choice depends on whether users need a map inside your app, a single preview, turn-by-turn navigation, or a broader location platform.
Open an external maps app with an Android intent
Use this for simple "show this place" or "get directions" actions. Launch ACTION_VIEW with a geo:latitude,longitude URI, optionally call setPackage("com.google.android.apps.maps"), and check resolveActivity() first. Maps URLs need no Google API key. The trade-off: less control over branding, state, analytics, and the in-app experience.
Use a static map image
Choose this for address cards, reports, emails, or thumbnails where gestures aren't needed. The Maps Static API returns images up to 640 x 640 and requires authentication and billing. It reduces rendering work but can't support panning, marker interaction, or live tracking.
Pair a native map UI with a specialized routing backend
Logistics, delivery, fleet, trucking, and field-service apps often need vehicle-aware routing, optimization, and predictable costs beyond a basic map. NextBillion.ai provides an Android Maps SDK, a Navigation SDK, and routing APIs with truck-size and axle-load constraints. Pricing can run per order or per vehicle instead of per API call. The trade-off is added backend integration, data synchronization, and vendor evaluation work.
Conclusion
Implementing maps on Android works best when you choose the capability first, secure the project and key, initialize the map through its lifecycle, and validate location and marker data.
Most failures come from outdated dependencies, wrong credentials, premature map access, unnecessary permissions, or unoptimized data. The right approach balances user experience, privacy, performance, provider requirements, and long-term cost.
Frequently Asked Questions
Does Android have its own map app?
Android is an operating system and doesn't mandate one map app. Many devices ship with Google Maps through Google Mobile Services, but manufacturers, users, and developers can use other map apps or SDKs.
What is the best way to add Google Maps to an Android app?
Use the current Maps SDK for Android with a configured Cloud project and restricted API key. Add a SupportMapFragment or MapView, then initialize the map in the asynchronous ready callback.
Do I need an API key to display a map in an Android app?
Yes, Google's embedded SDK requires authentication and billing. Restrict the key to your package name and signing certificate, and store it securely. Maps URLs for external launches don't need a key.
Do I need location permission to show a map in an Android app?
No. A map renders without it; Google's sample shows a default map with My Location disabled. Request permission only for location-based features.
How do I add markers to a map in an Android app?
Wait for the map-ready callback, then call addMarker with a LatLng and a title. Track markers by stable identifier, and use ClusterManager for larger datasets.
Can I use a map provider other than Google Maps in an Android app?
Yes. Options include Mapbox, MapLibre Native, HERE, and NextBillion.ai, plus intents and static images. Compare capabilities, licensing, coverage, pricing, offline support, and integration effort.
