{"id":13557382,"url":"https://github.com/Qwant/idunn","last_synced_at":"2025-04-03T11:31:54.714Z","repository":{"id":38407197,"uuid":"133823727","full_name":"Qwant/idunn","owner":"Qwant","description":"Qwant Maps internal API for Points of Interest, directions and more.","archived":true,"fork":false,"pushed_at":"2022-12-27T16:57:49.000Z","size":2790,"stargazers_count":37,"open_issues_count":7,"forks_count":10,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-11-04T07:36:02.255Z","etag":null,"topics":["mimir","poi","qwant-maps"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Qwant.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-17T14:16:14.000Z","updated_at":"2024-10-25T21:43:56.000Z","dependencies_parsed_at":"2022-07-14T07:20:34.916Z","dependency_job_id":null,"html_url":"https://github.com/Qwant/idunn","commit_stats":null,"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Qwant%2Fidunn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Qwant%2Fidunn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Qwant%2Fidunn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Qwant%2Fidunn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Qwant","download_url":"https://codeload.github.com/Qwant/idunn/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246993112,"owners_count":20865939,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mimir","poi","qwant-maps"],"created_at":"2024-08-01T12:04:18.940Z","updated_at":"2025-04-03T11:31:49.699Z","avatar_url":"https://github.com/Qwant.png","language":"Python","funding_links":[],"categories":["Python","others"],"sub_categories":[],"readme":"[![GitHub Build](https://github.com/Qwant/idunn/workflows/Idunn%20tests/badge.svg)](https://github.com/Qwant/idunn)\n[![GitHub license](https://img.shields.io/github/license/Qwant/idunn.svg)](./LICENSE)\n[![Docker Pulls](https://img.shields.io/docker/pulls/qwantresearch/idunn.svg)](https://hub.docker.com/r/qwantresearch/idunn/)\n\n# Idunn\n\nIdunn is the main back-end API of Qwant Maps, it acts a the entrypoint in front\nof many other APIs and is in charge of aggregating data for geocoding,\ndirections, POIs details, ...\n\n- historicaly, Idunn was only an API to get [points-of-interest](https://en.wikipedia.org/wiki/Point_of_interest) information for QwantMaps.\n- The POIs are taken from the [mimir](https://github.com/CanalTP/mimirsbrunn) ElasticSearch database.\n- It also fetches POI data from Wikipedia API and a custom Wikidata Elasticsearch source.\n- Why [Idunn](https://fr.wikipedia.org/wiki/Idunn) ? Because she is the wife of [Bragi](https://fr.wikipedia.org/wiki/Bragi) that is also [the main](https://github.com/CanalTP/mimirsbrunn/tree/master/libs/bragi) mimir API.\n- A simple workflow schema of Idunn is presented below.\n\nNote: this diagram may be outdated:\n\n![Idunn workflow](./doc/diagram.png)\n\n## API\n\n- The API provides its OpenAPI schema with:\n`GET /openapi.json`\n\nThe main endpoints are:\n* `/v1/places/{place_id}?lang={lang}\u0026type={type}\u0026verbosity={verbosity}` to get the details of a place\n(admin, street, address or POI).\n    * `type`: (optional) parameter belongs to the set `{'admin', 'street', 'address', 'poi'}`\n    * `verbosity` parameter belongs to the set `{'long', 'short'}`. The default verbosity is `long`.\n* `/v1/places?bbox={bbox}\u0026category=\u003ccategory-name\u003e\u0026size={size}` to get a list of all points of interest matching the given bbox and categories\n    * `bbox`: left,bot,right,top e.g. `bbox=2.0,48.0,3.0,49.0`\n    * `category`: multiple values are accepted (e.g. `category=leisure\u0026category=museum`)\n    * `size`: maximum number of places in the response\n    * `verbosity`: default verbosity is `list` (equivalent to `long`, except \"information\" and \"wiki\" blocks are not returned)\n    * `source`: (optional) to force a data source (instead of automated selection based on coverage). Accepted values: `osm`, `pages_jaunes`\n    * `q`: full-text query (optional, experimental)\n* `/v1/places?bbox={bbox}\u0026raw_filter=class,subclass\u0026size={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 raw filters (e.g. `raw_filter=*,restaurant\u0026raw_filter=shop,*\u0026raw_filter=bakery,bakery`)\n* `/v1/categories` to get the list of all the categories you can filter on.\n* `/v1/directions` See [directions.md](./doc/directions.md) for details\n* `/v1/events?bbox={bbox}\u0026category=\u003ccategory_name\u003e\u0026size={size}` to get a list of all events matching the given bbox and outing_category\n    * `bbox`: left,bot,right,top e.g. `bbox=2.0,48.0,3.0,49.0`\n    * `category`: one value is accepted (e.g. `category=concert | show | exhibition | sport | entertainment`)\n    * `size`: maximum number of events in the response\n---\n* `/v1/status` to get the status of the API and associated ES cluster.\n* `/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.\n\n## Running\n\n### Requirements\n\n   - Python 3.10\n   - [Pipenv](https://github.com/pypa/pipenv), to manage dependencies and virtualenv\n\n### Installation\n\n- Create the virtualenv and install dependencies:\n  ```shell\n  pipenv install\n  ```\n\n- and then:\n  ```shell\n  IDUNN_MIMIR_ES=\u003curl_to_MIMIR_ES\u003e IDUNN_WIKI_ES=\u003curl_to_WIKI_ES\u003e pipenv run python app.py\n  ```\n\n- you can query the API on port 5000:\n  ```shell\n  curl localhost:5000/v1/places/toto?lang=fr\u0026type=poi\n  ```\n\n### Configuration\n\nThe configuration can be given from different ways:\n 1. a default settings is available in `utils/default_settings.yaml`\n 2. a yaml settings file can be given with an env var `IDUNN_CONFIG_FILE`\n    (the default settings is still loaded and overriden)\n 3. specific variable can be overriden with env var. They need to be given like \"IDUNN_{var_name}={value}\"\n    eg IDUNN_MIMIR_ES=...\n    You can create a `.env` file with commonly used env variables, it will be loaded by pipenv by default.\n\nPlease note that you will need an API key from [openweathermap](https://openweathermap.org/) in order to use the `Weather` block. You can then set it into the `IDUNN_WEATHER_API_KEY` environment variable or directly into the `WEATHER_API_KEY` inside the `utils/default_settings.yaml` file.\n\n### Run tests\n\nTo run tests, first make sure you have dev dependencies installed:\n\n```shell\npipenv install --dev\n```\n\nThen, you can run the full testsuite using pytest:\n\n```shell\npipenv run pytest -vv -x\n```\n\nIf you are using a `.env` file, you need to make sure that pipenv won't load it, which can be done by setting the environment variable `PIPENV_DONT_LOAD_ENV=1`.\n\n## How to contribute ?\n\n- 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](tests/docker-compose.yml) 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.\n\n- To contribute the common workflow is:\n\n\t1. install the dev dependencies: `pipenv install --dev`\n\t2. add a test in `./tests` for the new feature you propose\n\t3. implement your feature\n\t4. run pytest: `pipenv run pytest -vv -x`\n\t5. check the linter output: `pipenv run lint`\n\t6. if everything is fixed, then check the format: `pipenv run black --diff --check`\n\n## Run it with Redis and elasticsearch\n\nYou can run it with both **Redis** and **elasticsearch** using **docker**. First, edit the `docker-compose.yml` file to add a link to your **elasticsearch** instance (for example: `https://somewhere.lost/`) in `IDUNN_MIMIR_ES`.\n\nThen you just need to run:\n\n```bash\n$ docker-compose up --build\n```\n\nIf you need to clean the **Redis** cache, run:\n\n```bash\n$ docker-compose kill\n$ docker image prune --filter \"label=idunn_idunn\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FQwant%2Fidunn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FQwant%2Fidunn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FQwant%2Fidunn/lists"}