Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Wrapper Nominatim API

Latest Stable Version Build Status Scrutinizer Code Quality Total Downloads MIT licensed


A simple interface to OSM Nominatim.

See Nominatim documentation for info on the service.


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 = "";
$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);

Or do a details query (by place_id):

$details = $nominatim->newDetails()

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

Or do a details query (by osm type and osm id):

$details = $nominatim->newDetails()

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

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 = "";
$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 :, please see Nominatim usage policy.