📡 Wrapper for Nominatim API
Clone or download


Wrapper Nominatim API

Latest Stable Version Build Status Scrutinizer Code Quality Total Downloads Join the chat at https://gitter.im/maxhelias/php-nominatim MIT licensed


A simple interface to OSM Nominatim.

See Nominatim documentation for info on the service.

See the PhpDoc of the project.


Install the package through composer:

composer require maxh/php-nominatim

Make sure, that you include the composer autoloader somewhere in your codebase.

Basic usage

Create a new instance of Nominatim.

use maxh\Nominatim\Nominatim;

$url = "http://nominatim.openstreetmap.org/";
$nominatim = new Nominatim($url);

Searching by query :

$search = $nominatim->newSearch();


Or break it down by address :

$search = $nominatim->newSearch()
            ->polygon('geojson')    //or 'kml', 'svg' and 'text'

$result = $nominatim->find($search);

Or do a reverse query :

$reverse = $nominatim->newReverse()
            ->latlon(43.4843941, -1.4960842);

$result = $nominatim->find($reverse);

Or do a lookup query :

$lookup = $nominatim->newLookup()

$result = $nominatim->find($lookup);

By default, the output format of the request is json and the wrapper return a array of results. It can be also xml, but the wrapper return a object SimpleXMLElement

How to override request header ?

There are two possibilities :

  1. By Nominatim instance, for all request :
$nominatim = new Nominatim($url, [
    'verify' => false
  1. By find method, for a request :
$result = $nominatim->find($lookup, [
    'verify' => false

How to customize HTTP client configuration ?

You can inject your own HTTP client with your specific configuration. For instance, you can edit user-agent and timeout for all your requests

use maxh\Nominatim\Nominatim;
use GuzzleHttp\Client;

$url = "http://nominatim.openstreetmap.org/";
$defaultHeader = [
    'verify' => false,
    'headers', array('User-Agent' => 'api_client')

$client = new Client([
    'base_uri'           => $url,
    'timeout'            => 30,
    'connection_timeout' => 5,

$nominatim = new Nominatim($url, $defaultHeader, $client);


This projet was inpired by the Opendi/nominatim project with more features like reverse query, support of the xml format, customize HTTP client and more on which i work.

Recall Usage Policy Nominatim

If you use the service : http://nominatim.openstreetmap.org/, please see Nominatim usage policy.