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

Your Libraries & OS Mentoring Libraries
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!

4 Likes