Maps & Location
If your app is about places - meetups, deliveries, local services, fitness routes, travel - you will probably want maps and location. Keyless hand-off to Apple Maps or Google Maps needs no connector. Embedded maps, geocoding, and route APIs need either a Mapbox public token or a Google Maps backend relay.
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:
- Adds the map view to your screen.
- Asks for location permission in context, when the user taps "Find coffee near me," and includes the platform permission copy you must review before release.
- Gets the user's current location.
- Uses the place-data source you choose, such as a provider's enabled POI/search API through a deployed relay, and drops pins. If no suitable source is connected, the agent asks you to choose one instead of inventing results.
- 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 choose libraries yourself. Describe the outcome; the agent builds the app-side flow and tells you exactly which provider APIs, relay deployment, native build, and permission steps are still required.
How the map renders (and what works in the preview)
By default the agent uses a keyless deep link for turn-by-turn directions. If you connect Google Maps, it can also generate static-map, geocoding, and route UI plus a SETUP REQUIRED relay contract. Those REST calls become live only after you deploy the relay and provision a separate restricted server key; the connector key is never embedded.
Mapbox static images and REST calls can run in the preview with its publishable token. Keep that token minimum-scope and isolated per app. Fully interactive Mapbox or Google map views need native SDK setup and a development build.
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.
Connecting Google Maps REST APIs safely
Google requires a billed Cloud project and an API key for its REST map services. Review current pricing rather than assuming a fixed free allowance.
- Go to the Google Cloud Console. Sign in with your Google account.
- Create a new project (or pick an existing one).
- Turn on three services for that project: Maps Static API, Geocoding API, and Routes API.
- In APIs & Services → Credentials, create an API key. Google gives you a long string starting with
AIza. - Limit the validation key to the APIs you selected, add a small quota and billing alerts, and paste it only in the encrypted connector form. Do not use iOS/Android application restrictions for plain REST calls.
- In the Appsanic project build, select Connectors → Google Maps and enter the key. Connect other projects separately.
- Deploy the generated relay, create a different runtime key restricted to that server's fixed outbound IP addresses and required APIs, and add it directly to the relay's secret manager.
Appsanic's connection test checks one bounded geocoding request. It does not deploy the relay or prove Static Maps and Routes are enabled.
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 (for example, restaurants with coordinates), nearby queries need an appropriate database schema and spatial query. The agent can generate the SQL and review steps, but you apply schema changes yourself unless an explicitly listed bounded action is available.
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.
- A Google REST request is rate-limited. Check the relay's authentication and per-user limits, Cloud quotas, enabled APIs, billing, and server-key IP restrictions. Never move the key into the app as a workaround.
Under the hood (for engineers)
- Maps (default): keyless Apple/Google Maps deep links. Google Maps Static, Geocoding, and Routes use an authenticated relay you deploy with its own server key; the preview stays a placeholder until that relay exists.
- 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; its minimum-scope public token can support preview-safe static images and REST calls. Interactive native maps still require a development build.
- Location:
expo-locationfor foreground requests, withuseUserLocationhook scaffolded by default. - Geosearch: for Postgres/Supabase, the agent can generate review-first PostGIS SQL with geography columns and
ST_DWithinqueries. You verify and apply it in Supabase.
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.