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 .
A discussion thread will become available on Elixir Forum .