Skip to main content

Suma Address Autocomplete

Real-time address validation and autocomplete powered by SmartyStreets API.

Overview​

Suma Address Autocomplete provides intelligent address validation and autocomplete functionality for WordPress forms, particularly checkout forms in WooCommerce and BigCommerce for WordPress. Using the SmartyStreets API, the plugin validates addresses in real-time, suggests corrections, and ensures accurate shipping information.

Current Version: 1.0.0
Requires: WordPress 4.7+, PHP 8.0+
Text Domain: suma-address-autocomplete

Key Features​

Real-Time Address Validation​

  • Instant Validation — Validates addresses as users type
  • USPS Database — Checks against official USPS address database
  • International Support — Validates US and international addresses
  • Auto-Correction — Suggests corrected addresses for typos

Smart Autocomplete​

  • Predictive Suggestions — Shows address options as user types
  • Fast Lookups — Sub-second response times
  • Street-Level Accuracy — Complete address including unit numbers
  • ZIP+4 Codes — Returns extended ZIP codes for precision

Form Integration​

  • WooCommerce Checkout — Seamless integration with checkout forms
  • BigCommerce Checkout — BigCommerce for WordPress support
  • Custom Forms — Works with Gravity Forms and Contact Form 7
  • Manual Integration — JavaScript API for custom implementations

User Experience​

  • Non-Intrusive — Suggestions appear without blocking form submission
  • Mobile-Friendly — Touch-optimized autocomplete dropdowns
  • Accessibility — ARIA labels and keyboard navigation
  • Progressive Enhancement — Graceful degradation if JavaScript disabled

How It Works​

User Types Address
    ↓
JavaScript Captures Input
    ↓
Debounced API Call
    ↓
SmartyStreets Validation
    ↓
Results Returned
    ↓
Autocomplete Dropdown
    ↓
User Selects or Continues
    ↓
Form Populated with Valid Address

Architecture Overview​

Built with modern JavaScript and React/Preact:

  • Frontend: Preact components with Tailwind CSS
  • Build System: Laravel Mix + Webpack
  • Styling: Tailwind CSS 3.x with forms plugin
  • State Management: Preact Signals
  • SDK: SmartyStreets JavaScript SDK

Use Cases​

  • E-commerce Checkout — Reduce shipping errors and failed deliveries
  • Address Collection — Ensure accurate customer data capture
  • Form Validation — Prevent invalid addresses at submission
  • User Experience — Speed up form completion with autocomplete
  • Data Quality — Maintain clean address database

Technical Requirements​

  • WordPress 6.4 or higher
  • PHP 8.0 or higher
  • WooCommerce or BigCommerce for WordPress (optional)
  • SmartyStreets API credentials (Auth ID and Auth Token)
  • HTTPS enabled (required by SmartyStreets)

SmartyStreets API​

Required Credentials​

  • Auth ID — SmartyStreets account authentication ID
  • Auth Token — SmartyStreets API access token

API Endpoints Used​

  • US Street Address API — Validates US addresses
  • US Autocomplete API — Provides address suggestions
  • International Street Address API — Validates international addresses

Pricing​

SmartyStreets operates on a pay-per-lookup model. Monitor usage via SmartyStreets dashboard.

Technology Stack​

Frontend Libraries​

  • Preact — Lightweight React alternative (10KB)
  • @preact/signals — State management
  • @headlessui/react — Accessible UI components
  • @heroicons/react — Icon library
  • Tailwind CSS — Utility-first CSS framework
  • SmartyStreets JavaScript SDK — API client library

Build Tools​

  • Laravel Mix 6.x — Asset compilation
  • Webpack — Module bundling
  • Sass — CSS preprocessing
  • Tailwind CLI — CSS generation

Development​

npm install          # Install dependencies
npm run watch        # Development with live reload
npm run prod         # Production build
npm run tw:watch     # Tailwind watch mode
npm run tw:build     # Tailwind production build

Form Field Targeting​

The plugin automatically enhances these fields:

  • #billing_address_1 — Billing street address
  • #shipping_address_1 — Shipping street address
  • .address-autocomplete — Custom class for manual integration

JavaScript API​

Manual Integration​

// Initialize autocomplete on custom field
SumaAddressAutocomplete.init({
  field: '#custom_address',
  authId: 'your-auth-id',
  authToken: 'your-auth-token'
});

Events​

// Listen for address selection
document.addEventListener('suma:address-selected', function(e) {
  console.log('Address selected:', e.detail);
});

Configuration Options​

Configure via WordPress admin settings page:

  • Enable/Disable — Turn autocomplete on/off
  • SmartyStreets Auth ID — API authentication ID
  • SmartyStreets Auth Token — API access token
  • Target Forms — Select which forms to enhance
  • Validation Mode — Strict or lenient validation
  • International Support — Enable/disable international addresses

Security​

  • API Key Protection — Keys never exposed to frontend
  • Server-Side Proxy — All API calls routed through WordPress
  • HTTPS Required — SmartyStreets enforces HTTPS
  • Capability Checks — Admin settings require manage_options

Performance​

  • Debounced Requests — Minimizes API calls while typing
  • Caching — Recent lookups cached in session
  • Async Loading — Script loaded asynchronously
  • Minimal Footprint — Small bundle size (~50KB gzipped)