Update docs

Signed-off-by: Thomas Citharel <tcit@tcit.fr>
This commit is contained in:
Thomas Citharel 2019-11-19 20:01:31 +01:00
parent c7b25474d3
commit ea00cf45dc
No known key found for this signature in database
GPG Key ID: A061B9DDE0CA0773
4 changed files with 87 additions and 14 deletions

View File

@ -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!

View File

@ -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

View File

@ -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

View File

@ -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: