View Source README

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.

Who made this?

Copyright 2024, Made by Isaak Tsalicoglou, OVERBRING in Athens, Attica, Greece.

Many thanks to all the volunteers and contributors of OpenStreetMap and Nominatim.