06 Address Autocomplete

Address Autocomplete Feature Guide

Overview

The Address Autocomplete feature provides intelligent, real-time address suggestions as users type. Powered by the Pelias geocoding service, it helps ensure accurate address entry, reduces errors, and improves the user experience when entering addresses for orders, customers, and locations.

How It Works

  1. Type-Ahead Suggestions: As you begin typing an address, the system provides suggestions in real-time
  2. Geocoding Service: Uses Pelias, an open-source geocoding engine, to match and validate addresses
  3. Global Coverage: Supports addresses worldwide with comprehensive geographic data
  4. Smart Filtering: Automatically filters by state/region when specified
  5. Manual Override: Always allows manual address entry if needed

Using Address Autocomplete

Basic Usage

  1. Click in any address field
  2. Start typing the address (street name, business name, or full address)
  3. Select from the dropdown suggestions or continue typing
  4. Press Enter or click a suggestion to select it
  5. Field auto-populates with complete address details

Example Searches

  • "1600 Pennsylvania" → Suggests the White House address
  • "Empire State" → Suggests Empire State Building
  • "123 Main St, Austin" → Suggests addresses in Austin, TX
  • "Eiffel Tower" → Suggests the Paris landmark address

Supported Address Components

Street Addresses

  • House/Apt Numbers: 123, 456B, Unit 7, Apt 12C
  • Street Names: Main Street, Broadway, Elm Ave
  • Street Types: Street, Avenue, Boulevard, Road
  • Directionals: N, S, E, W, North, South

Points of Interest

  • Business Names: Google Office, Starbucks, Walmart
  • Landmarks: Statue of Liberty, Golden Gate Bridge
  • Institutions: MIT, City Hall, Public Library

Geographic Features

  • Parks: Central Park, Yellowstone National Park
  • Airports: LAX, JFK International Airport
  • Train Stations: Grand Central Terminal, Union Station

Field Integration

Order Creation

  • Customer Address: Autocomplete for customer locations
  • Notary Location: Find notary service areas
  • Meeting Location: Specify appointment locations
  • Service Address: Where notary services will be performed

Customer Profile

  • Primary Address: Main customer address
  • Billing Address: Separate billing location
  • Mailing Address: Postal delivery address
  • Service Addresses: Multiple service locations

Company Management

  • Business Address: Company headquarters
  • Branch Offices: Multiple office locations
  • Service Areas: Geographic coverage areas
  • Registered Address: Legal business address

Configuration Options

State/Region Filtering

When enabled, addresses are filtered by a specific state or region:

  • Improved Relevance: More accurate local suggestions
  • Faster Results: Reduced search space
  • Regulatory Compliance: State-specific address formats

Example Configuration:

// Filter addresses to California
stateFilter: "CA";

// Filter addresses to Texas
stateFilter: "Texas";

Manual Entry Mode

  • Always Enabled: Users can always type addresses manually
  • Fallback Option: Available when autocomplete isn't working
  • Privacy Option: For sensitive addresses
  • International Addresses: For locations outside primary service area

Error Handling

Service Unavailable

When the geocoding service is not available:

  • Graceful Degradation: Shows a helpful message
  • Manual Entry: Allows users to type the full address
  • No Service Interruption: Users can continue working
  • Clear Messaging: "Address lookup is temporarily unavailable. Please enter the address manually."

No Results Found

When no addresses match the search:

  • Helpful Suggestion: "No addresses found matching your search. Try entering the full address manually."
  • Search Tips: Suggest refining the search terms
  • Manual Entry: Option to type the complete address

Timeouts

If the service responds slowly:

  • 5-Second Timeout: Prevents long waits
  • User Notification: "Address lookup is taking too long. Please try again or enter the address manually."
  • Retry Option: Users can try the search again
  • Continue Working: Manual entry always available

Technical Details

Pelias Integration

  • Service URL: Configured via NEXT_PUBLIC_PELIAS_URL environment variable
  • API Endpoint: /v1/autocomplete for suggestions
  • Data Sources: OpenStreetMap, OpenAddresses, and other open data
  • Request Format: RESTful API with JSON responses

Response Format

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-74.006, 40.7128]
      },
      "properties": {
        "name": "1600 Pennsylvania Ave NW",
        "street": "Pennsylvania Ave NW",
        "housenumber": "1600",
        "postalcode": "20500",
        "locality": "Washington",
        "region": "DC",
        "country": "United States"
      }
    }
  ]
}

Privacy and Security

  • Data Encryption: All API calls use HTTPS
  • No Data Storage: Search terms are not stored permanently
  • Rate Limiting: Prevents abuse and ensures fair usage
  • Audit Logging: All address lookups are logged for security

Performance Optimization

Client-Side

  • Debouncing: 300ms delay between keystrokes
  • Caching: Previous search results cached locally
  • Minimum Characters: Search starts after 2 characters
  • Request Throttling: Limits API calls during rapid typing

Server-Side

  • Response Caching: Common searches cached for 1 hour
  • CDN Integration: Fast response times globally
  • Load Balancing: Multiple service instances for reliability
  • Health Monitoring: Automatic failover if service is down

Best Practices

For Users

  1. Be Specific: Include street numbers when possible
  2. Use Abbreviations: "St" for Street, "Ave" for Avenue
  3. Include City: Add city name for better results
  4. Check Suggestions: Review all suggestions before selecting
  5. Verify Address: Confirm the selected address is correct

For Developers

  1. Error Handling: Always handle service failures gracefully
  2. User Feedback: Provide clear messages for all states
  3. Performance: Implement debouncing and caching
  4. Accessibility: Ensure keyboard navigation works
  5. Mobile Support: Optimize for touch interfaces

For Administrators

  1. Service Monitoring: Monitor geocoding service health
  2. Usage Analytics: Track autocomplete usage patterns
  3. Error Monitoring: Set up alerts for high error rates
  4. Fallback Plans: Have manual entry procedures ready
  5. User Training: Train staff on effective usage

Troubleshooting

Common Issues

Q: No suggestions appear when I type A:

  • Check internet connection
  • Verify the service is running
  • Try typing a more specific address
  • Use manual entry if needed

Q: Suggestions are incorrect or incomplete A:

  • Try alternative address formats
  • Include zip or postal code
  • Check for typos in the search
  • Use manual entry for unusual addresses

Q: Service is slow or timing out A:

  • Wait for the timeout message
  • Try the search again
  • Use manual entry if urgent
  • Check service status page

Q: International addresses not working A:

  • Enter the full country name
  • Use local address format
  • Contact support for country-specific issues
  • Manual entry always available

API Reference

Proxy Endpoint

GET /api/proxy/pelias?text={search_text}&boundary.region={state}

Parameters

  • text (required): The address or place to search for
  • boundary.region (optional): Limit results to a specific state/region

Response Codes

  • 200: Success (returns data or empty results)
  • 400: Invalid or missing search text
  • 503: Service unavailable
  • 504: Service timeout

Error Responses

{
  "features": [],
  "userMessage": "Address lookup is temporarily unavailable. Please enter the address manually."
}

Integration Examples

React Component

<PeliasAutocomplete
  onAddressSelect={handleAddressSelect}
  stateFilter="CA" // Optional: filter by California
  allowManualEntry={true} // Always allow manual typing
  placeholder="Enter customer address..."
  required={true}
/>

JavaScript Integration

// Direct API call
fetch("/api/proxy/pelias?text=1600 Pennsylvania Ave")
  .then((response) => response.json())
  .then((data) => {
    if (data.features.length > 0) {
      console.log("Found address:", data.features[0]);
    } else if (data.userMessage) {
      console.log("Service message:", data.userMessage);
    }
  });

Future Enhancements

Planned Features

  • Voice Input: Dictate addresses using speech recognition
  • Image Recognition: Photo capture of addresses
  • Address Validation: Real-time USPS address verification
  • History: Remember recent address searches
  • Favorites: Save frequently used addresses

Advanced Features

  • Multiple Languages: Support for international address formats
  • Batch Processing: Validate multiple addresses at once
  • Custom Datasets: Add proprietary address databases
  • Machine Learning: Improve suggestions based on user behavior