ExNominatim

ExNominatim is 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, "~> 1.0.0"}
  ]
end

Documentation has been published on HexDocs .

A discussion thread will become available on Elixir Forum .

blog-post
ExNominatim 2024
/images/software/stack/Elixir.png Elixir