Skip to content
master
Go to file
Code

README.md

travis GitHub license GitHub tag

Mimirsbrunn

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.

what's a geocoder ?

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.

qwant maps

who uses it ?

If you use it too, feel free to open a pull request, we'll be happy to add your project here!

ressources

How to use

API

Mimirsbrunn exposes a REST Json api (with bragi).

This API provices several services:

Autocomplete

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

Monitoring API

feature route Parameters
staus /status None
Prometheus metrics /metrics None

handled datasets

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.

Install

with docker

docker_mimir is a repository with some python script to easily import some data in mimir.

debian packages

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

manually

prerequiste

  • 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

build

cargo build --release

test

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.

More documentation

For more precise documentation on use, troubleshooting, development please check the documentation directory.

Contributing

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.

presentation of the other alternatives

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.

You can’t perform that action at this time.