Mimirsbrunn (also called Mimir) is an independent geocoding and reverse-geocoding system written in Rust, and built upon Elasticsearch. It can handle addresses, streets, points-of-interest (POI), administrative regions or public transport stops.
Usually geocoding refers to "the process of transforming a physical address description to a location on the Earth's surface". However Mimir is more a geoparser than a geocoder since it can resolve any ambiguous toponym to its correct location.
In other words, a geocoder reads a description (possibly incomplete) of a location, and returns a list of candidate locations (latitude / longitude) matching the input.
Geocoding is traditionally used for autocompleting search fields used in geographic applications. For example, here is a screenshot of Qwant Maps, where the user enters a search string 20 rue hec mal, and mimir returns possible candidates in a dropdown box.
If you use it too, feel free to open a pull request, we'll be happy to add your project here!
Mimirsbrunn exposes a REST Json api (with bragi).
This API provices several services:
| feature | route | Parameters | response |
|---|---|---|---|
| geocoding | /autocomplete |
TODO (in the meantime, can be seen here) | The response is formated using geocodejson, the same format as pelias, photon and addok. TODO: give more details and some examples |
| reverse geocoding | /reverse |
TODO (in the meantime, can be seen here) | TODO: give more details and some examples |
| Detail on one object | /features/{id} |
TODO (in the meantime, can be seen here) | TODO: give more details and some examples |
| feature | route | Parameters |
|---|---|---|
| staus | /status |
None |
| Prometheus metrics | /metrics |
None |
Mimirsbrunn relies on geographical datasets to find what users are looking for. These locations belong to different data types and come from various sources. To import these locations Mimirsbrunn comes along with the following specific tools:
| Data Types | Data Sources | Import Tools |
|---|---|---|
| Addresses | OpenAddresses or BANO (the french opendata dataset) | openaddresses2mimir or bano2mimir |
| Streets | OpenStreetMap | osm2mimir |
| POI | OpenStreetMap | osm2mimir |
| Public Transport Stops | Navitia.io data platform or any GTFS data repository | ntfs2mimir or stops2mimir |
| Administrative Regions | OpenStreetMap or Cosmogony | osm2mimir or cosmogony2mimir |
To use another datasource you have to write your own data importer. See for instance Fafnir, an external component to import POIs from another database.
For more detail about the different ways to import those data sources, check the components documentation.
docker_mimir is a repository with some python script to easily import some data in mimir.
Kisio Digital, the company behind navitia has some available debian 8 packages.
If you need some packages for a different target, you can use CanalTP's script or cargo-deb
- install rust
- install ES: the supported ES version is 2.x (yes it's old...). You can install it either directly on you system, or use docker. For a disposable ES, you can run:
docker run --name es2 -d -p '9200:9200' elasticsearch:2
If you want to build local binaries, use cargo build --release. You may need to adjust the
version of the rust compiler prior to executing this command (eg rustup update).
If you want to build a docker image, you can use the docker command, with the following caveat:
You need to specify the version of debian it will be based on, as well as the version of rust.
You also want to verify that the version of Debian you specify is supported! Check the content of
docker/Dockerfile_bragi for that. Your docker command will look like:
docker build --build-arg DEBIAN_VERSION=buster --build-arg RUST_VERSION=1.47 ...
Alternatively, there is a Makefile that can assist you with several tasks. See make help for
details. For example make snapshot will build an image and push it to a repository. The
repository, as well as the build environments are specified in deploy.env.
cargo test
Integration tests are spawning one ElasticSearch docker, so you'll need a recent docker version. Only one docker is spawn, so the ES db is cleaned before each test.
For more precise documentation on use, troubleshooting, development please check the documentation directory.
The project is Licensed as AGPL 3.
We'll be happy to review all you pull requests.
You can also open some issues if you find some bugs, or if you find the geocoder results not to your liking.
Another way to contribute to this project (and to lots of others geocoders) is to add some geocoder test on geocoder-tester, a great non regression tool used by many geocoder. It's quite easy, you just add some new test cases with some searches and the results that you expect.
TODO: add a bit more detail on all the projects
All those projects use quite the same APIs, and you can compare their results using geocoder-tester.
For a more visual comparison, you can also use a comparator.