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_urlwith a string value setting the base URL of the target Nominatim API server (it defaults to the public server).:forcewith a boolean value, wheretruemeans 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?: falsein the request parameters struct) will be ignored for requests to all endpoints, except for requests to the/searchendpoint. - Unless requested otherwise in
opts, requests to the/searchendpoint will return data in GeocodeJSON format (instead of the defaultjsonv2). - Requests to the
/reverseendpoint will set:namedetailsto 1 (unless otherwise set inopts). - Requests to the
/statusendpoint will return JSON instead of the default text (HTTP status code 200 and textOKor 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_urland:forceacross all endpoints are the public Nominatim API server's URL andfalse, respectively. - Any keyword-value pairs set in the
:alllist 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
:alllist and are applied automatically in requests to that endpoint. - Anything you set in
optsoverrides 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
:formatvalue for the/reverseendpoint, which is switched to GeocodeJSON, instead of XML (the API endpoint's default). - The
:formatvalue for the/lookupendpoint, which is switched to JSONv2, instead of XML (the API endpoint's default). - The
:formatvalue for the/statusendpoint, 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.