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