GoMap! Place Picker — Quick Start Instructions

## 1. Installation

Add the Place Picker GoMap! plugin to your Bubble app. No API key is needed — the plugin works immediately after installation.

Place the "Place Picker" element on your page and resize it to the desired dimensions (recommended: 100% width, 300-500px height).


## 2. Basic Setup

Map Style — choose between Standard, Dark, Light, or Bright.

Initial Latitude / Longitude — optional text fields. Pass coordinates as text (e.g. "48.8566", "2.3522"). Supports dynamic data from your database. If left empty or invalid, the map auto-centers on the user's real location.

Zoom — initial zoom level (1 = world, 10 = city, 15 = streets, 18 = buildings). Default: 14.

Pin Color — hex color for the center pin (e.g. #3B82F6). Default: blue.


## 3. Geolocation Priority

When enable_current_location is ON (default):

1. GPS — requests browser geolocation permission (high accuracy)
2. IP fallback — if GPS denied or unavailable, detects approximate location by IP
3. Initial coordinates — if both GPS and IP fail, uses initial_lat/initial_lng (if valid)

The location button shows a colored status dot:
- Green — GPS active, precise location
- Yellow — location detected by IP (approximate)
- Red — GPS permission denied (tap button to retry)


## 4. Coordinate Input Format

The initial_lat and initial_lng fields accept text. This makes it easy to bind dynamic Bubble data.

Accepted formats:
- "48.8566" — standard decimal
- "48,8566" — comma as decimal separator (auto-converted)
- " 48.8566 " — extra whitespace (auto-trimmed)

Invalid input (empty, letters, out of range) automatically triggers GPS/IP geolocation fallback. Latitude must be between -90 and 90. Longitude must be between -180 and 180.


## 5. How It Works

1. Map loads and centers on user's location (or initial coordinates)
2. A blue dot shows the user's detected position
3. A pin is fixed at the center of the map
4. User drags the map — pin stays centered — reverse geocode runs automatically
5. Address label appears below the pin
6. If enable_confirm_prompt is ON: "Confirm this address? Yes / No" appears
7. User clicks Yes — address_confirmed becomes true, address_pick_confirmed event fires
8. User clicks No — prompt hides, user continues dragging


## 6. Confirmation Prompt

Set enable_confirm_prompt to Yes to show "Confirm this address? Yes / No" after each location selection. Useful for forms where explicit user confirmation is required.

Set it to No for instant selection — the location_selected event fires immediately after each reverse geocode, without asking for confirmation.


## 7. Address Search

Set enable_search to Yes to show a search bar at the top of the map. Users can type any address, place name, or landmark. Results appear as a dropdown — tap one to fly to that location.


## 8. Exposed States

Use these in your Bubble workflows:

selected_lat — latitude as text (e.g. "48.856600"), 6 decimal places
selected_lng — longitude as text (e.g. "2.352200"), 6 decimal places
selected_address — full reverse-geocoded address
selected_city — city name
selected_country — country name
address_confirmed — yes/no, true after user clicks "Yes" on confirm prompt
gps_status — text: "gps", "ip", "denied", or "unknown"


## 9. Events

location_selected — fires after each reverse geocode (pin position changed)
address_pick_confirmed — fires when user clicks "Yes" on the confirmation prompt
map_ready — fires when the map finishes loading


## 10. Actions

set_location — pass lat (text) and lng (text) to move the map to specific coordinates. Accepts the same flexible text format as initial_lat/lng.

clear — resets the map to world view, clears all states.


## 11. Example: Save Address to Database

1. Add PlacePicker element to your page
2. Set enable_confirm_prompt to Yes
3. Add workflow: When PlacePicker's address_pick_confirmed happens
4. Action: Create a new Thing (e.g. Address)
  - latitude = PlacePicker's selected_lat
  - longitude = PlacePicker's selected_lng
  - address = PlacePicker's selected_address
  - city = PlacePicker's selected_city
  - country = PlacePicker's selected_country


## 12. Tips

- Use text fields in your database for lat/lng to preserve decimal precision
- The map performs well on mobile — test on real devices for best UX
- Pin color can match your app's brand color
- For edit forms, pass existing coordinates to initial_lat/initial_lng to pre-position the pin
- The search bar supports all languages — it uses the browser's language for results