PHPackages                             nonsapiens/realaddressfactory - 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. [Utility & Helpers](/categories/utility)
4. /
5. nonsapiens/realaddressfactory

ActiveLibrary[Utility & Helpers](/categories/utility)

nonsapiens/realaddressfactory
=============================

Creates real-world street addresses from Google Maps, to use in database seeding, unit tests, or anything else. Supports Laravel 11+, and Faker

v3.1.2(5mo ago)4910.2k↓18.2%4[1 issues](https://github.com/nonsapiens/realaddressfactory/issues)7MITPHPPHP ^8.3|8.4

Since Jun 4Pushed 5mo ago3 watchersCompare

[ Source](https://github.com/nonsapiens/realaddressfactory)[ Packagist](https://packagist.org/packages/nonsapiens/realaddressfactory)[ Docs](https://github.com/nonsapiens/realaddressfactory)[ RSS](/packages/nonsapiens-realaddressfactory/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (6)Versions (11)Used By (7)

RealAddress Generator
=====================

[](#realaddress-generator)

About
-----

[](#about)

This Laravel 8+ library creates actual, 100% real addresses, with full address details and lat/long coordinates Using the Google Maps API, these addresses can be created using the RealAddress classes, and also supports Faker, so you can use RealAddress in your database seeding!

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

[](#installation)

Require this package with composer using the following command:

```
composer require nonsapiens/realaddressfactory --dev
```

To optionally publish the config file, run:

```
php artisan vendor:publish --provider="Nonsapiens\RealAddressFactory\RealAddressFactoryServiceProvider"
```

### Google Maps API

[](#google-maps-api)

As this library relies on Google Maps, your Google Maps API key needs to be defined in your `.env` file:

```
GOOGLE_MAPS_API_KEY=abcdefghijklmnopqrstuv

```

If you don't have an API key, [get one here](https://developers.google.com/maps/documentation/javascript/get-api-key)

Usage
-----

[](#usage)

RealAddress offers three different ways of generating real-world addresses. [Each of these methods return the `\Geocoder\Provider\GoogleMaps\Model\GoogleAddress` class](http://geocoder-php.org/Geocoder/), which takes the Google Maps API response and standardises it in an easy-to-use, easy-to-read manner. As standard, RealAddress supports the generating of real addresses for the following countries:

- United States of America
- Great Britain
- France
- Germany
- South Africa
- Russia
- Australia

You can extend RealAddress by adding additional countries in the `config/realaddress.php` config file. This config file also defines which cities in a given country addresses can be created for. Additional cities can be defined here.

### Faker

[](#faker)

RealAddress provides additional functions for Faker's `\Faker\Generator` class instance. The code example below shows typical usage in a Factory class:

```
class UserFactory extends Factory
{
    protected $model = User::class;

    public function definition(): array
    {
        /** @var GoogleAddress $address */
        $address = $this->faker->britishAddress();

        return [
            'first_name' => $this->faker->firstName($gender),
            'last_name' => $this->faker->lastName,
            'full_address' => $address->getFormattedAddress(),
		    'latitude' => $address->getCoordinates()->getLatitude(),
		    'longitude' => $address->getCoordinates()->getLongitude()
        ];
    }
}
```

Similarly, the address can be limited to a specific city: `$address = $faker->britishAddress('London');`

or can be generated randomly between multiple-defined cities: `$address = $faker->britishAddress(['London', 'Manchester']);`

... where these cities must be defined in `config/realaddress.php` in order to work.

The ready-to-use faker functions include:

- `britishAddress()`
- `usaAddress()`
- `germanAddress()`
- `frenchAddress()`
- `southAfricanAddress()`
- `russianAddress()`

If you have extended `config/realaddress.php` to include a new country, you can generate an address for it with:

```
	$address = $faker->realAddress('Brazil')						# From any of the defined cities
	$address = $faker->realAddress('Brazil', 'Rio de Janiero');		# For Rio de Janiero only
	$address = $faker->realAddresss('Brazil', ['Rio de Janiero', 'Salvador'])	# Multiple cities
```

### Using the Facade

[](#using-the-facade)

Using the Facade allows you to generate real-world addresses at runtime, and also allows *multiple* addresses to be generated at once. The code examples below show typical RealAddress facade usage:

```
use Nonsapiens\RealAddressFactory\Facades\RealAddress;
.
.
.
$johannesburgAddresses          = RealAddress::makeSouthAfrica(20, 'Johannesburg');		# 20 addresses for Johannesburg, South Africa
$frenchAddress                  = RealAddress::makeFrance(1);							# A single address for France
$brazilAddresses                = RealAddress::make(10, 'Brazil');						# 10 addresses for the custom country of Brazil
```

### Using the RealAddress class

[](#using-the-realaddress-class)

Functionally, provides the same methods as the Facade above:

```
use Nonsapiens\RealAddressFactory\RealAddressFactory;

$f = new RealAddressFactory();

$southAfricanPoints = $f->makeSouthAfrica(4);                # Generates 4 locations within South Africa's major cities
$capeTownPoints     = $f->makeSouthAfrica(2, 'Cape Town');   # Generates 2 locations from Cape Town, South Africa
$multiPoints        = $f->makeSouthAfrica(3, ['Pretoria', 'Johannesburg']);
```

### Adding new countries or cities

[](#adding-new-countries-or-cities)

An example of extending the `config/realaddress.php` array to include Kenya, and two cities:

```
'kenya' => [
		'cities' => [ 'Nairobi', 'Mombasa' ],
	   ],
```

Note that the cities defined here must be identifiable to Google Maps, and should ideally be spelt in their English variant.

### Warning

[](#warning)

Extended and heavy use of this factory may cause Google to block your key. Heavy use may also attract GCP API charges, subject to Google's Places API costing structure. To help prevent this, there is a built in rate-limiter, that blocks too many calls being made to the Google API. This value is configurable inside the `config/realaddress.php` config file

About the author
----------------

[](#about-the-author)

[**Stuart Steedman**](https://www.linkedin.com/in/stuart-steedman-b612a537/) is CTO of [Sebenza](https://sebenza.tech), a [DNI](https://www.dninvest.co.za) company operating in Bryanston, where we fit free wifi routers to minibus taxis across South Africa, as well as enabling digital fare collection for the transport industry. He specialises in Laravel development, and is a speaker at tech and development related conferences, including BotCon, AfricaStream, DevConf and more.

###  Health Score

53

—

FairBetter than 97% of packages

Maintenance69

Regular maintenance activity

Popularity38

Limited adoption so far

Community22

Small or concentrated contributor base

Maturity71

Established project with proven stability

 Bus Factor2

2 contributors hold 50%+ of commits

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.

###  Release Activity

Cadence

Every ~158 days

Recently: every ~96 days

Total

9

Last Release

176d ago

Major Versions

v2.0.2 → v3.0.02024-11-04

PHP version history (3 changes)v2.0.0PHP >=7.3.0

v3.0.0PHP ^8.3

v3.1.0PHP ^8.3|8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/6d8b2540548fd4037017a3177a24b230506c67ca96d5ed870cd82153726e597f?d=identicon)[nonsapiens](/maintainers/nonsapiens)

---

Top Contributors

[![stuartsteedman](https://avatars.githubusercontent.com/u/69784087?v=4)](https://github.com/stuartsteedman "stuartsteedman (6 commits)")[![Jonathan-Maurer](https://avatars.githubusercontent.com/u/78354815?v=4)](https://github.com/Jonathan-Maurer "Jonathan-Maurer (5 commits)")[![stuartsebenza](https://avatars.githubusercontent.com/u/111981335?v=4)](https://github.com/stuartsebenza "stuartsebenza (5 commits)")[![nonsapiens](https://avatars.githubusercontent.com/u/9744534?v=4)](https://github.com/nonsapiens "nonsapiens (1 commits)")

---

Tags

addressAddressFactoryRealAddressFactory

### Embed Badge

![Health badge](/badges/nonsapiens-realaddressfactory/health.svg)

```
[![Health](https://phpackages.com/badges/nonsapiens-realaddressfactory/health.svg)](https://phpackages.com/packages/nonsapiens-realaddressfactory)
```

###  Alternatives

[blair2004/nexopos

The Free Modern Point Of Sale System build with Laravel, TailwindCSS and Vue.js.

1.2k2.3k](/packages/blair2004-nexopos)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)[tomshaw/electricgrid

A feature-rich Livewire package designed for projects that require dynamic, interactive data tables.

116.6k](/packages/tomshaw-electricgrid)

PHPackages © 2026

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