View Source ExNominatim (ExNominatim v1.1.4)
Main user-friendly functions for interacting with the endpoints of a Nominatim API server.
The opts
keyword list of the endpoint request functions can optionally include the following:
:base_url
with a string value setting the base URL of the target Nominatim API server (it defaults to the public server).:force
with a boolean value, wheretrue
means that validation errors will be ignored and the HTTP GET request to the API will run regardless.
Warning
Please respect the Nominatim Usage Policy when using the public server. To prevent useless requests, it is recommended to not disable request validation.
New since v1.1.0: 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 defaultjsonv2
). - Requests to the
/reverse
endpoint will set:namedetails
to 1 (unless otherwise set inopts
). - Requests to the
/status
endpoint will return JSON instead of the default text (HTTP status code 200 and textOK
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 usingExNominatim.Report.atomize/1
.
Here's the preference order:
- The default values for
:base_url
and:force
across all endpoints are the public Nominatim API server's URL andfalse
, 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 following things are set as default in ExNominatim's default settings (unless overriden through your own configuration or explicitly-set request parameter values):
- The
:format
value for the/reverse
endpoint, which is switched to GeocodeJSON, instead of XML (the API endpoint's default). - The
:format
value for the/lookup
endpoint, which is switched to JSONv2, instead of XML (the API endpoint's default). - The
:format
value for the/status
endpoint, which is switch to JSON, instead of text (the API endpoint's default).
Summary
Functions
Show internal details for an OpenStreetMap object (for debugging only) using the /details
API endpoint.
Same as ExNominatim.explain_fields/1
, but show all fields and their explanations.
Given a request params struct (%ReverseParams{}
, %SearchParams{}
, etc.), a keyword list, or a list of atoms corresponding to keys, explain the fields, their default values (if any) and their values' limits (if applicable). It ignores any keyword list keys or atoms in the list that do not correspond to request parameters.
Show the current configuration defaults.
Look up address details for OpenStreetMap objects by their "OSM ID" using the /lookup
API endpoint.
Search OpenStreetMap objects by their location using the /reverse
API endpoint.
Search OpenStreetMap objects by name or type using the /search
API endpoint.
Query the status of the server at base_url
using the /status
API endpoint without any keyword list options provided.
Query the status of the server at base_url
using the /status
API endpoint.
Functions
Show internal details for an OpenStreetMap object (for debugging only) using the /details
API endpoint.
Note: You can set an alternative server as the value of the :base_url
keyword and ignore any validation errors by setting the :force
keyword's value to true
.
Given a keyword list of request parameters as opts
, transform this to a %DetailsParams{}
struct, validate it and its values using the ExNominatim.Validations
module's functions and, if valid (or if opts
contains force: true
to ignore any validation errors), prepare and make an HTTP request to the /details
endpoint.
Same as ExNominatim.explain_fields/1
, but show all fields and their explanations.
Given a request params struct (%ReverseParams{}
, %SearchParams{}
, etc.), a keyword list, or a list of atoms corresponding to keys, explain the fields, their default values (if any) and their values' limits (if applicable). It ignores any keyword list keys or atoms in the list that do not correspond to request parameters.
Alternatively, provide the atom corresponding to an endpoint (e.g., :search
for /search
) to get the explanations of the parameters specific to that endpoint.
The content shown is adapted from the Nominatim API Reference page of the endpoint corresponding to the request params struct.
The result is a map, so that you can reuse the explanations for user guidance and error reporting in your own application.
Show the current configuration defaults.
Look up address details for OpenStreetMap objects by their "OSM ID" using the /lookup
API endpoint.
Note: You can set an alternative server as the value of the :base_url
keyword and ignore any validation errors by setting the :force
keyword's value to true
.
Given a keyword list of request parameters as opts
, transform this to a %LookupParams{}
struct, validate it and its values using the ExNominatim.Validations
module's functions and, if valid (or if opts
contains force: true
to ignore any validation errors), prepare and make an HTTP request to the /lookup
endpoint.
Search OpenStreetMap objects by their location using the /reverse
API endpoint.
Note: You can set an alternative server as the value of the :base_url
keyword and ignore any validation errors by setting the :force
keyword's value to true
.
Given a keyword list of request parameters as opts
, transform this to a %ReverseParams{}
struct, validate it and its values using the ExNominatim.Validations
module's functions and, if valid (or if opts
contains force: true
to ignore any validation errors), prepare and make an HTTP request to the /reverse
endpoint.
Search OpenStreetMap objects by name or type using the /search
API endpoint.
Given a keyword list of request parameters as params
, transform this to a %SearchParams{}
struct, validate it and its values using the ExNominatim.Validations
module's functions and, if valid (or if params
contains force: true
to ignore any validation errors), prepare and make an HTTP request to the /search
endpoint.
Query the status of the server at base_url
using the /status
API endpoint without any keyword list options provided.
Query the status of the server at base_url
using the /status
API endpoint.
Note: You can set an alternative server as the value of the :base_url
keyword and ignore any validation errors by setting the :force
keyword's value to true
.
Given a keyword list of request parameters as opts
, transform this to a %StatusParams{}
struct, validate it and its values using the ExNominatim.Validations
module's functions and, if valid (or if opts
contains force: true
to ignore any validation errors), prepare and make an HTTP request to the /status
endpoint.