README

Nominatim Geocoding API Client

Changelog

View the changelog.

Usage

Install package

composer require wimski/nominatim-geocoding-api-client

Example

use Wimski\Nominatim\Client;
use Wimski\Nominatim\Config\NominatimConfig;
use Wimski\Nominatim\GeocoderServices\NominatimGeocoderService;
use Wimski\Nominatim\RequestParameters\ForwardGeocodingQueryRequestParameters;
use Wimski\Nominatim\Transformers\GeocodingResponseTransformer;

$config = new NominatimConfig(
    'my-custom-user-agent',
    'email@provider.net',
);

$service = new NominatimGeocoderService(
    new Client(),
    new GeocodingResponseTransformer(),
    $config,
);

$requestParameters = ForwardGeocodingQueryRequestParameters::make('some query')
    ->addCountryCode('nl')
    ->includeAddressDetails();

$response = $service->requestForwardGeocoding($requestParameters);

// Get data from the response
$latitude = $response->getItems()[0]->getCoordinate()->getLatitude();

PSR HTTP

The 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 that as a constructor argument to the Client:

$service = new NominatimGeocoderService(
    new Client($myCustomPsrHttpClient),
    new GeocodingResponseTransformer(),
    new NominatimConfig('user-agent', 'email@provider.net'),
);

Services

Services for the following providers are currently available:

• Nominatim
• LocationIQ
• Generic: without any implementation specific headers or parameters.

Custom services can easily be created by extending the AbstractGeocoderService as long as the provider implements the Nominatim spec correctly.

PHPUnit

composer run phpunit

PHPStan

composer run phpstan

Credits

• wimski
• All Contributors

License

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