Places API & Geocoding
Address autocomplete for enrollment forms (Places API) and converting addresses to GPS coordinates (Geocoding API) — with India-specific configuration.
These two APIs solve two distinct but connected problems in any location-aware app:
- Getting a valid, structured address from the user — Places API (autocomplete)
- Converting that address to GPS coordinates for storage — Geocoding API
They are almost always used together. The user types, Places suggests, the user selects, Geocoding converts the selection to { lat, lng } which goes into your database.
Places API — Address Autocomplete
The "Why First" Scenario
You are building the EduTrack enrollment flow. Step 2 is "Enter your home address." You put a text box. Parents type freely.
One parent types "Banjara Hills". Another types "Banjara Hills Hyd". A third types "Road No 12 Banjara Hills Hyderabad Telangana 500034". All three mean the same place. All three look different in your database. None of them have coordinates. Your branch map cannot show distances. Your catchment area calculation is broken. Your nearest branch suggestion returns an error.
The Places API solves this at the source — before the parent submits. As they type "Pres", they see "Prestige Towers, Road No. 12, Banjara Hills, Hyderabad, Telangana 500034" as a suggestion. They tap it. Your app receives a clean, standardised address with verified coordinates. The database has exactly what it needs.
The Excel Analogy
Think of a dropdown validation list in Excel — instead of letting users type anything into a cell, you give them a validated list to pick from. The Places autocomplete is the same idea, except the list is Google's entire database of real-world addresses, updated in real time based on what the user is typing.
Setting Up the Places API
The Places API uses the same API key as your Maps JavaScript API. What changes is which APIs you enable in Google Cloud Console.
In Google Cloud Console → APIs & Services → Library, search for and enable Places API (not "Places API (New)" — both work, but the standard one is more widely documented).
Both the Maps JavaScript API and the Places API can share the same API key — you do not need a separate key.
Address Autocomplete in a React Web App
Install the library:
There are two common React libraries for Google Maps: @vis.gl/react-google-maps (recommended for map display, covered in the Maps API page) and @react-google-maps/api (recommended for Places Autocomplete). You can use both in the same project — they do not conflict.
The autocomplete component:
Using the component in an enrollment form:
The componentRestrictions: { country: 'in' } option is important for Indian apps. Without it, the autocomplete shows global results. A user typing "Banjara Hills" would see results from multiple countries. Restricting to 'in' limits suggestions to India only.
Address Autocomplete in a React Native App (Expo)
For mobile, use the react-native-google-places-autocomplete library — purpose-built for this use case with native styling options.
Install:
Basic usage:
fetchDetails={true} is required. The basic autocomplete only returns the address text. To also get the geometry.location (the coordinates), you must set fetchDetails to true — this triggers a second Places API call to retrieve full place details including latitude and longitude.
Cost implication of fetchDetails: Each address selection with fetchDetails={true} makes one autocomplete session call plus one Place Details call. The autocomplete session bundles all keystrokes into one charge — so typing 10 characters and selecting is one session, not 10 requests. The Place Details call is an additional $17 per 1,000 requests. For Indian apps at typical volume, this is negligible within the free credit.
Geocoding API
When to Use Geocoding vs Places
The Places API already returns coordinates when a user selects an address. So when do you need the Geocoding API separately?
| Situation | Use |
|---|---|
| User picks from Places autocomplete | Places API — coordinates come with the selection |
| You have a text address stored in your database (e.g. imported from a form that had no autocomplete) and need to convert it | Geocoding API |
| User pastes an address from somewhere else (clipboard, forwarded message) | Geocoding API |
| Server-side batch processing — converting many stored addresses to coordinates | Geocoding API (HTTP, server-side) |
Client-Side Geocoding (Using the Maps JavaScript SDK)
If you have already loaded the Maps JavaScript API on the page, you can geocode without an additional library call:
Server-Side Geocoding (Supabase Edge Function)
For batch processing or any situation where you need geocoding without the browser Maps SDK, call the Geocoding API HTTP endpoint directly from an edge function:
The server-side Geocoding API key must not be restricted to HTTP referrers. Domain restrictions are for browser-based requests. Edge function requests come from a Supabase data centre IP, not from your website's domain. Instead, for server-side keys, use "IP address" restrictions in Google Cloud Console, or keep the key in Supabase secrets (never in frontend code) and rely on edge function security. Never put an unrestricted Geocoding key in your React frontend — use the client-side google.maps.Geocoder() approach instead, which inherits the Maps JavaScript API key's domain restrictions.
Caching Geocoded Results
The most important performance and cost optimisation for Geocoding: never geocode the same address twice.
Once you have converted an address to coordinates, store them in your database. If the same address is entered again, read from the database — do not call the Geocoding API again.
In practice for EduTrack: when a parent saves their address, store all three values:
Geocode on first entry, store the result, reuse it for every subsequent enrollment or fee payment at the same address. The Geocoding API call happens once per address, not once per transaction.
Cache the full Places result, not just coordinates. When a user selects from the Places autocomplete, the result includes the place_id — a unique Google identifier for that specific address. Store place_id alongside coordinates. If you ever need to re-fetch details for that address (e.g., to show updated opening hours for a business), you can call Place Details by place_id — which is more reliable than re-geocoding by text, because addresses can change in name while the physical location stays the same.
Connecting the Two APIs in an Enrollment Flow
The complete address capture flow for EduTrack:
This is the complete picture — Places API for input, coordinates from the Place Details response, stored once, used everywhere.
componentRestrictions: { country: 'in' }. Type a locality name and confirm Indian suggestions appear. Then log the result object to the console and identify where geometry.location.lat and geometry.location.lng are returned.