MapComplete/Docs/Studio/Integrating_Maproulette.md

# Integrating MapRoulette

## Importing points

[MapRoulette](https://www.maproulette.org/) 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.](https://wiki.openstreetmap.org/wiki/Import/Guidelines)

(Another approach to set up a guided import is to create a map note for every point with the [import helper](https://mapcomplete.org/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 that should be imported there and stringify it.

You have quite some freedom for the other tags. Make sure to add an *id* tag. Other tags (e.g. images, metadata) may go into the properties as well.
However, do _not_ add the generic tags for the layer to import into, to avoid that the maproulette challenges are loaded by the target layer.


```
{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {"type": "Point", "coordinates": [1.234, 5.678]},
            "properties": {
                "id": ..., # Especially important when you want to rebuild the data
                "image": ...,
                "lastModifiedBy": ..., # from the source data, just to help
                "tags": "foo=bar;name=xyz;image=...", # To be imported
            }
        
        }
    
    ] 
}

```

Then, create a challenge on https://maproulette.org/admin/projects (or, if you want to test first, on https://staging.maproulette.org/)


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`](./Docs/Layers/maproulette_challenge.md). Extend this layer with your needs.**
The API is shortly discussed here for future reference only.

Hint: use [the maproulette theme in debug mode](https://mapcomplete.org/maproulette?debug=true) to inspect all properties.

To view the overview a single challenge, visit `https://maproulette.org/browse/challenges/<challenge-id>` with your
browser.
To get the challenge-id, visit the overview of a challenge in your browser. The URL will end with `/project/<project-id>/challenge/<challenge-id>?`. You can ignore the project-id and use the `challenge-id`. Challenge ids are unique and straight from the database, even over users and projects.

The API endpoint for a single challenge is `https://maproulette.org/api/v2/challenge/view/<challenge-id>` which returns a
geojson. This endpoint supports a bbox to only return a part of the challenge: `https://maproulette.org/api/v2/challenge/view/<challenge-id>?bbox=west,south,east,north`

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](Docs/Layers/maproulette_challenge.md).
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`](./Docs/CalculatedTags.md) 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](./Docs/SpecialRenderings.md#importbutton)).
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:

```json
{
    "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](./Docs/SpecialRenderings.md#tagapply).

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

```json

 {
    "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](./Docs/Layers/maproulette.md) (_not_ the `maproulette-challenge`-layer!), such as [`maproulette.mark_fixed`](./Docs/Layers/maproulette.md#markfixed),[`maproulette.mark_duplicate`](./Docs/Layers/maproulette.md#markduplicate),[`maproulette.mark_too_hard`](./Docs/Layers/maproulette.md#marktoohard).

In the background, these use the special visualisation [`maproulette_set_status`](./Docs/SpecialRenderings.md#maproulettesetstatus) - which allows to apply different status codes or different messages/icons.