PHPackages                             arraypress/google-address-validation - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. arraypress/google-address-validation

ActiveLibrary[API Development](/categories/api)

arraypress/google-address-validation
====================================

A PHP library for integrating with the Google Address Validation API in WordPress, providing comprehensive address validation, standardization, and verification. Features WordPress transient caching and WP\_Error support.

111↓100%PHP

Since Jan 6Pushed 1y ago1 watchersCompare

[ Source](https://github.com/arraypress/google-address-validation)[ Packagist](https://packagist.org/packages/arraypress/google-address-validation)[ RSS](/packages/arraypress-google-address-validation/feed)WikiDiscussions main Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

Google Address Validation API for WordPress
===========================================

[](#google-address-validation-api-for-wordpress)

A PHP library for integrating with the Google Address Validation API in WordPress. This library provides robust address validation, standardization, and verification capabilities with support for WordPress transient caching and WP\_Error handling.

Features
--------

[](#features)

- ✅ **Address Validation**: Verify and standardize addresses globally
- 📊 **Validation Scoring**: Get numerical scores (0-100) and ratings for address quality
- 🏠 **Detailed Components**: Access all address components and metadata
- 📫 **USPS Support**: Enhanced validation for US addresses with USPS data
- 🌍 **International**: Support for addresses worldwide with region code handling
- 🔄 **Response Parsing**: Clean response object for easy data access
- ⚡ **WordPress Integration**: Native transient caching and WP\_Error support
- 🛡️ **Type Safety**: Full type hinting and strict types
- 🏢 **Business Detection**: Identify business locations and PO boxes
- 📍 **Geocoding**: Get coordinates for validated addresses
- 🔍 **Validation Details**: Access validation status and issues

Requirements
------------

[](#requirements)

- PHP 7.4 or later
- WordPress 5.0 or later
- Google Address Validation API key

Installation
------------

[](#installation)

Install via Composer:

```
composer require arraypress/google-address-validation
```

Basic Usage
-----------

[](#basic-usage)

```
use ArrayPress\Google\AddressValidation\Client;

// Initialize client with your API key
$client = new Client( 'your-google-api-key' );

// Validate an address
$result = $client->validate( '1600 Amphitheatre Parkway, Mountain View, CA' );
if ( ! is_wp_error( $result ) ) {
    // Get validation score and rating
    $score = $result->get_score();
    $rating = $result->get_rating();
    echo "Validation Score: {$score}/100 ({$rating})\n";

    // Check if address is verified
    if ( $result->is_verified() ) {
        // Get standardized address
        $address = $result->get_standardized_address();
        echo "Formatted Address: {$address['formatted_address']}\n";

        // Get coordinates
        if ( $geocode = $result->get_geocode() ) {
            echo "Latitude: {$geocode['latitude']}\n";
            echo "Longitude: {$geocode['longitude']}\n";
        }
    }
}
```

Validation Scoring
------------------

[](#validation-scoring)

The library provides a comprehensive scoring system to assess address quality:

```
$result = $client->validate( '1600 Amphitheatre Parkway, Mountain View, CA' );
if ( ! is_wp_error( $result ) ) {
    // Get numerical score (0-100)
    $score = $result->get_score();

    // Get human-readable rating
    $rating = $result->get_rating(); // Returns: Excellent, Good, Fair, or Poor

    // Example score interpretation
    switch (true) {
        case $score >= 90:
            echo "Excellent - Highly reliable address\n";
            break;
        case $score >= 75:
            echo "Good - Reliable address with minor issues\n";
            break;
        case $score >= 50:
            echo "Fair - Address may need verification\n";
            break;
        default:
            echo "Poor - Address needs significant verification\n";
    }
}
```

### Score Components

[](#score-components)

The validation score considers multiple factors:

- Address completeness (30 points)
- Confirmed components (20 points)
- No inferred components (15 points)
- No replaced components (10 points)
- Geocoding data (10 points)
- Postal code presence (5 points)
- Precise location (5 points)
- USPS validation (5 bonus points for US addresses)

Extended Examples
-----------------

[](#extended-examples)

### USPS Validation for US Addresses

[](#usps-validation-for-us-addresses)

```
// Enable USPS validation for US addresses
$result = $client->validate(
    '1600 Pennsylvania Avenue NW, Washington, DC 20500',
    'US',
    true // Enable USPS validation
);

if  ( ! is_wp_error( $result ) ) {
    $usps_data = $result->get_usps_data();
    // Access USPS-specific data
}
```

### Address Type Detection

[](#address-type-detection)

```
$result = $client->validate( '123 Business Street, Anytown, USA' );
if ( ! is_wp_error( $result ) ) {
    if ( $result->is_residential() ) {
        echo "This is a residential address\n";
    } elseif ( $result->is_po_box() ) {
        echo "This is a PO Box\n";
    } else {
        echo "This is likely a commercial address\n";
    }
}
```

### Working with Address Components

[](#working-with-address-components)

```
$result = $client->validate( '1600 Amphitheatre Parkway, Mountain View, CA' );
if ( ! is_wp_error( $result ) ) {
    $components = $result->get_standardized_address();
    echo "Street: {$components['street_number']} {$components['street_name']}\n";
    echo "City: {$components['locality']}\n";
    echo "State: {$components['administrative_area']}\n";
    echo "ZIP: {$components['postal_code']}\n";
    echo "Country: {$components['country']}\n";
}
```

### Handling Responses with Caching

[](#handling-responses-with-caching)

```
// Initialize with custom cache duration (1 hour = 3600 seconds)
$client = new Client( 'your-api-key', true, 3600 );

// Results will be cached
$result = $client->validate( '1600 Amphitheatre Parkway, Mountain View, CA' );

// Clear specific cache
$client->clear_cache( 'validate_1600 Amphitheatre Parkway, Mountain View, CA' );

// Clear all validation caches
$client->clear_cache();
```

API Methods
-----------

[](#api-methods)

### Client Methods

[](#client-methods)

- `validate( $address, $region_code = '', $enable_usps = false, $previous_address = false)`: Validate an address
- `clear_cache( $identifier = null)`: Clear cached responses

### Response Methods

[](#response-methods)

#### Validation Methods

[](#validation-methods)

- `get_score()`: Get numerical validation score (0-100)
- `get_rating()`: Get human-readable validation rating
- `check_validity()`: Get detailed validation analysis
- `is_fully_validated()`: Check if address is completely validated
- `is_high_confidence()`: Check if address has high confidence validation
- `is_minimal_valid()`: Check if address meets minimal validation requirements
- `is_standardized()`: Check if address is in standard format
- `is_exact_match()`: Check if address is an exact match without inferences
- `is_verification_needed()`: Check if address needs additional verification
- `is_deliverable()`: Check if address is deliverable (USPS data for US addresses)
- `is_shippable()`: Check if address is valid for shipping
- `is_valid_landmark()`: Check if address is a valid landmark/POI
- `is_us_address()`: Check if address is in the United States
- `has_minimal_components()`: Check if address has required components

#### Address Properties

[](#address-properties)

- `is_business()`: Check if address is a business location
- `is_residential()`: Check if address is residential
- `is_po_box()`: Check if address is a PO Box
- `is_active()`: Check if address is active (USPS)
- `is_vacant()`: Check if address is vacant (USPS)
- `is_commercial_mail_receiver()`: Check if address is a CMRA (USPS)

#### Basic Example

[](#basic-example)

```
use ArrayPress\Google\AddressValidation\Client;

// Initialize client
$client = new Client( 'your-google-api-key' );

// Validate an address
$result = $client->validate( '1600 Amphitheatre Parkway, Mountain View, CA' );
if ( ! is_wp_error( $result ) ) {
    // Get detailed validation status
    $validity = $result->check_validity();

    if ( $validity['is_valid'] ) {
        echo "Confidence Level: {$validity['confidence_level']}\n";

        // Check specific validation aspects
        if ( $result->is_high_confidence() ) {
            echo "High confidence validation\n";
        }

        if ( $result->is_shippable() ) {
            echo "Valid shipping address\n";
        }
    } else {
        echo "Validation Issues:\n";
        foreach ( $validity['issues'] as $issue ) {
            echo "- $issue\n";
        }
    }
}
```

Use Cases
---------

[](#use-cases)

- **Address Verification**: Validate customer addresses with confidence scores
- **Data Standardization**: Standardize address data
- **USPS Integration**: Enhanced US address validation
- **Fraud Prevention**: Verify address authenticity
- **International Support**: Validate global addresses
- **Business Verification**: Identify business locations
- **Data Quality**: Assess and maintain address data quality with numerical metrics
- **Location Services**: Support location-based features

Contributing
------------

[](#contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

License
-------

[](#license)

This project is licensed under the GPL-2.0-or-later License.

Support
-------

[](#support)

- [Documentation](https://github.com/arraypress/google-address-validation)
- [Issue Tracker](https://github.com/arraypress/google-address-validation/issues)

###  Health Score

16

—

LowBetter than 6% of packages

Maintenance34

Infrequent updates — may be unmaintained

Popularity8

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity15

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/cd6eb8aff0903d87eb674d1ba3c5f3653899c0d7661504eb0deb7798ed86b643?d=identicon)[arraypress](/maintainers/arraypress)

---

Top Contributors

[![arraypress](https://avatars.githubusercontent.com/u/22668877?v=4)](https://github.com/arraypress "arraypress (12 commits)")

### Embed Badge

![Health badge](/badges/arraypress-google-address-validation/health.svg)

```
[![Health](https://phpackages.com/badges/arraypress-google-address-validation/health.svg)](https://phpackages.com/packages/arraypress-google-address-validation)
```

###  Alternatives

[google/apiclient

Client library for Google APIs

9.8k186.9M901](/packages/google-apiclient)[stripe/stripe-php

Stripe PHP Library

4.0k139.3M419](/packages/stripe-stripe-php)[webonyx/graphql-php

A PHP port of GraphQL reference implementation

4.7k75.4M279](/packages/webonyx-graphql-php)[twilio/sdk

A PHP wrapper for Twilio's API

1.6k90.6M252](/packages/twilio-sdk)[friendsofsymfony/jsrouting-bundle

A pretty nice way to expose your Symfony routing to client applications.

1.5k52.7M208](/packages/friendsofsymfony-jsrouting-bundle)[knplabs/github-api

GitHub API v3 client

2.2k15.3M171](/packages/knplabs-github-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
