Laravel integration for Nominatim Geocoding API Client

This package is a Laravel integration of the Nominatim Geocoding API Client.

Changelog

View the changelog.

Usage

Install package

composer require wimski/laravel-nominatim

Example

use Wimski\Nominatim\Contracts\GeocoderServiceInterface;
use Wimski\Nominatim\Objects\Coordinate;
use Wimski\Nominatim\RequestParameters\ForwardGeocodingQueryRequestParameters;

class MyClass
{
    public function __construct(
        protected GeocoderServiceInterface $geocoder,
    ) {
    }
    
    public function queryCoordinate(string $query): Coordinate
    {
        $requestParameters = ForwardGeocodingQueryRequestParameters::make($query)
            ->addCountryCode('nl')
            ->includeAddressDetails();
            
        $response = $this->geocoder->requestForwardGeocoding($request);
        
        return $response->getItems()[0]->getCoordinate();
    }
}

PSR HTTP

The underlying Client class uses Discovery by default to get instances of the following contracts:

• Psr\Http\Client\ClientInterface
• Psr\Http\Message\RequestFactoryInterface
• Psr\Http\Message\UriFactoryInterface

This means that you need to include (a) PSR compatible package(s) in your project.

If you already have setup a specific HTTP client configuration in your project, which you would also like to use for Nominatim requests, you can pass these in by extending the service provider.

1. Disable package discovery

composer.json

"extra": {
    "laravel": {
        "dont-discover": [
            "wimski/laravel-nominatim"
        ]
    }
}

2. Extend service provider

<?php

namespace App\Providers;

use Psr\Http\Client\ClientInterface as HttpClientInterface;
use Psr\Http\Message\RequestFactoryInterface;
use Psr\Http\Message\UriFactoryInterface;
use Wimski\LaravelNominatim\Providers\NominatimServiceProvider as ServiceProvider;

class NominatimServiceProvider extends ServiceProvider
{
    protected function getHttpClient() : ?HttpClientInterface
    {
        // return your configured HTTP client here
    }
    
    protected function getRequestFactory() : ?RequestFactoryInterface
    {
        // return your configured request factory here
    }
    
    protected function getUriFactory() : ?UriFactoryInterface
    {
        // return your configured uri factory here
    }
}

3. Include extended service provider

config/app.config

return [
    // ...
    
    'providers' => [
    
        /*
         * Application Service Providers...
         */
         App\Providers\NominatimServiceProvider::class,
    ],
    
    // ...
];

Services

Services for the following providers are currently available:

• Nominatim
  • NOMINATIM_SERVICE=nominatim
  • NOMINATIM_NOMINATIM_USER_AGENT= (required)
  • NOMINATIM_NOMINATIM_EMAIL= (required)
• LocationIQ
  • NOMINATIM_SERVICE=location_iq
  • NOMINATIM_LOCATION_IQ_KEY= (access token, required)
• Generic
  • NOMINATIM_SERVICE=generic

PHPUnit

composer run phpunit

PHPStan

composer run phpstan

Credits

• wimski
• All Contributors

License

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