From ea00cf45dcdd98f5c5343e27c6f0c6fe5bbc96d0 Mon Sep 17 00:00:00 2001 From: Thomas Citharel Date: Tue, 19 Nov 2019 20:01:31 +0100 Subject: [PATCH] Update docs Signed-off-by: Thomas Citharel --- docs/administration/configure/geocoders.md | 78 ++++++++++++++++++++++ lib/service/geospatial/pelias.ex | 2 + lib/service/geospatial/provider.ex | 9 ++- mkdocs.yml | 12 ---- 4 files changed, 87 insertions(+), 14 deletions(-) create mode 100644 docs/administration/configure/geocoders.md diff --git a/docs/administration/configure/geocoders.md b/docs/administration/configure/geocoders.md new file mode 100644 index 000000000..ee9349eaf --- /dev/null +++ b/docs/administration/configure/geocoders.md @@ -0,0 +1,78 @@ +# Geocoders + +Geocoding is the ability to match an input **string representing a location - such as an address - to geographical coordinates**. +Reverse geocoding is logically the opposite, matching **geographical coordinates to names of places**. + +This is needed to set correct address for events, and more easily find events with geographical data, for instance if you want to discover events happening near your current position. + +However, providing a geocoding service is quite expensive, especially if you want to cover the whole Earth. + +!!!note + To give an idea of what hardware is required to self-host a geocoding service, we successfully used Addok, Pelias and Mimirsbrunn on a 8 core/16GB RAM machine without any issues **on French data**. + +## List of supported geocoders + +This is the list of all geocoders supported by Mobilizon. The current default one is [Nominatim](#nominatim) and uses the official OpenStreetMap instance. + +!!! bug + Changing geocoder through `.env` configuration isn't currently supported by Mobilizon. + Instead you need to edit the following line in `config.prod.exs`: + ```elixir + config :mobilizon, Mobilizon.Service.Geospatial, service: Mobilizon.Service.Geospatial.Nominatim + ``` + And change `Nominatim` to one of the supported geocoders. This change might be overwritten when updating Mobilizon. + +### Nominatim + +[Nominatim](https://wiki.openstreetmap.org/wiki/Nominatim) is a GPL-2.0 licenced tool to search data by name and address. It's written in C and PHP and uses PostgreSQL. +It's the current default search tool on the [OpenStreetMap homepage](https://www.openstreetmap.org). + +!!! warning + When using the official Nominatim OpenStreetMap instance (default endpoint for this geocoder if not configured otherwise), you need to read and accept the [Usage Policy](https://operations.osmfoundation.org/policies/nominatim). + +Several companies provide hosted instances of Nominatim that you can query via an API, for example see [MapQuest Open Initiative](https://developer.mapquest.com/documentation/open/nominatim-search). + +### Addok + +[Addok](https://github.com/addok/addok) is a WTFPL licenced search engine for address (and only address). It's written in Python and uses Redis. +It's used by French government for [adresse.data.gouv.fr](https://adresse.data.gouv.fr). + +!!! warning + When using France's Addok instance at `api-adresse.data.gouv.fr` (default endpoint for this geocoder if not configured otherwise), you need to read and accept the [GCU](https://adresse.data.gouv.fr/cgu) (in French). + +### Photon + +[Photon](https://photon.komoot.de/) is an Apache 2.0 licenced search engine written in Java and powered by ElasticSearch. + +!!! warning + The terms of use for the official instance (default endpoint for this geocoder if not configured otherwise) are simply the following: + > You can use the API for your project, but please be fair - extensive usage will be throttled. We do not guarantee for the availability and usage might be subject of change in the future. + +### Pelias + +[Pelias](https://github.com/pelias/pelias) is a MIT licensed geocoder composed of several services written in NodeJS. It's powered by ElasticSearch. + +There's [Geocode Earth](https://geocode.earth/) SAAS that provides a Pelias API. +They offer discounts for Open-Source projects. [See the pricing](https://geocode.earth/). + +### Mimirsbrunn + +[Mimirsbrunn](https://github.com/CanalTP/mimirsbrunn) is an AGPL-3.0 licensed geocoding written in Rust and powered by ElasticSearch. + +Mimirsbrunn is used by [Qwant Maps](https://www.qwant.com/maps) and [Navitia](https://www.navitia.io). + +### Google Maps + +[Google Maps](https://developers.google.com/maps/documentation/geocoding/intro) is a proprietary service that provides APIs for geocoding. + +They don't have a free plan, but offer credit when creating a new account. [See the pricing](https://cloud.google.com/maps-platform/pricing/). + +### MapQuest + +[MapQuest](https://developer.mapquest.com/documentation/open/geocoding-api/) is a proprietary service that provides APIs for geocoding. + +They offer a free plan. [See the pricing](https://developer.mapquest.com/plans). + +### More geocoding services + +Geocoding implementations are simple modules that need to implement the [`Mobilizon.Service.Geospatial.Provider` behaviour](https://framasoft.frama.io/mobilizon/backend/Mobilizon.Service.Geospatial.Provider.html), so feel free to write your own! diff --git a/lib/service/geospatial/pelias.ex b/lib/service/geospatial/pelias.ex index 19d1a53d4..1b173cad1 100644 --- a/lib/service/geospatial/pelias.ex +++ b/lib/service/geospatial/pelias.ex @@ -1,6 +1,8 @@ defmodule Mobilizon.Service.Geospatial.Pelias do @moduledoc """ [Pelias](https://pelias.io) backend. + + Doesn't provide type of POI. """ alias Mobilizon.Addresses.Address diff --git a/lib/service/geospatial/provider.ex b/lib/service/geospatial/provider.ex index 40d8b8278..87dbb3606 100644 --- a/lib/service/geospatial/provider.ex +++ b/lib/service/geospatial/provider.ex @@ -9,11 +9,13 @@ defmodule Mobilizon.Service.Geospatial.Provider do * `Mobilizon.Service.Geospatial.Addok` [🔗](https://github.com/addok/addok) * `Mobilizon.Service.Geospatial.MapQuest` [🔗](https://developer.mapquest.com/documentation/open/) * `Mobilizon.Service.Geospatial.GoogleMaps` [🔗](https://developers.google.com/maps/documentation/geocoding/intro) + * `Mobilizon.Service.Geospatial.Mimirsbrunn` [🔗](https://github.com/CanalTP/mimirsbrunn) + * `Mobilizon.Service.Geospatial.Pelias` [🔗](https://pelias.io) ## Shared options - * `:user_agent` User-Agent string to send to the backend. Defaults to `"Mobilizon"` + * `:user_agent` User-Agent string to send to the backend. Defaults to `"Mobilizon"` or `Mobilizon.Config.instance_user_agent/0` * `:lang` Lang in which to prefer results. Used as a request parameter or through an `Accept-Language` HTTP header. Defaults to `"en"`. * `:country_code` An ISO 3166 country code. String or `nil` @@ -31,7 +33,10 @@ defmodule Mobilizon.Service.Geospatial.Provider do ## Options - Most backends implement all of [the shared options](#module-shared-options). + In addition to [the shared options](#module-shared-options), `c:geocode/3` also + accepts the following options: + + * `zoom` Level of detail required for the address. Default: 15 ## Examples diff --git a/mkdocs.yml b/mkdocs.yml index c3870a524..f72f58f39 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,15 +33,3 @@ theme: icon: 'calendar_today' feature: tabs: true -# -#nav: -# - Home: 'index.md' -# - About: 'about.md' -# - Administration: -# - Install: 'administration/install.md' -# - Dependencies: 'administration/dependencies.md' -# - Docker: 'administration/docker.md' -# - Contribute: -# - Contribute: 'contribute.md' -# - Development: 'contribute/development.md' -# - Styleguide: