> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cfosilvia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ADDRESS AUTOCOMPLETE

# Address Autocomplete Feature

## Overview

The property dialog now includes Google Places Autocomplete for improved address entry. This provides a better user experience by suggesting addresses as users type.

## Setup

### 1. Get a Google Maps API Key

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the following APIs:
   * **Maps JavaScript API** ✅ (Required for loading Google Maps)
   * **Places API (New)** ✅ (Required for autocomplete)
4. Create credentials (API Key)
5. Restrict the API key to your domain for production

**Note:** The component works with both the legacy "Places API" and the new "Places API (New)". You're using the new one which is recommended.

### 2. Configure Environment Variable

Add the following to your `.env.local` file:

```bash theme={null}
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=your_api_key_here
```

**Note**: The `NEXT_PUBLIC_` prefix is required for client-side access in Next.js.

### 3. API Key Restrictions (Recommended for Production)

For security, restrict your API key:

**Application Restrictions:**

* Set HTTP referrers to your domains:
  * `https://yourdomain.com/*`
  * `http://localhost:3000/*` (for development)

**API Restrictions:**

* Only allow:
  * **Maps JavaScript API** (loads the script)
  * **Places API (New)** (provides autocomplete)

**Note:** You do NOT need Geocoding API - the Places API includes all necessary functionality.

## Features

* **Real-time suggestions** as user types (debounced to 300ms)
* **US address filtering** - restricts results to US addresses only
* **Session tokens** - optimizes API usage and reduces costs
* **Fallback** - If API key is missing, component falls back to regular input
* **Loading states** - Shows spinner while loading script and fetching suggestions
* **Click outside** - Closes suggestions dropdown when clicking elsewhere

## Cost Optimization

The component uses several techniques to minimize API costs:

1. **Debouncing** - Waits 300ms after user stops typing before making API call
2. **Session tokens** - Groups autocomplete + place details requests into single session (cheaper billing)
3. **Minimum characters** - Only searches after user types 3+ characters
4. **Request optimization** - Only requests necessary fields in place details

## Pricing

As of 2024:

* **Autocomplete - Per Session**: \$2.83 per 1000 requests
* **Place Details - Basic**: \$0.00 per 1000 requests (when bundled with Autocomplete)

The session token feature ensures you're only charged once per complete user interaction.

## Usage

The AddressAutocomplete component is used in TWO places:

### 1. Property Search Tab

Users can:

1. Start typing an address
2. Select from suggested addresses
3. The full address is auto-filled
4. Then search for property details via Zillow

### 2. Manual Entry Tab

Users can:

1. Start typing in the Street Address field
2. Select from suggested addresses
3. **All address fields auto-fill** (street, city, state, zip)
4. Then add property with manual estimated value

## Troubleshooting

### Error: "ApiTargetBlockedMapError"

This means your API key has referrer restrictions that are blocking localhost.

**Solution:**

1. Go to [Google Cloud Console](https://console.cloud.google.com/google/maps-apis/credentials)
2. Click on your API key
3. Under "Application restrictions" → "HTTP referrers"
4. Add these referrers:
   ```
   http://localhost:3000/*
   http://localhost:*/*
   https://yourdomain.com/*
   ```
5. Save changes (may take a few minutes to propagate)

**OR** For development only, temporarily set to "None" under Application restrictions (NOT recommended for production!)

### Autocomplete not working

1. **Check console for errors** - Look for API key issues
2. **Verify API is enabled** - Ensure Places API is enabled in Google Cloud
3. **Check billing** - Ensure billing is set up on your Google Cloud project
4. **Verify environment variable** - Make sure `NEXT_PUBLIC_GOOGLE_MAPS_API_KEY` is set in `.env.local`
5. **Restart dev server** - After adding env variable: `npm run dev`

### Component shows regular input (no autocomplete)

The component automatically falls back to a regular input field if:

* API key is not set
* API key is invalid or blocked
* Google Maps script fails to load

This is intentional - users can still enter addresses manually.

## Manual Input Fallback

Both the Property Search and Manual Entry tabs support manual input. If autocomplete fails or API key is not configured:

* Users can still type addresses manually
* The component gracefully falls back to a regular text input
* All functionality remains available


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.