2020-06-24 00:35:19 +02:00
# MapComplete
2020-07-09 15:28:57 +02:00
> Let a thousand flowers bloom
2022-05-07 23:22:52 +02:00
[  ](https://liberapay.com/pietervdvn/)
[](https://matrix.to/#/#MapComplete:matrix.org?via=matrix.org)
2022-05-01 23:17:41 +02:00
2020-07-09 15:28:57 +02:00
2022-10-26 00:10:15 +02:00
**MapComplete is an OpenStreetMap viewer and editor.** The main goal is to make it trivial to see and update information on OpenStreetMap, also for non-technical users.
This is achieved by showing only features related to a _single topic_ on the map. MapComplete contains many thematic maps, each built for a certain community of users, showing data and questions that are highly relevant for this topic.
By showing only objects on a single topic, contributors are not distracted by objects that are not relevant to them.
Furthermore, this allows to show (and ask for) attributes that are highly specialized (e.g. a widget that determines tree species based on pictures) but also by reusing common attributes and elements (such as showing and adding opening hours or pictures).
2020-06-24 00:35:19 +02:00
2021-10-02 21:32:50 +02:00
**The design goals** of MapComplete are to be:
2020-06-24 00:35:19 +02:00
2020-08-17 17:23:15 +02:00
- Easy to use, both on web and on mobile
2020-08-26 23:48:58 +02:00
- Easy to deploy (by not having a backend)
2020-08-22 18:57:27 +02:00
- Easy to set up a custom theme
- Easy to fall down the rabbit hole of OSM
2020-06-24 00:35:19 +02:00
2021-11-07 16:34:51 +01:00
**The basic functionality is** to download some map features from Overpass and then ask certain questions. An answer is
sent back to directly to OpenStreetMap.
2020-08-17 17:23:15 +02:00
2021-09-09 00:05:51 +02:00
Furthermore, it shows images present in the `image` tag or, if a `wikidata` or `wikimedia_commons` -tag is present, it
follows those to get these images too.
2020-06-24 00:35:19 +02:00
2022-01-26 21:40:38 +01:00
**An explicit non-goal** of MapComplete is to modify geometries of ways, especially generic geometry-editing. (Splitting
2022-10-26 00:10:15 +02:00
roads is possible and in some restricted themes is geometry-conflation possible too). If adding geometry would be supported, we'd also have to show all geometries (to avoid accidental intersections).
This would invite to show and map these other geometries as well, resulting in a general-purpose editor. However, we already [have an excellent, web-based general purpose editor ](https://wiki.openstreetmap.org/wiki/ID ).
2020-08-24 22:42:59 +02:00
2021-11-07 16:34:51 +01:00
**More about
MapComplete:** [Watch Pieter's talk on the 2021 State Of The Map Conference ](https://media.ccc.de/v/sotm2021-9448-introduction-and-review-of-mapcomplete ) ([YouTube](https://www.youtube.com/watch?v=zTtMn6fNbYY))
about the history, vision and future of MapComplete.
2021-10-02 21:32:50 +02:00
2022-10-26 00:10:15 +02:00
## What's the difference with StreetComplete?
This is the repository of _Map_ Complete. _Street_ Complete is an Android-only application where the contributor is shown some questions to solve, after which the pin will dissappear from the map.
StreetComplete can thus be seen as a Todo-map for contributors who go on a stroll, whereas MapComplete is a website showing relevant information and which allows to add or update information.
The codebases are separate, even though many ideas and some artwork are copied from the StreetComplete app.
2022-09-19 12:38:31 +02:00
# Documentation
**All documentation can be found in [the documentation directory ](Docs/ )**
## Dev
To develop or deploy a version of MapComplete, have a look [to the guide ](Docs/Development_deployment.md ).
2020-08-24 22:42:59 +02:00
2022-09-19 12:38:31 +02:00
## Creating your own theme
2021-11-07 16:34:51 +01:00
2022-09-19 12:38:31 +02:00
It is possible to quickly make and distribute your own theme, [please read the documentation on how to do this ](Docs/Making_Your_Own_Theme.md ).
The main developer is currently _not_ taking requests for new themes (unless they are commissioned). There are simply to much good thematic maps to make.
We do however encourage you to try to create your own theme yourself - we'll gladly accept it as official theme if it meets the criteria.
2020-08-24 22:42:59 +02:00
2020-07-09 15:27:09 +02:00
## Examples
2022-01-31 20:34:09 +01:00
- [An overview of all official themes ](https://mapcomplete.osm.be ).
2021-09-09 00:05:51 +02:00
- [Buurtnatuur.be ](http://buurtnatuur.be ), developed for the Belgian [Green party ](https://www.groen.be/ ). They also
funded the initial development!
2022-01-31 20:34:09 +01:00
- [Cyclofix ](https://mapcomplete.osm.be/cyclofix.html ), further development
2021-09-09 00:05:51 +02:00
on [Open Summer of Code ](https://summerofcode.be/ ) funded
by [Brussels Mobility ](https://mobilite-mobiliteit.brussels/en ). Landing page at https://cyclofix.osm.be/
2022-01-31 20:34:09 +01:00
- [Bookcases ](https://mapcomplete.osm.be/bookcases.html ) cause I like to collect
2021-09-09 00:05:51 +02:00
them.
2022-01-31 20:34:09 +01:00
- [Map of Maps ](https://mapcomplete.osm.be/maps.html ),
2021-09-09 00:05:51 +02:00
after a tweet
2022-12-08 09:59:35 +01:00
- [A build of the develop branch can be found here ](https://pietervdvn.github.io/mc/develop )
2020-07-09 15:27:09 +02:00
2021-10-29 16:35:29 +02:00
There are plenty more. [Discover them in the app ](https://mapcomplete.osm.be/index.html ).
2020-07-09 15:27:09 +02:00
2020-09-07 02:47:21 +02:00
### Statistics
2021-09-09 00:05:51 +02:00
To see statistics,
consult [OsmCha ](https://osmcha.org/?filters=%7B%22comment%22%3A%5B%7B%22label%22%3A%22%23mapcomplete%22%2C%22value%22%3A%22%23mapcomplete%22%7D%5D%2C%22date__gte%22%3A%5B%7B%22label%22%3A%222020-07-05%22%2C%22value%22%3A%222020-07-05%22%7D%5D%7D )
or the [analytics page ](https://pietervdvn.goatcounter.com/ )
2020-09-07 02:47:21 +02:00
2020-08-22 18:57:27 +02:00
## User journey
MapComplete is set up to lure people into OpenStreetMap and to teach them while they are on the go, step by step.
A typical user journey would be:
2020-08-25 00:10:48 +02:00
0. Oh, this is a cool map of _my specific interest_ ! There is a lot of data already...
2020-08-25 00:20:20 +02:00
2020-08-25 12:34:17 +02:00
* The user might discover the explanation about OSM in the second tab
* The user might share the map and/or embed it in the third tab
* The user might discover the other themes in the last tab
2021-09-09 00:05:51 +02:00
1. The user clicks that big tempting button 'login' in order to answer questions - there's enough of these login
buttons... The user creates an account.
2020-08-25 00:20:20 +02:00
2020-08-25 12:34:17 +02:00
2. The user answers a question! Hooray! The user transformed into a __contributor__ now.
2021-09-09 00:05:51 +02:00
2020-08-25 12:34:17 +02:00
* When at least one question is answered (aka: having one changeset on OSM), adding a new point is unlocked
2021-09-09 00:05:51 +02:00
2020-08-25 00:20:20 +02:00
3. The user adds a new POI somewhere
* Note that _all messages_ must be read before being able to add a point.
2021-09-09 00:05:51 +02:00
* In other words, sending a message to a misbehaving MapComplete user acts as having a **zero-day-block** . This is
added deliberately to make sure new users _have_ to read feedback from the community.
2020-08-25 00:20:20 +02:00
2022-06-07 03:34:32 +02:00
4. At 50 changesets, the [personal layout ](https://mapcomplete.osm.be/personal.html ) is advertised. The
2021-09-09 00:05:51 +02:00
personal theme is a theme where contributors can pick layers from all the official themes. Note that the personal
theme is always available.
2020-08-25 00:20:20 +02:00
2021-09-09 00:05:51 +02:00
5. At 200 changesets, the tags become visible when answering questions and when adding a new point from a preset. This
is to give more control to power users and to teach new users the tagging scheme
2020-08-25 00:20:20 +02:00
2021-09-09 00:05:51 +02:00
6. At 250 changesets, the tags get linked to the wiki
2020-08-22 18:57:27 +02:00
2021-09-09 00:05:51 +02:00
7. At 500 changesets, I expect contributors to be power users and to be comfortable with tagging scheme and such. The
custom theme generator is unlocked.
2020-08-22 18:57:27 +02:00
2020-06-24 00:35:19 +02:00
## License
2020-08-26 15:36:04 +02:00
GPLv3.0 + recommended pingback.
2020-06-24 00:35:19 +02:00
2021-09-09 00:05:51 +02:00
I love it to see where the project ends up. You are free to reuse the software (under GPL) but, when you have made your
own change and are using it, I would like to know about it. Drop me a line, give a pingback in the issues,...
2020-06-24 00:35:19 +02:00
2020-08-24 22:42:59 +02:00
## Translating MapComplete
2021-09-09 00:05:51 +02:00
The core strings and builtin themes of MapComplete are translated
on [Hosted Weblate ](https://hosted.weblate.org/projects/mapcomplete/core/ ). You can easily make an account and start
translating in their web-environment - no installation required.
2020-08-24 22:42:59 +02:00
2022-07-02 23:12:42 +02:00
You can even jump to the right translation string directly from MapComplete:
2021-05-19 16:15:12 +02:00
[](https://hosted.weblate.org/engage/mapcomplete/)
2020-06-24 00:35:19 +02:00
## Architecture
### High-level overview
2021-09-09 00:05:51 +02:00
The website is purely static. This means that there is no database here, nor one is needed as all the data is kept in
OpenStreetMap, Wikimedia (for images), Imgur. Settings are saved in the preferences-space of the OSM-website, amended by
some local-storage if the user is not logged-in.
2020-06-24 00:35:19 +02:00
2021-09-09 00:05:51 +02:00
When viewing, the data is loaded from overpass. The data is then converted (in the browser) to geojson, which is
rendered by Leaflet.
2020-06-24 00:35:19 +02:00
When a map feature is clicked, a popup shows the information, images and questions that are relevant for that object.
2021-09-09 00:05:51 +02:00
The answers given by the user are sent (after a few seconds) to OpenStreetMap directly - if the user is logged in. If
not logged in, the user is prompted to do so.
2020-07-21 22:50:54 +02:00
2021-09-09 00:05:51 +02:00
The UI-event-source is a class where the entire system is built upon, it acts as an observable object: another object
can register for changes to update when needed.
2020-07-21 22:50:54 +02:00
2020-06-25 03:39:31 +02:00
### Searching images
2020-06-24 00:35:19 +02:00
2020-06-25 03:39:31 +02:00
Images are fetched from:
2020-06-24 00:35:19 +02:00
2020-06-25 03:39:31 +02:00
- The OSM `image` , `image:0` , `image:1` , ... tags
- The OSM `wikimedia_commons` tags
- If wikidata is present, the wikidata `P18` (image) claim and, if a commons link is present, the commons images
### Uploading images
2021-04-23 09:57:10 +02:00
Images are uploaded to Imgur, as their API was way easier to handle. The URL is written into the changes.
2020-06-25 03:39:31 +02:00
2021-09-09 00:05:51 +02:00
The idea is that once in a while, the images are transferred to wikipedia or that we hook up wikimedia directly (but I
need some help in getting their API working).
2020-08-27 18:44:16 +02:00
### Uploading changes
2021-09-09 00:05:51 +02:00
In order to avoid lots of small changesets, a changeset is opened and kept open. The changeset number is saved into the
users preferences on OSM.
2020-08-27 18:44:16 +02:00
2021-09-09 00:05:51 +02:00
Whenever a change is made -even adding a single tag - the change is uploaded into this changeset. If that fails, the
changeset is probably closed and we open a new changeset.
2020-06-28 00:06:23 +02:00
2021-09-09 00:05:51 +02:00
Note that changesets are closed automatically after one hour of inactivity, so we don't have to worry about closing
them.
2020-06-28 00:06:23 +02:00
2020-06-28 23:33:48 +02:00
# Privacy
2020-06-28 00:06:23 +02:00
2021-09-09 00:05:51 +02:00
Privacy is important, we try to leak as little information as possible. All major personal information is handled by
OSM. Geolocation is available on mobile only through the device's GPS location (so no geolocation is sent of to Google).
2020-06-28 23:33:48 +02:00
TODO: erase cookies of third party websites and API's
2020-06-28 00:06:23 +02:00
2021-04-17 11:37:22 +02:00
# Attribution and Copyright
2020-06-28 00:06:23 +02:00
2021-04-17 11:37:22 +02:00
The code is available under GPL; all map data comes from OpenStreetMap (both foreground and background maps).
2020-09-27 18:45:37 +02:00
Background layer selection: curated by https://github.com/osmlab/editor-layer-index
2021-04-09 17:56:13 +02:00
Icons are attributed in various 'license_info.json'-files and can be found in the app.
