PHPackages                             arraypress/google-distance-matrix - 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. arraypress/google-distance-matrix

ActiveLibrary

arraypress/google-distance-matrix
=================================

A PHP library for integrating with the Google Distance Matrix API in WordPress, providing travel distance and time calculations between multiple origins and destinations. Features WordPress transient caching and WP\_Error support.

11PHP

Since Jan 6Pushed 1y ago1 watchersCompare

[ Source](https://github.com/arraypress/google-distance-matrix)[ Packagist](https://packagist.org/packages/arraypress/google-distance-matrix)[ RSS](/packages/arraypress-google-distance-matrix/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Google Distance Matrix API for WordPress
========================================

[](#google-distance-matrix-api-for-wordpress)

A PHP library for integrating with the Google Distance Matrix API in WordPress. This library provides robust distance and time calculations between multiple origins and destinations with support for WordPress transient caching and WP\_Error handling.

Features
--------

[](#features)

- 📊 **Distance Calculations**: Calculate distances between multiple origins and destinations
- ⏱️ **Travel Times**: Get accurate travel duration with traffic considerations
- 🚗 **Multiple Modes**: Support for driving, walking, cycling, and transit modes
- 🌍 **International**: Support for distance calculations worldwide
- 📏 **Unit Flexibility**: Support for both metric and imperial measurements
- 🔄 **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
- 🚦 **Traffic Data**: Optional real-time traffic consideration
- 🗺️ **Route Options**: Support for route restrictions and preferences
- 🔗 **Fluent Interface**: Chainable methods for setting options

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

[](#requirements)

- PHP 7.4 or later
- WordPress 6.7.1 or later
- Google Distance Matrix API key

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

[](#installation)

Install via Composer:

```
composer require arraypress/google-distance-matrix
```

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

[](#basic-usage)

```
use ArrayPress\Google\DistanceMatrix\Client;

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

// Using fluent interface
$result = $client
	->set_mode( 'driving' )
	->set_units( 'imperial' )
	->set_avoid( 'tolls' )
	->calculate( 'New York, NY', 'Boston, MA' );

if ( ! is_wp_error( $result ) ) {
	// Get distance and duration
	$distance = $result->get_formatted_distance();
	$duration = $result->get_formatted_duration();

	echo "Distance: {$distance}\n";
	echo "Duration: {$duration}\n";

	// Get raw values in meters/seconds
	$meters  = $result->get_distance_meters();
	$seconds = $result->get_duration_seconds();
}
```

Setting Default Options
-----------------------

[](#setting-default-options)

```
// Set defaults for multiple calculations
$client
	->set_mode( 'driving' )
	->set_units( 'imperial' )
	->set_language( 'en' );

// Use defaults
$result1 = $client->calculate( 'New York, NY', 'Boston, MA' );

// Override specific options
$result2 = $client->calculate(
	'New York, NY',
	'Boston, MA',
	[ 'mode' => 'transit' ]
);

// Reset to default options
$client->reset_options();
```

Multiple Origins/Destinations
-----------------------------

[](#multiple-originsdestinations)

```
$origins = [
	'San Francisco, CA',
	'Los Angeles, CA'
];

$destinations = [
	'Las Vegas, NV',
	'Phoenix, AZ',
	'San Diego, CA'
];

$result = $client
	->set_mode( 'driving' )
	->set_units( 'imperial' )
	->calculate( $origins, $destinations );

if ( ! is_wp_error( $result ) ) {
	$distances = $result->get_all_distances();
	foreach ( $distances as $route ) {
		echo "From: {$route['origin']}\n";
		echo "To: {$route['destination']}\n";
		echo "Distance: {$route['distance']['text']}\n";
		echo "Duration: {$route['duration']['text']}\n\n";
	}
}
```

Available Options
-----------------

[](#available-options)

### Travel Modes

[](#travel-modes)

```
const VALID_MODES = [
    'driving',
    'walking',
    'bicycling',
    'transit'
];
```

### Units

[](#units)

```
const VALID_UNITS = [
    'metric',
    'imperial'
];
```

### Avoid Options

[](#avoid-options)

```
const VALID_AVOID = [
    'tolls',
    'highways',
    'ferries'
];
```

### Traffic Models

[](#traffic-models)

```
const VALID_TRAFFIC_MODELS = [
    'best_guess',
    'pessimistic',
    'optimistic'
];
```

### Default Options

[](#default-options)

```
const DEFAULT_OPTIONS = [
    'mode' => 'driving',
    'units' => 'metric',
    'language' => 'en'
];
```

### Working with Options Array

[](#working-with-options-array)

```
$result = $client->calculate(
    'New York, NY',
    'Boston, MA',
    [
        'mode' => 'driving',           // driving, walking, bicycling, transit
        'units' => 'imperial',         // metric or imperial
        'avoid' => 'tolls',           // tolls, highways, ferries
        'language' => 'en',           // response language
        'traffic_model' => 'best_guess' // best_guess, pessimistic, optimistic
    ]
);
```

### 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->calculate( 'New York, NY', 'Boston, MA' );

// Clear specific cache
$client->clear_cache( 'matrix_New York, NY_Boston, MA' );

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

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

[](#api-methods)

### Client Methods

[](#client-methods)

#### Option Setters

[](#option-setters)

- `set_mode( string $mode )`: Set travel mode
- `set_units( string $units )`: Set distance units
- `set_avoid(?string $avoid )`: Set features to avoid
- `set_language( string $language )`: Set response language
- `set_traffic_model(?string $model )`: Set traffic model
- `reset_options()`: Reset all options to defaults

#### Core Methods

[](#core-methods)

- `calculate( $origins, $destinations, $options = [] )`: Calculate distances
- `clear_cache( $identifier = null )`: Clear cached responses

### Response Methods

[](#response-methods)

#### Distance Methods

[](#distance-methods)

- `get_distance( $origin_index, $destination_index )`: Get distance data for specific pair
- `get_duration( $origin_index, $destination_index )`: Get duration data for specific pair
- `get_formatted_distance( $origin_index, $destination_index )`: Get formatted distance string
- `get_formatted_duration( $origin_index, $destination_index )`: Get formatted duration string
- `get_distance_meters( $origin_index, $destination_index )`: Get distance in meters
- `get_duration_seconds( $origin_index, $destination_index )`: Get duration in seconds

#### Data Access Methods

[](#data-access-methods)

- `get_origins()`: Get array of origin addresses
- `get_destinations()`: Get array of destination addresses
- `get_all_distances()`: Get all calculated distances in array format
- `get_element( $origin_index, $destination_index )`: Get specific matrix element
- `get_element_status( $origin_index, $destination_index )`: Get status of specific calculation
- `is_complete()`: Check if all calculations were successful
- `find_nearest_destination( $origin_index )`: Find nearest destination to specific origin

Use Cases
---------

[](#use-cases)

- **Delivery Planning**: Calculate delivery routes and times
- **Shipping Costs**: Distance-based shipping calculations
- **Service Areas**: Define and check service coverage areas
- **Route Optimization**: Find optimal routes for multiple destinations
- **Travel Time Estimation**: Accurate travel time calculations
- **Fleet Management**: Support for vehicle routing and planning
- **Coverage Analysis**: Analyze service area coverage
- **Location Planning**: Optimize location selection based on distance
- **E-commerce Shipping**: Calculate shipping costs based on distance
- **Service Radius**: Define service areas with time/distance constraints

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-distance-matrix)
- [Issue Tracker](https://github.com/arraypress/google-distance-matrix/issues)

###  Health Score

15

—

LowBetter than 3% of packages

Maintenance33

Infrequent updates — may be unmaintained

Popularity3

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity16

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 (10 commits)")

### Embed Badge

![Health badge](/badges/arraypress-google-distance-matrix/health.svg)

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

PHPackages © 2026

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