mirror of
https://framagit.org/framasoft/mobilizon.git
synced 2024-12-21 23:44:30 +00:00
Update docs
Signed-off-by: Thomas Citharel <tcit@tcit.fr>
This commit is contained in:
parent
c7b25474d3
commit
ea00cf45dc
4 changed files with 87 additions and 14 deletions
78
docs/administration/configure/geocoders.md
Normal file
78
docs/administration/configure/geocoders.md
Normal 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!
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
||||
|
|
12
mkdocs.yml
12
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:
|
||||
|
|
Loading…
Reference in a new issue