ExNominatim released: the most full-featured Elixir client for the Nominatim API of OpenStreetMap

Three of the Elixir applications that I have been developing require geolocation and reverse geolocation functionality within Greece. With the goal of not relying on the Google Maps API, I looked into using the OpenStreetMap Nominatim API. The public API is free to use, but comes with its own Terms of Use preventing more than one request per second. This led me to self-host Nominatim.

To utilize the self-hosted API through my Elixir application, I found out that there is already a package called ExOpenStreetMap that was released in 2023 and has seen around 70k downloads since then.

Looking into the code left a lot to be desired. ExOpenStreetMap only implements the /search endpoint, doesn’t perform any validation of the request parameters, doesn’t permit configurability of the target Nominatim server URL and is, in general, as bare-bones as an API wrapper can get.

So here’s an alternative: ExNominatim aims to be the most full-featured client for the OpenStreetMap Nominatim API V1 (public and self-hosted), with extensive request validation, robust error-handling and reporting, and user guidance with helpful messages.

ExNominatim:

• 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 .