Integrating_Maproulette.md

Integrating MapRoulette

Importing points

MapRoulette is a website which has challenges. A challenge is a collection of microtasks, i.e. mapping tasks which can be solved in a few minutes.

A perfect example of this is to setup such a challenge to e.g. import new points.

Important: always follow the import guidelines if you want to import data.

(Another approach to set up a guided import is to create a map note for every point with the import helper. This however litters the map notes and will upset mappers if used with to much points. However, this flow is easier to setup as no changes to theme files are needed, nor is a maproulette-account needed)

Preparing the data

Convert your source data into a geojson. Use tags as field where all the OSM-properties should go. Make sure to include all tags there.

Hint: MapRoulette has a button 'rebuild task', where you can first 'remove all incomplete tasks'. This is perfect to start over in case of small data errors.

The API

Most of the heavy lifting is done in layer maproulette-challenge. Extend this layer with your needs. The API is shortly discussed here for future reference only.

There is an API-endpoint at https://maproulette.org/api/v2/tasks/box/{x_min}/{y_min}/{x_max}/{y_max} which can be used to query all tasks in a bbox and returns this as geojson. Hint: use the maproulette theme in debug mode to inspect all properties.

To view the overview a single challenge, visit https://maproulette.org/browse/challenges/<challenge-id> with your browser. The API endpoint for a single challenge is https://maproulette.org/api/v2/challenge/view/<challenge-id> which returns a geojson.

Override the geojson-source in order to use the challenge:

{
    "builtin": "maproulette_challenge",
    "override" : {
        "source": {
            "geoJson": "https://maproulette.org/api/v2/challenge/view/<challenge-id>"
        }
    }
}

Displaying MapRoulette data in MapComplete

As you'll probably want to link MapComplete to your challenge, reuse maproulette_challenge. It has a basic framework already to load the tags.

Of course, interacting with the tasks is the next step.

Detecting nearby features

You can use calculatedTags to add a small piece of code to e.g. detect nearby entities.

The following example is to match hotels:

    "calculatedTags": [
      "_closest_osm_poi=feat.closest('hotel')?.properties?.id",
      "_closest_osm_poi_distance=feat.distanceTo(feat.properties._closest_osm_poi)",
      "_has_closeby_feature=Number(feat.properties._closest_osm_poi_distance) < 50 ? 'yes' : 'no'"
    ], 

This can be used to decide if tags should be applied on an existing object or a new point should be created.

Creating a new point based on a maproulette challenge (Guided import)

Requirement: the MapRoulette task should have tags added.

One can add import-button in the featureInfoBox (documentation here). Note that the import button has support for MapRoulette and is able to close the task if the property containing the maproulette-id is given:

{
    "id": "import-button",
    "condition": "_has_closeby_feature=no",
    "render": {
      "special": {
        "type": "import_button",
        "targetLayer": "<the layer in which the point should appear afterwards>",
        "tags": "tags", -- should stay 'tags', unless you took a different name while creating the data
        "maproulette_id": "mr_taskId",  -- important to get the task closed
        "text": {
          "en": "Import this point" -- or a nice message
        },
        "icon": "./assets/svg/addSmall.svg", -- optional, feel free to change
        "location_picker": "photo", -- optional, background layer to pinpoint the hotel
      }
    }
}

Applying tags to already existing features

For this, the tag_apply-button can be used.

The following example uses the calculated tags _has_closeby_feature and _closest_osm_hotel. These were added by a small extra script using calculatedTagss.

 {
    "id": "tag-apply-button",
    "condition": "_has_closeby_feature=yes", -- don't show if no feature to add to
    "render": {
      "special": {
        "type": "tag_apply",
        "tags_to_apply": "$tags", -- note the '$', property containing the tags
        "id_of_object_to_apply_this_one": "_closest_osm_poi" -- id of the feature to add those tags to
        "message": {
          "en": "Add all the suggested tags"
        },
        "image": "./assets/svg/addSmall.svg"
      }
    }
  }

Changing the status of the task

The easiest way is to reuse a tagrendering from the Maproulette-layer (not the maproulette-challenge-layer!), such as maproulette.mark_fixed,maproulette.mark_duplicate,maproulette.mark_too_hard.

In the background, these use the special visualisation maproulette_set_status - which allows to apply different status codes or different messages/icons.

Creating a maproulette challenge

A challenge can be created on https://maproulette.org/admin/projects

This can be done with a geojson-file (or by other means).

MapRoulette works as a geojson-store with status fields added. As such, you have a bit of freedom in creating the data, but an id field is mandatory. A name tag is recommended

To setup a guided import, add a tags-field with tags formatted in such a way that they are compatible with the import-button

(The following example is not tested and might be wrong.)

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {"type": "Point", "coordinates": [1.234, 5.678]},
            "properties": {
                "id": ...
                "tags": "foo=bar;name=xyz",
            }
        
        }
    
    ] 
}