Idunn
- Idunn is an API to get points-of-interest information for QwantMaps.
- The POIs are taken from the mimir ElasticSearch database.
- It also fetches POI data from Wikipedia API and a custom Wikidata Elasticsearch source.
- Why Idunn ? Because she is the wife of Bragi that is also the main mimir API.
- A simple workflow schema of Idunn is presented below.
API
- The API provides its OpenAPI schema with:
GET /schema
The main endpoints are:
/v1/places/{place_id}?lang={lang}&type={type}&verbosity={verbosity}
to get the details of a place (admin, street, address or POI). Thetype
parameter belongs to the set{'admin', 'street', 'address', 'poi'}
. Theverbosity
parameter belongs to the set{'long', 'short'}
. The default verbosity islong
./v1/places?bbox={bbox}&raw_filter=class,subclass&size={size}
to get a list of all points of interest matching the given bbox (=left,bot,right,top e.g.bbox=2,48,3,49
) and the categories (e.g.raw_filter=*,restaurant&raw_filter=shop,*&raw_filter=bakery,bakery
)/v1/pois/{poi_id}?lang={lang}
is the deprecated route to get the details of a POI./v1/status
to get the status of the API and associated ES cluster./v1/metrics
to get some metrics on the API that give statistics on the number of requests received, the duration of requests... This endpoint can be scraped by Prometheus.
Running
- The dependencies are managed with Pipenv.
- To run the api you need to do:
pipenv install
- and then:
IDUNN_MIMIR_ES=<url_to_MIMIR_ES> IDUNN_WIKI_ES=<url_to_WIKI_ES> pipenv run python app.py
- you can query the API on port 5000:
curl localhost:5000/v1/places/toto?lang=fr&type=poi
Configuration
The configuration can be given from different ways:
- a default settings is available in utils/default_settings.yaml
- a yaml settings file can be given with an env var IDUNN_CONFIG_FILE (the default settings is still loaded and overriden)
- specific variable can be overriden with env var. They need to be given like "IDUNN_{var_name}={value}" eg IDUNN_MIMIR_ES=...
How to contribute ?
-
Idunn comes along with all necessary components to contribute as easily as possible: specifically you don't need to have any Elasticsearch instance running. Idunn uses docker images to simulate the Elasticsearch sources and the Redis. This means that you will need a local docker install to be able to spawn an ES cluster.
-
To contribute the common workflow is:
- install the dev dependencies:
pipenv install --dev
- add a test in
./tests
for the new feature you propose - implement your feature
- run pytest:
pipenv run pytest -vv -x
- install the dev dependencies: