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(3mo ago)01891LicenseRef-CSSM-Unlimited-2.0PHPPHP ^8.1CI passing

Since Jan 23Pushed 2mo 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 1mo ago

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

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 Guzzle Promises. 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 and a PSR-16 cache adapter.

```
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
$promise = $client->search('Kyiv, Ukraine');

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

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

$places = $promise->wait();
```

### Reverse Geocoding

[](#reverse-geocoding)

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

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

$client->reverse($lat, $lon, ['zoom' => 18])
    ->then(function ($place) {
        if ($place) {
            echo "Found: " . $place->getDisplayName() . "\n";
            if ($address = $place->getAddress()) {
                echo "City: " . $address->getCity() . "\n";
            }
        }
    })
    ->wait();
```

### Address Lookup

[](#address-lookup)

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

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

$client->lookup($osm_ids, ['addressdetails' => 1])
    ->then(function ($places) {
        foreach ($places as $place) {
            echo "ID: " . $place->getOsmType() . $place->getOsmId() . "\n";
            echo "Name: " . $place->getDisplayName() . "\n";
        }
    })
    ->wait();
```

### Place Details

[](#place-details)

Get detailed information about a place by its ID.

```
$client->details(['place_id' => 123456])
    ->then(function ($place) {
        echo "Category: " . $place->getCategory() . "\n";
        echo "Type: " . $place->getType() . "\n";
    })
    ->wait();
```

### Server Status

[](#server-status)

Check the status of the Nominatim server.

```
// Get status as array
$client->status('json')
    ->then(function ($status) {
        echo "Status: " . $status['status'] . "\n";
        echo "Message: " . $status['message'] . "\n";
    })
    ->wait();

// Get status as text
$text = $client->status('text')->wait();
echo $text; // "OK"
```

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

[](#asynchronous-operations)

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

```
use GuzzleHttp\Promise\Utils;

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

Utils::all($promises)->then(function ($results) {
    $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";
})->wait();
```

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.

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

39

—

LowBetter than 86% of packages

Maintenance83

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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

108d 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 (67 commits)")

---

Tags

api-clientasyncgeocodingguzzle-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

[thecodingmachine/graphqlite

Write your GraphQL queries in simple to write controllers (using webonyx/graphql-php).

5723.1M30](/packages/thecodingmachine-graphqlite)[commercetools/commercetools-sdk

The official PHP SDK for the commercetools Composable Commerce APIs

19281.5k](/packages/commercetools-commercetools-sdk)

PHPackages © 2026

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