PHPackages                             fyennyi/nominatim-async - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. fyennyi/nominatim-async

ActiveLibrary[API Development](/categories/api)

fyennyi/nominatim-async
=======================

Asynchronous PHP client for Nominatim API with Guzzle Promises support.

v1.0.2(6mo ago)02181LicenseRef-CSSM-Unlimited-2.0PHPPHP ^8.1CI passing

Since Jan 23Pushed 1w agoCompare

[ Source](https://github.com/Fyennyi/nominatim-async)[ Packagist](https://packagist.org/packages/fyennyi/nominatim-async)[ Fund](https://opencollective.com/cssm)[ Patreon](https://www.patreon.com/ChernegaSergiy)[ RSS](/packages/fyennyi-nominatim-async/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (3)Dependencies (5)Versions (4)Used By (1)

[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner-direct.svg)](https://stand-with-ukraine.pp.ua)

Nominatim Async PHP Client
==========================

[](#nominatim-async-php-client)

[![Latest Stable Version](https://camo.githubusercontent.com/b04d3a18795468eee3d50ae731c41a9aec29259fc78da0963e28cbb3c9843212/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6679656e6e79692f6e6f6d696e6174696d2d6173796e632e7376673f6c6162656c3d5061636b6167697374266c6f676f3d7061636b6167697374)](https://packagist.org/packages/fyennyi/nominatim-async)[![Total Downloads](https://camo.githubusercontent.com/4d8a010b4f4d7846d52e1e4e74ae77499eb80922720d466b9a8842cb0b2072f3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6679656e6e79692f6e6f6d696e6174696d2d6173796e632e7376673f6c6162656c3d446f776e6c6f616473266c6f676f3d7061636b6167697374)](https://packagist.org/packages/fyennyi/nominatim-async)[![License](https://camo.githubusercontent.com/3310bf6e73993f69fb7475ba479dc00e0895944a130f0c02d1ba13144e6cf26d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6679656e6e79692f6e6f6d696e6174696d2d6173796e632e7376673f6c6162656c3d4c6963656e6365266c6f676f3d6f70656e2d736f757263652d696e6974696174697665)](https://packagist.org/packages/fyennyi/nominatim-async)[![Tests](https://camo.githubusercontent.com/74ae50d4bd99303ecf98e0b547fbbd8461c80b9575c88fda0a482bc1baa45190/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f4679656e6e79692f6e6f6d696e6174696d2d6173796e632f706870756e69742e796d6c3f6c6162656c3d5465737473266c6f676f3d676974687562)](https://github.com/Fyennyi/nominatim-async/actions/workflows/phpunit.yml)[![Test Coverage](https://camo.githubusercontent.com/41d1ccb128fd3b1eb94e247571e8f96b0ca0774f168f5eefa9bbdb3b82f9157c/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f4679656e6e79692f6e6f6d696e6174696d2d6173796e633f6c6162656c3d54657374253230436f766572616765266c6f676f3d636f6465636f76)](https://app.codecov.io/gh/Fyennyi/nominatim-async)

An asynchronous PHP client for the [Nominatim](https://nominatim.org/) API (OpenStreetMap), built on top of React Promises and `fyennyi/async-cache-php`. This library allows you to perform forward and reverse geocoding, address lookups, and more, without blocking your application's execution flow.

Installation
------------

[](#installation)

To install the Nominatim Async Client, run the following command in your terminal:

```
composer require fyennyi/nominatim-async
```

Usage
-----

[](#usage)

### Basic Setup

[](#basic-setup)

First, create a client instance. You can optionally pass a custom Guzzle client, a PSR-16 cache adapter, and a Symfony Rate Limiter.

```
require 'vendor/autoload.php';

use Fyennyi\Nominatim\Client;

$client = new Client();
```

### Searching (Geocoding)

[](#searching-geocoding)

Search for a place by query string or structured parameters.

```
// Simple query
$places = \React\Async\await($client->search('Kyiv, Ukraine'));

foreach ($places as $place) {
    echo $place->getDisplayName() . "\n";
    echo "Lat: " . $place->getLat() . ", Lon: " . $place->getLon() . "\n";
}

// Structured query with extra parameters
$places = \React\Async\await($client->search([
    'street' => 'Khreshchatyk',
    'city' => 'Kyiv',
    'country' => 'Ukraine'
], [
    'addressdetails' => 1,
    'limit' => 5
]));
```

### Reverse Geocoding

[](#reverse-geocoding)

Find a place by its coordinates (latitude and longitude).

```
$lat = 50.4501;
$lon = 30.5234;

$place = \React\Async\await($client->reverse($lat, $lon, ['zoom' => 18]));

if ($place) {
    echo "Found: " . $place->getDisplayName() . "\n";
    if ($address = $place->getAddress()) {
        echo "City: " . $address->getCity() . "\n";
    }
}
```

### Address Lookup

[](#address-lookup)

Look up details for specific OSM objects (Nodes, Ways, Relations).

```
$osm_ids = ['R146656', 'N240109189'];

$places = \React\Async\await($client->lookup($osm_ids, ['addressdetails' => 1]));

foreach ($places as $place) {
    echo "ID: " . $place->getOsmType() . $place->getOsmId() . "\n";
    echo "Name: " . $place->getDisplayName() . "\n";
}
```

### Place Details

[](#place-details)

Get detailed information about a place by its ID.

```
$place = \React\Async\await($client->details(['place_id' => 123456]));

echo "Category: " . $place->getCategory() . "\n";
echo "Type: " . $place->getType() . "\n";
```

### Server Status

[](#server-status)

Check the status of the Nominatim server.

```
// Get status as array
$status = \React\Async\await($client->status('json'));

echo "Status: " . $status['status'] . "\n";
echo "Message: " . $status['message'] . "\n";

// Get status as text
$text = \React\Async\await($client->status('text'));
echo $text; // "OK"
```

Asynchronous Operations
-----------------------

[](#asynchronous-operations)

The main advantage of this library is the ability to run multiple requests concurrently using React Promises.

```
use React\Promise\PromiseInterface;

$promises = [
    'kyiv' => $client->search('Kyiv'),
    'lviv' => $client->search('Lviv'),
    'reverse' => $client->reverse(50.45, 30.52),
];

$results = \React\Async\await(\React\Promise\all($promises));

$kyiv_places = $results['kyiv'];
$lviv_places = $results['lviv'];
$reverse_place = $results['reverse'];

echo "Found " . count($kyiv_places) . " places in Kyiv.\n";
echo "Found " . count($lviv_places) . " places in Lviv.\n";
echo "Reverse result: " . ($reverse_place ? $reverse_place->getDisplayName() : 'None') . "\n";
```

Models
------

[](#models)

### Place

[](#place)

The `Place` object represents a location returned by the API. It provides comprehensive getters for all standard Nominatim fields:

- `getPlaceId()`, `getOsmId()`, `getOsmType()`, `getLicence()`
- `getLat()`, `getLon()`, `getDisplayName()`, `getLabel()`, `getLocalName()`, `getName()`
- `getCategory()`, `getType()`, `getAddressType()`, `getImportance()`, `getCalculatedImportance()`
- `getPlaceRank()`, `getAddressRank()`, `getAdminLevel()`, `getAdminLevels()`
- `getBoundingBox()`, `getIcon()`, `getCentroid()`, `getGeometry()`, `getEntrances()`
- `getAddress()` (returns an `Address` object), `getAddressTags()`, `getExtraTags()`, `getNameDetails()`
- `getParentPlaceId()`, `getHouseNumber()`, `getCalculatedPostcode()`, `getIndexedDate()`, `getCalculatedWikipedia()`, `isArea()`

### Address

[](#address)

The `Address` object provides easy access to address components:

- `getCountry()`, `getCountryCode()`, `getContinent()`, `getState()`, `getIso31662Lvl4()`, `getRegion()`, `getStateDistrict()`, `getCounty()`
- `getMunicipality()`, `getCity()`, `getTown()`, `getVillage()`, `getSettlement()`, `getCityDistrict()`, `getDistrict()`, `getBorough()`
- `getSuburb()`, `getSubdivision()`, `getHamlet()`, `getCroft()`, `getIsolatedDwelling()`, `getNeighbourhood()`, `getAllotments()`, `getQuarter()`, `getCityBlock()`, `getResidential()`
- `getRoad()`, `getHouseNumber()`, `getHouseName()`, `getPostcode()`
- `getFarm()`, `getFarmyard()`, `getIndustrial()`, `getCommercial()`, `getRetail()`
- `getEmergency()`, `getHistoric()`, `getMilitary()`, `getNatural()`, `getLanduse()`, `getPlace()`, `getRailway()`, `getManMade()`, `getAerialway()`, `getBoundary()`, `getAmenity()`, `getAeroway()`, `getClub()`, `getCraft()`, `getLeisure()`, `getOffice()`, `getMountainPass()`, `getShop()`, `getTourism()`, `getBridge()`, `getTunnel()`, `getWaterway()`
- `get(string $key)`, `toArray()`

Caching
-------

[](#caching)

This library utilizes `fyennyi/async-cache-php` to provide seamless, non-blocking caching capabilities. You can pass any PSR-16 compatible cache implementation (e.g., from `symfony/cache`) to the `Client` constructor.

```
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;

$psr16Cache = new Psr16Cache(new FilesystemAdapter());
$client = new Client(null, $psr16Cache);
```

By default, requests are cached for **24 hours** to reduce load on the Nominatim servers and ensure compliance with usage policies. The client also implements rate limiting automatically (1 request/sec) using Symfony Rate Limiter.

### Custom Rate Limiter

[](#custom-rate-limiter)

You can provide your own Symfony rate limiter implementation:

```
use Symfony\Component\RateLimiter\RateLimiterFactory;
use Symfony\Component\RateLimiter\Storage\InMemoryStorage;

$factory = new RateLimiterFactory([
    'id' => 'nominatim_api',
    'policy' => 'fixed_window',
    'limit' => 1,
    'interval' => '1 second',
], new InMemoryStorage());

$client = new Client(null, $psr16Cache, 'MyApp/1.0', $factory);
```

Contributing
------------

[](#contributing)

Contributions are welcome and appreciated! Here's how you can contribute:

1. Fork the project
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

Please make sure to update tests as appropriate and adhere to the existing coding style.

License
-------

[](#license)

This library is licensed under the CSSM Unlimited License v2.0 (CSSM-ULv2). See the [LICENSE](LICENSE) file for details.

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance84

Actively maintained with recent releases

Popularity12

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 91.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

3

Last Release

206d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e2471bdadcf4a5ea969fe763a72d03fb46525b59a7e4cedc3ed4d855029e7785?d=identicon)[ChernegaSergiy](/maintainers/ChernegaSergiy)

---

Top Contributors

[![ChernegaSergiy](https://avatars.githubusercontent.com/u/60980650?v=4)](https://github.com/ChernegaSergiy "ChernegaSergiy (96 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (9 commits)")

---

Tags

api-clientasynccodecovgeocodingguzzle-promisesnominatimopenstreetmapphpphp-libraryphp8psr-16psr-18reverse-geocoding

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/fyennyi-nominatim-async/health.svg)

```
[![Health](https://phpackages.com/badges/fyennyi-nominatim-async/health.svg)](https://phpackages.com/packages/fyennyi-nominatim-async)
```

###  Alternatives

[laravel/framework

The Laravel Framework.

34.9k556.2M21.5k](/packages/laravel-framework)[shopware/platform

The Shopware e-commerce core

3.4k1.5M3](/packages/shopware-platform)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.8M674](/packages/shopware-core)[tempest/framework

The PHP framework that gets out of your way.

2.3k37.6k21](/packages/tempest-framework)[leantime/leantime

Open source project management system for non-project managers. Simple like Trello, powerful like Jira. Built with neurodiversity in mind.

11.3k4.0k](/packages/leantime-leantime)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

762297.9k53](/packages/civicrm-civicrm-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)