├── .php-cs-fixer.php ├── LICENSE ├── README.md ├── composer.json └── src ├── Details.php ├── Exceptions ├── InvalidParameterException.php └── NominatimException.php ├── Lookup.php ├── Nominatim.php ├── Query.php ├── QueryInterface.php ├── Reverse.php └── Search.php /.php-cs-fixer.php: -------------------------------------------------------------------------------- 1 | 6 | This source file is subject to the MIT license that is bundled 7 | with this source code in the file LICENSE. 8 | EOF; 9 | 10 | $finder = (new PhpCsFixer\Finder()) 11 | ->in(__DIR__ . '/examples') 12 | ->in(__DIR__ . '/src') 13 | ->in(__DIR__ . '/tests') 14 | ; 15 | 16 | return (new PhpCsFixer\Config()) 17 | ->setRiskyAllowed(true) 18 | ->setRules([ 19 | '@PhpCsFixer' => true, 20 | '@PhpCsFixer:risky' => true, 21 | '@PHP74Migration:risky' => true, 22 | '@PHPUnit84Migration:risky' => true, 23 | 'date_time_immutable' => true, 24 | 'general_phpdoc_annotation_remove' => [ 25 | 'annotations' => [ 26 | 'expectedException', 27 | 'expectedExceptionMessage', 28 | 'expectedExceptionMessageRegExp' 29 | ] 30 | ], 31 | 'global_namespace_import' => true, 32 | 'header_comment' => [ 33 | 'comment_type' => 'PHPDoc', 34 | 'header' => $header, 35 | 'location' => 'after_declare_strict' 36 | ], 37 | 'linebreak_after_opening_tag' => true, 38 | 'list_syntax' => ['syntax' => 'short'], 39 | 'mb_str_functions' => true, 40 | 'nullable_type_declaration_for_default_null_value' => true, 41 | 'ordered_interfaces' => true, 42 | 'php_unit_strict' => false, 43 | 'phpdoc_line_span' => true, 44 | 'self_static_accessor' => true, 45 | 'simplified_null_return' => true, 46 | ]) 47 | ->setFinder($finder) 48 | ->setCacheFile(__DIR__.'/.php_cs.cache'); 49 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2016 Maxime Helias 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | Wrapper Nominatim API 2 | ================ 3 | 4 | [![Latest Stable Version](https://poser.pugx.org/maxh/php-nominatim/v/stable)](https://packagist.org/packages/maxh/php-nominatim) 5 | [![Build Status](https://travis-ci.com/maxhelias/php-nominatim.svg?branch=master)](https://travis-ci.com/maxhelias/php-nominatim) 6 | [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/maxhelias/php-nominatim/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/maxhelias/php-nominatim/?branch=master) 7 | [![Total Downloads](https://poser.pugx.org/maxh/php-nominatim/downloads)](https://packagist.org/packages/maxh/php-nominatim) 8 | [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/maxhelias/php-nominatim/blob/master/LICENSE) 9 | 10 | [![SensioLabsInsight](https://insight.sensiolabs.com/projects/c54e5519-01fd-4855-980f-3a28c5f6ff12/big.png)](https://insight.sensiolabs.com/projects/c54e5519-01fd-4855-980f-3a28c5f6ff12) 11 | 12 | A simple interface to OSM Nominatim. 13 | 14 | 15 | See [Nominatim documentation](http://wiki.openstreetmap.org/wiki/Nominatim) for info on the service. 16 | 17 | Installation 18 | ------------ 19 | 20 | Install the package through [composer](http://getcomposer.org): 21 | 22 | ```bash 23 | composer require maxh/php-nominatim 24 | ``` 25 | 26 | Make sure, that you include the composer [autoloader](https://getcomposer.org/doc/01-basic-usage.md#autoloading) 27 | somewhere in your codebase. 28 | 29 | Basic usage 30 | ----------- 31 | 32 | Create a new instance of Nominatim. 33 | 34 | ```php 35 | use maxh\Nominatim\Nominatim; 36 | 37 | $url = "http://nominatim.openstreetmap.org/"; 38 | $nominatim = new Nominatim($url); 39 | ``` 40 | 41 | Searching by query : 42 | 43 | ```php 44 | $search = $nominatim->newSearch(); 45 | $search->query('HelloWorld'); 46 | 47 | $nominatim->find($search); 48 | ``` 49 | 50 | Or break it down by address : 51 | 52 | ```php 53 | $search = $nominatim->newSearch() 54 | ->country('France') 55 | ->city('Bayonne') 56 | ->postalCode('64100') 57 | ->polygon('geojson') //or 'kml', 'svg' and 'text' 58 | ->addressDetails(); 59 | 60 | $result = $nominatim->find($search); 61 | ``` 62 | 63 | Or do a reverse query : 64 | 65 | ```php 66 | $reverse = $nominatim->newReverse() 67 | ->latlon(43.4843941, -1.4960842); 68 | 69 | $result = $nominatim->find($reverse); 70 | ``` 71 | 72 | Or do a lookup query : 73 | 74 | ```php 75 | $lookup = $nominatim->newLookup() 76 | ->format('xml') 77 | ->osmIds('R146656,W104393803,N240109189') 78 | ->nameDetails(true); 79 | 80 | $result = $nominatim->find($lookup); 81 | ``` 82 | 83 | Or do a details query (by place_id): 84 | 85 | ```php 86 | $details = $nominatim->newDetails() 87 | ->placeId(1234) 88 | ->polygon('geojson'); 89 | 90 | $result = $nominatim->find($details); 91 | ``` 92 | 93 | Or do a details query (by osm type and osm id): 94 | 95 | ```php 96 | $details = $nominatim->newDetails() 97 | ->osmType('R') 98 | ->osmId(1234) 99 | ->polygon('geojson'); 100 | 101 | $result = $nominatim->find($details); 102 | ``` 103 | 104 | By default, the output format of the request is json and the wrapper return a array of results. 105 | It can be also xml, but the wrapper return a object [SimpleXMLElement](http://php.net/manual/fr/simplexml.examples-basic.php) 106 | 107 | How to override request header ? 108 | -------------------------------- 109 | 110 | There are two possibilities : 111 | 112 | 1. By `Nominatim` instance, for all request : 113 | ```php 114 | $nominatim = new Nominatim($url, [ 115 | 'verify' => false 116 | ]); 117 | ``` 118 | 2. By `find` method, for a request : 119 | ````php 120 | $result = $nominatim->find($lookup, [ 121 | 'verify' => false 122 | ]); 123 | ```` 124 | 125 | How to customize HTTP client configuration ? 126 | -------------------------------------------- 127 | 128 | You can inject your own HTTP client with your specific configuration. For instance, you can edit user-agent and timeout for all your requests 129 | 130 | ```php 131 | false, 138 | 'headers', array('User-Agent' => 'api_client') 139 | ]; 140 | 141 | $client = new Client([ 142 | 'base_uri' => $url, 143 | 'timeout' => 30, 144 | 'connection_timeout' => 5, 145 | ]); 146 | 147 | $nominatim = new Nominatim($url, $defaultHeader, $client); 148 | ``` 149 | 150 | Note 151 | ---- 152 | 153 | This projet was inpired by the [Opendi/nominatim](https://github.com/opendi/nominatim) project with more features like reverse query, support of the xml format, customize HTTP client and more on which i work. 154 | 155 | Recall Usage Policy Nominatim 156 | ----------------------------- 157 | 158 | If you use the service : [http://nominatim.openstreetmap.org/](http://nominatim.openstreetmap.org/), please see [Nominatim usage policy](http://wiki.openstreetmap.org/wiki/Nominatim_usage_policy). 159 | -------------------------------------------------------------------------------- /composer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "maxh/php-nominatim", 3 | "type": "library", 4 | "description": "Wrapper for Nominatim API", 5 | "keywords": ["geo", "geolocation", "open street map", "osm", "nominatim", "web service"], 6 | "homepage": "https://github.com/maxhelias/php-nominatim", 7 | "license": "MIT", 8 | "authors": [ 9 | { 10 | "name": "Maxime Helias", 11 | "email": "maximehelias16@gmail.com", 12 | "homepage": "http://maximehelias.com", 13 | "role": "Developer" 14 | } 15 | ], 16 | "require": { 17 | "php": ">=7.3", 18 | "ext-mbstring": "*", 19 | "guzzlehttp/guzzle": "@stable" 20 | }, 21 | "require-dev": { 22 | "phpunit/phpunit": "^8.5|^9.2", 23 | "friendsofphp/php-cs-fixer": "dev-master", 24 | "phpro/grumphp-shim": "^1.4" 25 | }, 26 | "autoload": { 27 | "psr-4": { "maxh\\Nominatim\\": "src"} 28 | }, 29 | "autoload-dev": { 30 | "psr-4": { 31 | "maxh\\Nominatim\\Tests\\": "tests/" 32 | } 33 | }, 34 | "scripts": { 35 | "test": "vendor/bin/phpunit", 36 | "php-cs-fixer": "vendor/bin/php-cs-fixer fix" 37 | } 38 | } 39 | -------------------------------------------------------------------------------- /src/Details.php: -------------------------------------------------------------------------------- 1 | 8 | * This source file is subject to the MIT license that is bundled 9 | * with this source code in the file LICENSE. 10 | */ 11 | 12 | namespace maxh\Nominatim; 13 | 14 | use maxh\Nominatim\Exceptions\InvalidParameterException; 15 | 16 | /** 17 | * Lookup details about a single place by id. 18 | * 19 | * @see http://wiki.openstreetmap.org/wiki/Nominatim 20 | */ 21 | class Details extends Query 22 | { 23 | /** 24 | * OSM Type accepted (Node/Way/Relation). 25 | * 26 | * @var array 27 | */ 28 | private $osmType = ['N', 'W', 'R']; 29 | 30 | /** 31 | * Constructor. 32 | * 33 | * @param array $query Default value for this query 34 | */ 35 | public function __construct(array &$query = []) 36 | { 37 | parent::__construct($query); 38 | 39 | $this->setPath('details'); 40 | 41 | $this->acceptedFormat[] = 'html'; 42 | $this->acceptedFormat[] = 'jsonv2'; 43 | } 44 | 45 | /** 46 | * Place information by placeId. 47 | * 48 | * @return Details 49 | */ 50 | public function placeId(int $placeId): self 51 | { 52 | $this->query['place_id'] = $placeId; 53 | 54 | return $this; 55 | } 56 | 57 | /** 58 | * [osmType description]. 59 | * 60 | * @throws \maxh\Nominatim\Exceptions\InvalidParameterException if osm type is not supported 61 | * 62 | * @return \maxh\Nominatim\Reverse 63 | */ 64 | public function osmType(string $type): self 65 | { 66 | if (\in_array($type, $this->osmType, true)) { 67 | $this->query['osmtype'] = $type; 68 | 69 | return $this; 70 | } 71 | 72 | throw new InvalidParameterException('OSM Type is not supported'); 73 | } 74 | 75 | /** 76 | * Place information by osmtype and osmid. 77 | * 78 | * @return Details 79 | */ 80 | public function osmId(int $osmId): self 81 | { 82 | $this->query['osmid'] = $osmId; 83 | 84 | return $this; 85 | } 86 | } 87 | -------------------------------------------------------------------------------- /src/Exceptions/InvalidParameterException.php: -------------------------------------------------------------------------------- 1 | 8 | * This source file is subject to the MIT license that is bundled 9 | * with this source code in the file LICENSE. 10 | */ 11 | 12 | namespace maxh\Nominatim\Exceptions; 13 | 14 | use Exception; 15 | 16 | /** 17 | * InvalidParameterException exception is thrown when a request failed because of a bad client configuration. 18 | * 19 | * InvalidParameterException appears when the request failed because of a bad parameter from 20 | * the client request. 21 | * 22 | * @category Exceptions 23 | */ 24 | class InvalidParameterException extends Exception 25 | { 26 | } 27 | -------------------------------------------------------------------------------- /src/Exceptions/NominatimException.php: -------------------------------------------------------------------------------- 1 | 8 | * This source file is subject to the MIT license that is bundled 9 | * with this source code in the file LICENSE. 10 | */ 11 | 12 | namespace maxh\Nominatim\Exceptions; 13 | 14 | use Exception; 15 | use GuzzleHttp\Promise\PromiseInterface; 16 | use Psr\Http\Message\RequestInterface; 17 | use Psr\Http\Message\ResponseInterface; 18 | 19 | /** 20 | * InvalidParameterException exception is thrown when a request failed because of a bad client configuration. 21 | * 22 | * InvalidParameterException appears when the request failed because of a bad parameter from 23 | * the client request. 24 | * 25 | * @category Exceptions 26 | */ 27 | class NominatimException extends Exception 28 | { 29 | /** 30 | * Contain the request. 31 | * 32 | * @var RequestInterface 33 | */ 34 | private $request; 35 | 36 | /** 37 | * Contain the response. 38 | * 39 | * @var ResponseInterface 40 | */ 41 | private $response; 42 | 43 | /** 44 | * Constructor. 45 | * 46 | * @param string $message Message of this exception 47 | * @param null|RequestInterface $request The request instance 48 | * @param null|ResponseInterface $response The response of the request 49 | * @param null|Exception $previous Exception object 50 | */ 51 | public function __construct( 52 | $message, 53 | ?RequestInterface $request = null, 54 | ?ResponseInterface $response = null, 55 | ?Exception $previous = null 56 | ) { 57 | // Set the code of the exception if the response is set and not future. 58 | $code = $response && !($response instanceof PromiseInterface) ? $response->getStatusCode() : 0; 59 | 60 | parent::__construct($message, $code, $previous); 61 | 62 | $this->request = $request; 63 | $this->response = $response; 64 | } 65 | 66 | /** 67 | * Return the Request. 68 | */ 69 | public function getRequest(): RequestInterface 70 | { 71 | return $this->request; 72 | } 73 | 74 | /** 75 | * Return the Response. 76 | * 77 | * @return ResponseInterface 78 | */ 79 | public function getResponse() 80 | { 81 | return $this->response; 82 | } 83 | } 84 | -------------------------------------------------------------------------------- /src/Lookup.php: -------------------------------------------------------------------------------- 1 | 8 | * This source file is subject to the MIT license that is bundled 9 | * with this source code in the file LICENSE. 10 | */ 11 | 12 | namespace maxh\Nominatim; 13 | 14 | use maxh\Nominatim\Exceptions\InvalidParameterException; 15 | 16 | /** 17 | * Lookup the address of one or multiple OSM objects like node, way or relation. 18 | * 19 | * @see http://wiki.openstreetmap.org/wiki/Nominatim 20 | */ 21 | class Lookup extends Query 22 | { 23 | /** 24 | * Constuctor. 25 | * 26 | * @param array $query Default value for this query 27 | */ 28 | public function __construct(array &$query = []) 29 | { 30 | parent::__construct($query); 31 | 32 | $this->setPath('lookup'); 33 | } 34 | 35 | // -- Builder methods ------------------------------------------------------ 36 | 37 | /** 38 | * A list of up to 50 specific osm node, way or relations ids to return the addresses for. 39 | * 40 | * @return \maxh\Nominatim\Lookup 41 | */ 42 | public function osmIds(string $id): self 43 | { 44 | $this->query['osm_ids'] = $id; 45 | 46 | return $this; 47 | } 48 | 49 | /** 50 | * Output format for the geometry of results. 51 | * 52 | * @throws \maxh\Nominatim\Exceptions\InvalidParameterException Polygon is not supported with lookup 53 | */ 54 | public function polygon(string $polygon): void 55 | { 56 | throw new InvalidParameterException('The polygon is not supported with lookup'); 57 | } 58 | } 59 | -------------------------------------------------------------------------------- /src/Nominatim.php: -------------------------------------------------------------------------------- 1 | 8 | * This source file is subject to the MIT license that is bundled 9 | * with this source code in the file LICENSE. 10 | */ 11 | 12 | namespace maxh\Nominatim; 13 | 14 | use GuzzleHttp\Client; 15 | use GuzzleHttp\Psr7\Request; 16 | use maxh\Nominatim\Exceptions\NominatimException; 17 | use Psr\Http\Message\RequestInterface; 18 | use Psr\Http\Message\ResponseInterface; 19 | use RuntimeException; 20 | use SimpleXMLElement; 21 | 22 | /** 23 | * Wrapper to manage exchanges with OSM Nominatim API. 24 | * 25 | * @see http://wiki.openstreetmap.org/wiki/Nominatim 26 | */ 27 | class Nominatim 28 | { 29 | /** 30 | * Contain url of the current application. 31 | * 32 | * @var string 33 | */ 34 | private $application_url; 35 | 36 | /** 37 | * Contain default request headers. 38 | * 39 | * @var array 40 | */ 41 | private $defaultHeaders; 42 | 43 | /** 44 | * Contain http client connection. 45 | * 46 | * @var \GuzzleHttp\Client 47 | */ 48 | private $http_client; 49 | 50 | /** 51 | * The search object which serves as a template for new ones created 52 | * by 'newSearch()' method. 53 | * 54 | * @var \maxh\Nominatim\Search 55 | */ 56 | private $baseSearch; 57 | 58 | /** 59 | * Template for new ones created by 'newReverser()' method. 60 | * 61 | * @var \maxh\Nominatim\Reverse 62 | */ 63 | private $baseReverse; 64 | 65 | /** 66 | * Template for new ones created by 'newLookup()' method. 67 | * 68 | * @var \maxh\Nominatim\Lookup 69 | */ 70 | private $baseLookup; 71 | 72 | /** 73 | * Template for new ones created by 'newDetails()' method. 74 | * 75 | * @var \maxh\Nominatim\Lookup 76 | */ 77 | private $baseDetails; 78 | 79 | /** 80 | * Constructor. 81 | * 82 | * @param string $application_url Contain url of the current application 83 | * @param null|\GuzzleHttp\Client $http_client Client object from Guzzle 84 | * @param array $defaultHeaders Define default header for all request 85 | * 86 | * @throws NominatimException 87 | */ 88 | public function __construct( 89 | string $application_url, 90 | array $defaultHeaders = [], 91 | ?Client $http_client = null 92 | ) { 93 | if (empty($application_url)) { 94 | throw new NominatimException('Application url parameter is empty'); 95 | } 96 | 97 | if (null === $http_client) { 98 | $http_client = new Client([ 99 | 'base_uri' => $application_url, 100 | 'timeout' => 30, 101 | 'connection_timeout' => 5, 102 | ]); 103 | } elseif ($http_client instanceof Client) { 104 | $application_url_client = (string) $http_client->getConfig('base_uri'); 105 | 106 | if (empty($application_url_client)) { 107 | throw new NominatimException('http_client must have a configured base_uri.'); 108 | } 109 | 110 | if ($application_url_client !== $application_url) { 111 | throw new NominatimException('http_client parameter hasn\'t the same url application.'); 112 | } 113 | } else { 114 | throw new NominatimException('http_client parameter must be a \\GuzzleHttp\\Client object or empty'); 115 | } 116 | 117 | $this->application_url = $application_url; 118 | $this->defaultHeaders = $defaultHeaders; 119 | $this->http_client = $http_client; 120 | 121 | //Create base 122 | $this->baseSearch = new Search(); 123 | $this->baseReverse = new Reverse(); 124 | $this->baseLookup = new Lookup(); 125 | $this->baseDetails = new Details(); 126 | } 127 | 128 | /** 129 | * Returns a new search object based on the base search. 130 | * 131 | * @return \maxh\Nominatim\Search 132 | */ 133 | public function newSearch(): Search 134 | { 135 | return clone $this->baseSearch; 136 | } 137 | 138 | /** 139 | * Returns a new reverse object based on the base reverse. 140 | * 141 | * @return \maxh\Nominatim\Reverse 142 | */ 143 | public function newReverse(): Reverse 144 | { 145 | return clone $this->baseReverse; 146 | } 147 | 148 | /** 149 | * Returns a new lookup object based on the base lookup. 150 | * 151 | * @return \maxh\Nominatim\Lookup 152 | */ 153 | public function newLookup(): Lookup 154 | { 155 | return clone $this->baseLookup; 156 | } 157 | 158 | /** 159 | * Returns a new datails object based on the base details. 160 | * 161 | * @return \maxh\Nominatim\Details 162 | */ 163 | public function newDetails(): Details 164 | { 165 | return clone $this->baseDetails; 166 | } 167 | 168 | /** 169 | * Runs the query and returns the result set from Nominatim. 170 | * 171 | * @param QueryInterface $nRequest The object request to send 172 | * @param array $headers Override the request header 173 | * 174 | * @throws NominatimException if no format for decode 175 | * @throws \GuzzleHttp\Exception\GuzzleException 176 | * 177 | * @return array|SimpleXMLElement The decoded data returned from Nominatim 178 | */ 179 | public function find(QueryInterface $nRequest, array $headers = []) 180 | { 181 | $url = $this->application_url.'/'.$nRequest->getPath().'?'; 182 | $request = new Request('GET', $url, array_merge($this->defaultHeaders, $headers)); 183 | 184 | //Convert the query array to string with space replace to + 185 | if (method_exists(\GuzzleHttp\Psr7\Query::class, 'build')) { 186 | $query = \GuzzleHttp\Psr7\Query::build($nRequest->getQuery(), PHP_QUERY_RFC1738); 187 | } else { 188 | $query = \GuzzleHttp\Psr7\build_query($nRequest->getQuery(), PHP_QUERY_RFC1738); 189 | } 190 | 191 | $url = $request->getUri()->withQuery($query); 192 | $request = $request->withUri($url); 193 | 194 | return $this->decodeResponse( 195 | $nRequest->getFormat(), 196 | $request, 197 | $this->http_client->send($request) 198 | ); 199 | } 200 | 201 | /** 202 | * Return the client using by instance. 203 | */ 204 | public function getClient(): Client 205 | { 206 | return $this->http_client; 207 | } 208 | 209 | /** 210 | * Decode the data returned from the request. 211 | * 212 | * @param string $format json or xml 213 | * @param RequestInterface $request Request object from Guzzle 214 | * @param ResponseInterface $response Interface response object from Guzzle 215 | * 216 | * @throws RuntimeException 217 | * @throws \maxh\Nominatim\Exceptions\NominatimException if no format for decode 218 | * 219 | * @return array|SimpleXMLElement 220 | */ 221 | private function decodeResponse(string $format, RequestInterface $request, ResponseInterface $response) 222 | { 223 | if ('json' === $format || 'jsonv2' === $format || 'geojson' === $format || 'geocodejson' === $format) { 224 | return json_decode($response->getBody()->getContents(), true); 225 | } 226 | 227 | if ('xml' === $format) { 228 | return new SimpleXMLElement($response->getBody()->getContents()); 229 | } 230 | 231 | throw new NominatimException('Format is undefined or not supported for decode response', $request, $response); 232 | } 233 | } 234 | -------------------------------------------------------------------------------- /src/Query.php: -------------------------------------------------------------------------------- 1 | 8 | * This source file is subject to the MIT license that is bundled 9 | * with this source code in the file LICENSE. 10 | */ 11 | 12 | namespace maxh\Nominatim; 13 | 14 | use maxh\Nominatim\Exceptions\InvalidParameterException; 15 | 16 | /** 17 | * Class implementing functionality common to requests nominatim. 18 | */ 19 | abstract class Query implements QueryInterface 20 | { 21 | /** 22 | * Contain the path of the request. 23 | * 24 | * @var string 25 | */ 26 | protected $path; 27 | 28 | /** 29 | * Contain the query for request. 30 | * 31 | * @var array 32 | */ 33 | protected $query = []; 34 | 35 | /** 36 | * Contain the format for decode data returning by the request. 37 | * 38 | * @var string 39 | */ 40 | protected $format; 41 | 42 | /** 43 | * Output format accepted. 44 | * 45 | * @var array 46 | */ 47 | protected $acceptedFormat = ['xml', 'json', 'jsonv2', 'geojson', 'geocodejson']; 48 | 49 | /** 50 | * Output polygon format accepted. 51 | * 52 | * @var array 53 | */ 54 | protected $polygon = ['geojson', 'kml', 'svg', 'text']; 55 | 56 | /** 57 | * Constuctor. 58 | * 59 | * @param array $query Default value for this query 60 | */ 61 | public function __construct(array &$query = []) 62 | { 63 | if (empty($query['format'])) { 64 | //Default format 65 | $query['format'] = 'json'; 66 | } 67 | 68 | $this->setQuery($query); 69 | $this->setFormat($query['format']); 70 | } 71 | 72 | // -- Builder methods ------------------------------------------------------ 73 | 74 | /** 75 | * Format returning by the request. 76 | * 77 | * @param string $format The output format for the request 78 | * 79 | * @throws \maxh\Nominatim\Exceptions\InvalidParameterException if format is not supported 80 | * 81 | * @return \maxh\Nominatim\Details|\maxh\Nominatim\Lookup|\maxh\Nominatim\Reverse|\maxh\Nominatim\Search 82 | */ 83 | final public function format(string $format): self 84 | { 85 | $format = mb_strtolower($format); 86 | 87 | if (\in_array($format, $this->acceptedFormat, true)) { 88 | $this->setFormat($format); 89 | 90 | return $this; 91 | } 92 | 93 | throw new InvalidParameterException('Format is not supported'); 94 | } 95 | 96 | /** 97 | * Preferred language order for showing search results, overrides the value 98 | * specified in the "Accept-Language" HTTP header. Either uses standard 99 | * rfc2616 accept-language string or a simple comma separated list of 100 | * language codes. 101 | * 102 | * @param string $language Preferred language order for showing search results, overrides the value 103 | * specified in the "Accept-Language" HTTP header. Either uses standard rfc2616 104 | * accept-language string or a simple comma separated list of language codes. 105 | * 106 | * @return \maxh\Nominatim\Details|\maxh\Nominatim\Lookup|\maxh\Nominatim\Reverse|\maxh\Nominatim\Search 107 | */ 108 | final public function language(string $language): self 109 | { 110 | $this->query['accept-language'] = $language; 111 | 112 | return $this; 113 | } 114 | 115 | /** 116 | * Include a breakdown of the address into elements. 117 | * 118 | * @return \maxh\Nominatim\Details|\maxh\Nominatim\Lookup|\maxh\Nominatim\Reverse|\maxh\Nominatim\Search 119 | */ 120 | public function addressDetails(bool $details = true): self 121 | { 122 | $this->query['addressdetails'] = $details ? '1' : '0'; 123 | 124 | return $this; 125 | } 126 | 127 | /** 128 | * If you are making large numbers of request please include a valid email address or alternatively include your 129 | * email address as part of the User-Agent string. This information will be kept confidential and only used to 130 | * contact you in the event of a problem, see Usage Policy for more details. 131 | * 132 | * @param string $email Address mail 133 | * 134 | * @return \maxh\Nominatim\Details|\maxh\Nominatim\Lookup|\maxh\Nominatim\Reverse|\maxh\Nominatim\Search 135 | */ 136 | public function email(string $email): self 137 | { 138 | $this->query['email'] = $email; 139 | 140 | return $this; 141 | } 142 | 143 | /** 144 | * Output format for the geometry of results. 145 | * 146 | * @throws \maxh\Nominatim\Exceptions\InvalidParameterException if polygon format is not supported 147 | * 148 | * @return \maxh\Nominatim\Details|\maxh\Nominatim\Query|\maxh\Nominatim\Reverse|\maxh\Nominatim\Search 149 | */ 150 | public function polygon(string $polygon) 151 | { 152 | if (\in_array($polygon, $this->polygon, true)) { 153 | $this->query['polygon_'.$polygon] = '1'; 154 | 155 | return $this; 156 | } 157 | 158 | throw new InvalidParameterException('This polygon format is not supported'); 159 | } 160 | 161 | /** 162 | * Include additional information in the result if available. 163 | * 164 | * @return \maxh\Nominatim\Details|\maxh\Nominatim\Lookup|\maxh\Nominatim\Reverse|\maxh\Nominatim\Search 165 | */ 166 | public function extraTags(bool $tags = true): self 167 | { 168 | $this->query['extratags'] = $tags ? '1' : '0'; 169 | 170 | return $this; 171 | } 172 | 173 | /** 174 | * Include a list of alternative names in the results. 175 | * These may include language variants, references, operator and brand. 176 | * 177 | * @return \maxh\Nominatim\Details|\maxh\Nominatim\Lookup|\maxh\Nominatim\Reverse|\maxh\Nominatim\Search 178 | */ 179 | public function nameDetails(bool $details = true): self 180 | { 181 | $this->query['namedetails'] = $details ? '1' : '0'; 182 | 183 | return $this; 184 | } 185 | 186 | /** 187 | * Returns the URL-encoded query. 188 | */ 189 | public function getQueryString(): string 190 | { 191 | return http_build_query($this->query); 192 | } 193 | 194 | // -- Getters & Setters ---------------------------------------------------- 195 | 196 | /** 197 | * Get path. 198 | */ 199 | final public function getPath(): string 200 | { 201 | return $this->path; 202 | } 203 | 204 | /** 205 | * Get query. 206 | */ 207 | final public function getQuery(): array 208 | { 209 | return $this->query; 210 | } 211 | 212 | /** 213 | * Get format. 214 | */ 215 | final public function getFormat(): string 216 | { 217 | return $this->format; 218 | } 219 | 220 | /** 221 | * Set path. 222 | * 223 | * @param string $path Name's path of the service 224 | */ 225 | protected function setPath(string $path): void 226 | { 227 | $this->path = $path; 228 | } 229 | 230 | /** 231 | * Set query. 232 | * 233 | * @param array $query Parameter of the query 234 | */ 235 | protected function setQuery(array &$query = []): void 236 | { 237 | $this->query = $query; 238 | } 239 | 240 | /** 241 | * Set format. 242 | * 243 | * @param string $format Format returning by the response 244 | */ 245 | protected function setFormat(string $format): void 246 | { 247 | $this->format = $this->query['format'] = $format; 248 | } 249 | } 250 | -------------------------------------------------------------------------------- /src/QueryInterface.php: -------------------------------------------------------------------------------- 1 | 8 | * This source file is subject to the MIT license that is bundled 9 | * with this source code in the file LICENSE. 10 | */ 11 | 12 | namespace maxh\Nominatim; 13 | 14 | /** 15 | * QueryInterface for building request to Nominatim. 16 | */ 17 | interface QueryInterface 18 | { 19 | /** 20 | * Get path of the request. 21 | * 22 | * Example request : 23 | * - Search = search 24 | * - Reverse Geocoding = reverse 25 | */ 26 | public function getPath(): string; 27 | 28 | /** 29 | * Get the query to send. 30 | */ 31 | public function getQuery(): array; 32 | 33 | /** 34 | * Get the format of the request. 35 | * 36 | * Example : json or xml 37 | */ 38 | public function getFormat(): string; 39 | } 40 | -------------------------------------------------------------------------------- /src/Reverse.php: -------------------------------------------------------------------------------- 1 | 8 | * This source file is subject to the MIT license that is bundled 9 | * with this source code in the file LICENSE. 10 | */ 11 | 12 | namespace maxh\Nominatim; 13 | 14 | use maxh\Nominatim\Exceptions\InvalidParameterException; 15 | 16 | /** 17 | * Reverse Geocoding a OSM nominatim service for places. 18 | * 19 | * @see http://wiki.openstreetmap.org/wiki/Nominatim 20 | */ 21 | class Reverse extends Query 22 | { 23 | /** 24 | * OSM Type accepted (Node/Way/Relation). 25 | * 26 | * @var array 27 | */ 28 | public $osmType = ['N', 'W', 'R']; 29 | 30 | /** 31 | * Constructor. 32 | * 33 | * @param array $query Default value for this query 34 | */ 35 | public function __construct(array &$query = []) 36 | { 37 | parent::__construct($query); 38 | 39 | $this->setPath('reverse'); 40 | } 41 | 42 | // -- Builder methods ------------------------------------------------------ 43 | 44 | /** 45 | * [osmType description]. 46 | * 47 | * @throws \maxh\Nominatim\Exceptions\InvalidParameterException if osm type is not supported 48 | * 49 | * @return \maxh\Nominatim\Reverse 50 | */ 51 | public function osmType(string $type): self 52 | { 53 | if (\in_array($type, $this->osmType, true)) { 54 | $this->query['osm_type'] = $type; 55 | 56 | return $this; 57 | } 58 | 59 | throw new InvalidParameterException('OSM Type is not supported'); 60 | } 61 | 62 | /** 63 | * A specific osm node / way / relation to return an address for. 64 | * 65 | * @return \maxh\Nominatim\Reverse 66 | */ 67 | public function osmId(int $id): self 68 | { 69 | $this->query['osm_id'] = $id; 70 | 71 | return $this; 72 | } 73 | 74 | /** 75 | * The location to generate an address for. 76 | * 77 | * @param float $lat The latitude 78 | * @param float $lon The longitude 79 | * 80 | * @return \maxh\Nominatim\Reverse 81 | */ 82 | public function latlon(float $lat, float $lon): self 83 | { 84 | $this->query['lat'] = $lat; 85 | 86 | $this->query['lon'] = $lon; 87 | 88 | return $this; 89 | } 90 | 91 | /** 92 | * Level of detail required where 0 is country and 18 is house/building. 93 | * 94 | * @return \maxh\Nominatim\Reverse 95 | */ 96 | public function zoom(int $zoom): self 97 | { 98 | $this->query['zoom'] = (string) $zoom; 99 | 100 | return $this; 101 | } 102 | } 103 | -------------------------------------------------------------------------------- /src/Search.php: -------------------------------------------------------------------------------- 1 | 8 | * This source file is subject to the MIT license that is bundled 9 | * with this source code in the file LICENSE. 10 | */ 11 | 12 | namespace maxh\Nominatim; 13 | 14 | use maxh\Nominatim\Exceptions\InvalidParameterException; 15 | 16 | /** 17 | * Searches a OSM nominatim service for places. 18 | * 19 | * @see http://wiki.openstreetmap.org/wiki/Nominatim 20 | */ 21 | class Search extends Query 22 | { 23 | /** 24 | * Constuctor. 25 | * 26 | * @param array $query Default value for this query 27 | */ 28 | public function __construct(array &$query = []) 29 | { 30 | parent::__construct($query); 31 | 32 | $this->setPath('search'); 33 | 34 | $this->acceptedFormat[] = 'html'; 35 | $this->acceptedFormat[] = 'jsonv2'; 36 | } 37 | 38 | // -- Builder methods ------------------------------------------------------ 39 | 40 | /** 41 | * Query string to search for. 42 | * 43 | * @param string $query The query 44 | * 45 | * @return \maxh\Nominatim\Search 46 | */ 47 | public function query(string $query): self 48 | { 49 | $this->query['q'] = $query; 50 | 51 | return $this; 52 | } 53 | 54 | /** 55 | * Street to search for. 56 | * 57 | * Do not combine with query(). 58 | * 59 | * @param string $street The street 60 | * 61 | * @return \maxh\Nominatim\Search 62 | */ 63 | public function street(string $street): self 64 | { 65 | $this->query['street'] = $street; 66 | 67 | return $this; 68 | } 69 | 70 | /** 71 | * City to search for (experimental). 72 | * 73 | * Do not combine with query(). 74 | * 75 | * @param string $city The city 76 | * 77 | * @return \maxh\Nominatim\Search 78 | */ 79 | public function city(string $city): self 80 | { 81 | $this->query['city'] = $city; 82 | 83 | return $this; 84 | } 85 | 86 | /** 87 | * County to search for. 88 | * 89 | * Do not combine with query(). 90 | * 91 | * @param string $county The county 92 | * 93 | * @return \maxh\Nominatim\Search 94 | */ 95 | public function county(string $county): self 96 | { 97 | $this->query['county'] = $county; 98 | 99 | return $this; 100 | } 101 | 102 | /** 103 | * State to search for. 104 | * 105 | * Do not combine with query(). 106 | * 107 | * @param string $state The state 108 | * 109 | * @return \maxh\Nominatim\Search 110 | */ 111 | public function state(string $state): self 112 | { 113 | $this->query['state'] = $state; 114 | 115 | return $this; 116 | } 117 | 118 | /** 119 | * Country to search for. 120 | * 121 | * Do not combine with query(). 122 | * 123 | * @param string $country The country 124 | * 125 | * @return \maxh\Nominatim\Search 126 | */ 127 | public function country(string $country): self 128 | { 129 | $this->query['country'] = $country; 130 | 131 | return $this; 132 | } 133 | 134 | /** 135 | * Postal code to search for (experimental). 136 | * 137 | * Do not combine with query(). 138 | * 139 | * @param string $postalCode The postal code 140 | * 141 | * @return \maxh\Nominatim\Search 142 | */ 143 | public function postalCode(string $postalCode): self 144 | { 145 | $this->query['postalcode'] = $postalCode; 146 | 147 | return $this; 148 | } 149 | 150 | /** 151 | * Limit search results to a specific country (or a list of countries). 152 | * 153 | * should be the ISO 3166-1alpha2 code, e.g. gb for the United 154 | * Kingdom, de for Germany, etc. 155 | * 156 | * @param string $countrycode The country code 157 | * 158 | * @throws \maxh\Nominatim\Exceptions\InvalidParameterException if country code is invalid 159 | * 160 | * @return \maxh\Nominatim\Search 161 | */ 162 | public function countryCode(string $countrycode): self 163 | { 164 | if (!preg_match('/^[a-z]{2}$/i', $countrycode)) { 165 | throw new InvalidParameterException("Invalid country code: \"{$countrycode}\""); 166 | } 167 | 168 | if (empty($this->query['countrycodes'])) { 169 | $this->query['countrycodes'] = $countrycode; 170 | } else { 171 | $this->query['countrycodes'] .= ','.$countrycode; 172 | } 173 | 174 | return $this; 175 | } 176 | 177 | /** 178 | * The preferred area to find search results. 179 | * 180 | * @param string $left Left of the area 181 | * @param string $top Top of the area 182 | * @param string $right Right of the area 183 | * @param string $bottom Bottom of the area 184 | * 185 | * @return \maxh\Nominatim\Search 186 | */ 187 | public function viewBox(string $left, string $top, string $right, string $bottom): self 188 | { 189 | $this->query['viewbox'] = $left.','.$top.','.$right.','.$bottom; 190 | 191 | return $this; 192 | } 193 | 194 | /** 195 | * If you do not want certain OpenStreetMap objects to appear in the search results. 196 | * 197 | * @throws \maxh\Nominatim\Exceptions\InvalidParameterException if no place id 198 | * 199 | * @return \maxh\Nominatim\Search 200 | */ 201 | public function exludePlaceIds(): self 202 | { 203 | $args = \func_get_args(); 204 | 205 | if (\count($args) > 0) { 206 | $this->query['exclude_place_ids'] = implode(', ', $args); 207 | 208 | return $this; 209 | } 210 | 211 | throw new InvalidParameterException('No place id in parameter'); 212 | } 213 | 214 | /** 215 | * Limit the number of returned results. 216 | * 217 | * @return \maxh\Nominatim\Search 218 | */ 219 | public function limit(int $limit): self 220 | { 221 | $this->query['limit'] = (string) $limit; 222 | 223 | return $this; 224 | } 225 | } 226 | --------------------------------------------------------------------------------