Maps & Location

If your app is about places. Meetups, deliveries, local services, fitness routes, travel. You'll want maps and location. The agent can wire all of this up, but there's one annoying step: you need a free Google Maps key from Google's website (we'll walk you through it). Prefer Mapbox? That's a managed connector too - connect it instead and ask the agent to use Mapbox.

What you can do without much thought

"Show a map of nearby coffee shops. Get the user's current location, drop a pin on each coffee shop within 1 km, tap a pin to see name, address, and a Directions button that opens the user's preferred maps app for turn-by-turn directions."

What the agent does:

1. Adds the map view to your screen.
2. Asks for location permission at the right moment (when the user taps "Find coffee near me," not when the app opens. Apple will reject apps that ask too early).
3. Gets the user's current location.
4. Looks up coffee shops near that point and drops pins.
5. Tapping a pin opens a small panel with details + a Directions button that hands off to Apple Maps or Google Maps.

You don't have to know any of the libraries involved. Describe what you want, the agent does the rest.

How the map renders (and what works in the preview)

By default the agent builds map screens with Google's Static Maps images, plus geocoding and routes over plain REST. That combination works everywhere - the live preview, Expo Go on your phone, and real devices - with no special build. For turn-by-turn directions, the app hands off to the Google Maps app with a deep link.

Fully interactive pan-and-zoom maps (the react-native-maps kind) need a custom native build and don't run in the preview. Ask for one if you need it, and expect to test it in a development build rather than the preview.

The one annoying step: getting a Google Maps key

Google requires every app that uses its maps to have a free key. It takes about 10 minutes the first time.

1. Go to the Google Cloud Console. Sign in with your Google account.
2. Create a new project (or pick an existing one).
3. Turn on three services for that project: Maps Static API, Geocoding API, and Routes API.
4. In APIs & Services → Credentials, create an API key. Google gives you a long string starting with AIza.
5. Lock it down. While creating the key, add key restrictions - your app's identifier (the bundle ID for iOS and the package name for Android. See the Glossary) and/or the specific APIs above. This key is designed to be bundled into your app, so restrictions are what protect it. An unrestricted key gets abused within hours; an app-restricted key still passes our connection test, by design.
6. Connect the key in Dashboard → Connectors → Google Maps. Connect once and every project in your account can use it.

Google's free quota is generous. Most small apps stay free for months. Heavy use (lots of map opens or address searches per day) starts costing money.

Asking for location the right way

Phones treat location as one of the most sensitive permissions. Apple in particular rejects apps that ask without a clear reason.

The agent's default flow:

• The first time the user does something that needs location ("Find places near me"), we show a friendly screen explaining why. Then we ask for system permission.
• If the user says no, we don't ask again automatically. We provide a Settings toggle so they can change their mind later.

Be honest in the explanation:

"Let users know we'll use their location only to find nearby places, never share it, and they can disable it any time in Settings."

Two kinds of location permission

• While using the app: the default. Good for almost every app.
• Always: needed for things that track location when the app is closed (fitness tracking, delivery drivers). Apple and Google scrutinise this much more closely; you'll need a clear justification at App Store review.

Common things you can ask for

Drop pins on a map

"Drop a pin for each store. On tap, show the store's name, opening hours, and a 'Get directions' button."

Cluster pins when zoomed out

If you have more than ~50 pins visible, pins crowd. Clustering groups them into a single dot with a count, and they split apart as you zoom in.

"Cluster the pins when zoomed out. Show the count on each cluster. Zoom in automatically when a cluster is tapped."

Live clustering that splits as you pinch and zoom needs the fully interactive map - see the note above about custom native builds.

Address search as the user types

"Add an address search bar. As the user types, show suggestions. On selection, pin the location on the map."

Draw routes

"Draw the cyclist's route as a coloured line on the map, with colour reflecting speed (red = slow, green = fast)."

Native directions

Tapping a Directions button simply hands off to the user's preferred maps app - this is the agent's default:

"Add a 'Get directions' button on each pin's detail. Tapping opens directions in Apple Maps on iPhone and Google Maps on Android."

Building turn-by-turn inside your app is much more complex and usually unnecessary. The user already has a map app installed.

"Find places near me"

If your app stores location data (e.g., a list of restaurants with coordinates), you'll want to be able to query "places near a point." The agent enables this when you ask for nearby-lookup features. There's nothing for you to set up.

Background location (use with care)

If your app needs to know where the user is when the app is closed. A delivery app tracking the driver, a fitness app recording a route. Apple and Google both require:

• Stronger justification at App Store review.
• A visible indicator while tracking.
• A way for the user to pause.

Battery drains fast with background location. Most apps don't need it.

Things that go wrong

• The simulator's location is in Cupertino, California. That's where Apple fakes it by default. You can change it from the Simulator menu. Same idea on Android emulators.
• A user denied permission. Handle it gracefully. Show a screen with a button that opens the user's app settings, don't just blank out.
• The API key got rate-limited. Usually means it's unrestricted and being abused, or you're using more than the free quota. Restrict the key to your app's bundle ID/package name and you're protected.

Under the hood (for engineers)

• Maps (default): Google Maps Static API images plus Geocoding and Routes over plain REST, using the key from your Google Maps connector - no native module, so it runs in the preview and Expo Go. Turn-by-turn hands off to the Google Maps app via deep link.
• Maps (fully interactive): react-native-maps - requires a custom native build and doesn't run in the preview.
• Mapbox is available as a managed connector if you'd rather use it; its public token is also bundled into the app by design.
• Location: expo-location for foreground requests, with useUserLocation hook scaffolded by default.
• Geosearch: if your data is in Postgres (Supabase), the agent enables PostGIS and writes geography-typed columns with ST_DWithin queries.

Permission strings live in app.json under ios.infoPlist (NSLocationWhenInUseUsageDescription) and android.permissions (ACCESS_FINE_LOCATION).

Next

Read Offline Support for apps that need to work when the network doesn't.