ExNominatim - A full-featured client for the OpenStreetMap Nominatim API V1

Your Libraries & OS Mentoring Libraries
1

logo

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.

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.

8 Likes
2

Hi everyone, version 1.1.1 has just been published on Hex: https://hex.pm/packages/ex_nominatim

Here’s the updated documentation: https://hexdocs.pm/ex_nominatim/ExNominatim.html

I have retired the previous versions.

New stuff:

  • New Report module with functions for processing the output of responses into more user-friendly structures and “atomizing” any bitstring keys of maps/structs therein. This is enabled by default and can be switched off independently by setting either or both keywords :process, :atomize to false in the endpoint functions.
  • Implemented validation of a couple remaining fields.
  • Various improvements to the DX here and there, such as being able to properly validate setting the value of 0/1 fields to false/true.

I also implemented configurability, i.e.: ExNominatim now takes into account your overarching Elixir application’s configuration, as defined using the Config module. For example, in the config/config.exs file of a Phoenix app called MyApp, you can define default values like so:

config :my_app, MyApp.ExNominatim,
all: [
  base_url: "http://localhost:8080",
  force: true,
  format: "json",
  process: true,
  atomize: true
],
search: [format: "geocodejson", force: false],
reverse: [namedetails: 1],
lookup: [],
details: [],
status: [format: "json"]

The configuration above has the following effects:

  • Requests to all endpoints will use the self-hosted Nominatim API instance at port 8080 of localhost, accessible over HTTP.
  • Request parameter validation errors (valid?: false in the request parameters struct) will be ignored for requests to all endpoints, except for requests to the /search endpoint.
  • Unless requested otherwise in opts, requests to the /search endpoint will return data in GeocodeJSON format (instead of the default jsonv2).
  • Requests to the /reverse endpoint will set :namedetails to 1 (unless otherwise set in opts).
  • Requests to the /status endpoint will return JSON instead of the default text (HTTP status code 200 and text OK or HTTP status 500 and a detailed error mesage).
  • The responses from all endpoints will be processed automatically using ExNominatim.Report.process/1, and any maps and contents thereof (or map contents of structs’s keys) will be converted from bitstring keys to atom keys using ExNominatim.Report.atomize/1 (this is the default anyway).

Here’s the preference order:

  • The default values for :base_url and :force across all endpoints are the public Nominatim API server’s URL and false, respectively.
  • Any keyword-value pairs set in the :all list override these defaults and are applied automatically in requests to all endpoints.
  • Any keyword-value pairs set in the list of a specific endpoint override any values defined in the :all list and are applied automatically in requests to that endpoint.
  • Anything you set in opts overrides all the above.

At any moment you can use ExNominatim.get_config/0 to see the current configuration.

The code is mirrored to my Github account.

Feedback and recommendations welcome!

3 Likes