README

Universal geocoding and postal code lookup package for Laravel with support for multiple countries worldwide.

Features

• Multi-country support (UK, USA, Ukraine, Canada, and more)
• Multiple geocoding providers with automatic fallback
• Free UK postcode lookup via Postcodes.io API
• Google Maps Geocoding API integration for worldwide coverage
• Database caching to minimize API calls
• Reverse geocoding from coordinates to addresses
• Hierarchical region management
• Comprehensive test suite

Requirements

• PHP 8.1 or higher
• Laravel 10.0 or 11.0
• MySQL/PostgreSQL database

Installation

Install the package via Composer:

composer require kulykovoleksii/laravel-geocoding

Publish the configuration file:

php artisan vendor:publish --tag=geocoding-config

Publish and run migrations:

php artisan vendor:publish --tag=geocoding-migrations
php artisan migrate

Configuration

Add your Google Maps API key to .env (optional but recommended for worldwide coverage):

GOOGLE_MAPS_API_KEY=your_api_key_here

Get your API key at: https://console.cloud.google.com/google/maps-apis

Pricing: $200/month free credit (approximately 40,000 requests/month free)

Usage

Basic Usage

use Kulykovoleksii\Geocoding\Services\Geocoding\GeocodingService;

$geocoding = app(GeocodingService::class);

// Lookup UK postcode (uses free Postcodes.io)
$result = $geocoding->lookupPostalCode('SW1A 1AA');

echo $result->getFullAddress(); // Westminster, London, SW1A 1AA
echo $result->latitude;  // 51.5033
echo $result->longitude; // -0.1276

Lookup Different Countries

// USA ZIP code
$result = $geocoding->lookupPostalCode('90210');
echo $result->city;  // Beverly Hills
echo $result->state; // California

// Ukraine postal code
$result = $geocoding->lookupPostalCode('01001');
echo $result->city; // Kyiv

Geocode Full Address

$result = $geocoding->geocode('10 Downing Street, London, UK');

echo $result->latitude;   // 51.5033
echo $result->longitude;  // -0.1276
echo $result->postalCode; // SW1A 2AA

Reverse Geocoding

$result = $geocoding->reverseGeocode(51.5033, -0.1276);

echo $result->getFullAddress();
// Output: 10 Downing Street, Westminster, London, SW1A 2AA

Using Facade

use Kulykovoleksii\Geocoding\Facades\Geocoding;

$result = Geocoding::lookupPostalCode('SW1A 1AA');

Working with Regions

use Kulykovoleksii\Geocoding\Models\Region;
use Kulykovoleksii\Geocoding\Models\PostalCode;

// Create region hierarchy
$uk = Region::create([
    'name' => 'United Kingdom',
    'slug' => 'uk',
    'country_code' => 'GB',
    'type' => 'country',
]);

$london = Region::create([
    'name' => 'London',
    'slug' => 'london',
    'country_code' => 'GB',
    'type' => 'city',
    'parent_id' => $uk->id,
]);

// Query regions
$ukRegions = Region::byCountry('GB')->get();
$cities = Region::byType('city')->get();
$countries = Region::roots()->get();

Supported Postal Code Formats

Geocoding Providers

Postcodes.io (UK only, free)

Automatically used for UK postcodes. No configuration required.

Google Maps Geocoding API (Universal)

Used for non-UK addresses or when Postcodes.io doesn't have data. Requires API key in configuration.

Caching Strategy

All geocoding results are automatically cached in the database:

1. First lookup checks the database cache
2. If not found, queries the appropriate geocoding provider
3. Results are stored in the postal_codes table
4. Subsequent lookups use cached data
5. Reverse geocoding uses proximity search for nearby cached coordinates

This minimizes API calls and costs, especially for paid services like Google Maps.

Testing

Run the test suite:

composer test

Or using PHPUnit directly:

vendor/bin/phpunit

Contributing

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

Security

If you discover any security-related issues, please email oleksii.eng@gmail.com instead of using the issue tracker.

Credits

• Oleksii Kulykov

License

The MIT License (MIT). Please see License File for more information.