txt: ## dist_zef-bduggan-WebService-Nominatim.md
  [![Actions Status](https://github.com/bduggan/raku-webservice-nominatim/actions/workflows/linux.yml/badge.svg)](https://github.com/bduggan/raku-webservice-nominatim/actions/workflows/linux.yml)
  [![Actions Status](https://github.com/bduggan/raku-webservice-nominatim/actions/workflows/macos.yml/badge.svg)](https://github.com/bduggan/raku-webservice-nominatim/actions/workflows/macos.yml)
  
  # NAME
  
  WebService::Nominatim - Client for the OpenStreetMap Nominatim Geocoding API
  
  # SYNOPSIS
  
  ```
  use WebService::Nominatim;
  
  my \n = WebService::Nominatim.new;
  
  say n.search('Grand Central Station').first.<name lat lon>;
  # (Grand Central Terminal 40.75269435 -73.97725295036929)
  
  my $geo = n.search: '221B Baker Street, London, UK';
  my $geo = n.search: query => '221B Baker Street, London, UK';
  my $geo = n.search: query => { street => '221B Baker Street', city => 'London', country => 'UK' };
  say $geo.head.<lat lon>;
  # (51.5233879 -0.1582367)
  
  say n.search: 'Grand Place, Brussels', :format<geojson>, :raw;
  {"type":"FeatureCollection", ...
  
  ```
  
  ```
  
  {"type":"FeatureCollection","licence":"Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright","features":[{"type":"Feature","properties":{"place_id":97663568,"osm_type":"way","osm_id":991425177,"place_rank":25,"category":"boundary","type":"protected_area","importance":0.4874302285645721,"addresstype":"protected_area","name":"Grand-Place - Grote Markt","display_name":"Grand-Place - Grote Markt, Quartier du Centre - Centrumwijk, Pentagone - Vijfhoek, Bruxelles - Brussel, Brussel-Hoofdstad - Bruxelles-Capitale, Région de Bruxelles-Capitale - Brussels Hoofdstedelijk Gewest, 1000, België / Belgique / Belgien"},"bbox":[4.3512177,50.8460246,4.3537194,50.8474356],"geometry":{"type": "Point","coordinates": [4.352408060161565, 50.84672905]}}]}
  
  
  ```
  
  # DESCRIPTION
  
  This is an interface to OpenStreetMap's Nominatim Geocoding API, <https://nominatim.org>.
  
  # EXPORTS
  
  ```
  use WebService::Nominatim;
  my \n = WebService::Nominatim.new;
  
  ```
  
  Equivalent to:
  
  ```
  use WebService::Nominatim 'n';
  
  ```
  
  Add debug output:
  
  ```
  use WebService::Nominatim 'n' '-debug';
  
  ```
  
  If an argument is provided, a new instance will be returned. If `-debug` is provided, the instance will send logs to stderr. Note this is different from the `debug` attribute, which gets debug information from the server.
  
  # ATTRIBUTES
  
  ## url
  
  The base URL for the Nominatim API. Defaults to `https://nominatim.openstreetmap.org`.
  
  ## email
  
  The email address to use in the `email` query parameter. Optional, but recommended if you are sending a lot of requests.
  
  ## debug
  
  Optionally send debug => 1 in search requests. Responses will be HTML.
  
  ## dedupe
  
  Optionally send dedupe => 1 to search request.
  
  # EXPORTS
  
  If an argument is given to the module, it is assumed to be a name and the module creates a new `WebService::Nominatim` object. Also "-debug" will send debug output to stderr. These are equivalent:
  
  ```
  use WebService::Nominatim 'nom', '-debug';
  
  ```
  
  and
  
  ```
  use WebService::Nominatim;;
  my \nom = WebService::Nominatim.new;
  nom.logger.send-to: $*ERR;
  
  ```
  
  # METHODS
  
  ## search
  
  Search for a location using either a string search or a structured search. This will always return a list. The items in the list may be strings or hashes, depending on the format (json formats will be parsed into hashes). Use `:raw` to return strings.
  
  ### Usage
  
  ```
  $n.search('Grand Central Station');
  say .<display_name> for $n.search: 'Main St', :limit(5);
  $n.search: '221B Baker Street, London, UK';
  $n.search: query => '221B Baker Street, London, UK';
  $n.search: query => { street => '221B Baker Street', city => 'London', country => 'UK' }, limit => 5;
  
  ```
  
  ### Parameters
  
  See <https://nominatim.org/release-docs/develop/api/Search/> for details about meanings of the parameters.
  
  * `$query`
  
    The search query. This can be a string or a hash of search parameters.
    It can be a named parameter, or the first positional parameter.
  * `:raw`
  
    If set to a true value, the raw response will be returned as a string, without JSON parsing.
  * `:format`
  
    The format of the response. Defaults to jsonv2. Other options are xml, json, geojson, and geocodejson.
  
  Other parameters:
  
  * `:layer`
  * `:featureType`
  * `:addressdetails`
  * `:limit`
  * `:extratags`
  * `:namedetails`
  * `:accept-language`
  * `:countrycodes`
  * `:exclude_place_ids`
  * `:viewbox`
  * `:bounded`
  * `:polygon_geojson`
  * `:polygon_kml`
  * `:polygon_svg`
  * `:polygon_text`
  * `:polygon_threshold`
  
  ## lookup
  
  Look up an object.
  
  ```
  say n.lookup('R1316770', :format<geojson>);
  say n.lookup(relation-id => '1316770', :format<geojson>);
  say n.lookup(relation-ids => [ 1316770, ], :format<geojson>, :polygon_geojson);
  
  ```
  
  ### Parameters
  
  Many of the same parameters as `search` are available.
  
  Additionally, `node-ids`, `way-ids`, and `relation-ids` can be used to look up multiple objects. And `node-id`, `way-id`, and `relation-id` can be used to look up a single object.
  
  See <https://nominatim.org/release-docs/develop/api/Lookup/> for more details.
  
  ## status
  
  Get the status of the Nominatim server.
  
  ```
  say n.status;
  
  ```
  
  # SEE ALSO
  
  <https://nominatim.org/release-docs/develop/api/Search/>
  
  # AUTHOR
  
  Brian Duggan
  