A full-featured client for the OpenStreetMap Nominatim API V1 , with extensive request validation, robust error-handling and reporting, and user guidance with helpful validation messages.

Goals

• Prevent unnecessary calls to the Nominatim API server by validating intended requests and preventing them if the request parameters are invalid.
• Solid error-handling for robustness in production.
• Provide helpful validation messages to the user when a request is deemed invalid.

Features

• Covers the /search, /reverse, /lookup, /status and /details endpoints.
• Utilizes request parameter structs with the appropriate fields (except for json_callback) for each endpoint.
• Validates parameter values prior to the request (possible to override this with the force: true option).
• Provides helpful return tuples {:ok, ...}, {:error, reason} and {:error, {specific_error, other_info}} across the board.
• Collects all detected field validation errors in an :errors field, and provides a :valid? field in each request params struct.
• Can be used with self-hosted Nominatim API instances by setting the :base_url option of the enpoint-related functions in the ExNominatim module.
• Automatically sets the User-Agent header to “ExNominatim” (plus the version) to comply with the Nominatim Usage Policy .

Ideas and someday/maybe features

• Add a Processing module to automatically report back results as the content of the %Req.Response{} struct’s :body together with the HTTP status.
• Build Cachex in (see Reactive Warming ) and provide the option to automatically throttle requests to the public API to the “absolute maximum of 1 request per second” as requested by the Nominatim Usage Policy .
• Implement a test suite.

Installation

The package can be installed from Hex by adding ex_nominatim to your list of dependencies in mix.exs:

def deps do
  [
    {:ex_nominatim, "~> 2.0.0"}
  ]
end

Documentation has been published on HexDocs .

A discussion thread will become available on Elixir Forum .