This tutorial is for MapRoulette 1 which is no longer active. Please see the MapRoulette 2 wiki for up to date documentation.
You have played MapRoulette. You have seen some of the fun challenges. If you are reading this, you are probably thinking: 'I have a great idea for the next MapRoulette challenge!'
Great! That is exactly what I am here to explain step by step. So let's get started!
The first thing you need is a great idea for a challenge. You probably think you already have one, and you may be right! There are a few ground rules to a great MapRoulette challenge:
- The problems (tasks) require a human eye. If it can be automatically fixed, it is probably boring for humans to work on.
- The task is clear and specific. It should be immediately obvious to the mapper what needs to be fixed, so your question needs to be clear and point to specific nodes or ways.
- It takes seconds, not minutes, to fix the problems. The MapRoulette Flow relies on mappers being able to quickly resolve the problem. This is what makes MapRoulette addictive!
- No local knowledge is required. Folks should be able to resolve the problem just by looking at the data and available aerial imagery.
- The problem is machine-detectable. Well, theoretically you could manually pick the OSM ways or nodes you want fixed, but a typical challenge has hundreds or even thousands of tasks. You will need a query or process to reliably produce the problems you want fixed.
- Please add the name of this road. Requires local knowledge, so not a good MapRoulette challenge.
- Please add the opening hours for this business. Might be OK, because mappers can look up the opening hours on the internet. Possibly takes too long and requires googling taking mappers out of the MapRoulette 'flow' - would need testing.
- Please connect these ways we think should be connected. Great MapRoulette challenge: clear and specific, no local knowledge required, but does require a human eye.
- Is this business still open? Requires local knowledge to verify, so not a good MapRoulette challenge.
- Please fix up this neighborhood. This is a vague question and does not point to specific features or things you want fixed. Bad MapRouette Challenge idea.
For more inspiration, just have a look at the currently active MapRoulette challenges!
A challenge consists of two equally important parts: the Challenge metadata and the Tasks. We will cover the metadata in this section. Then we will go into preparing the Tasks in the next section.
Source: Flickr Commons
The Challenge metadata describes what the challenge is, both to MapRoulette and to the user. Here is what you need to define:
A short, descriptive title. The title will show up at the top of the sidebar, and also in the challenge selection panel. The Challenge title is what MapRoulette users will recognize your challenge by. It should give MapRoulette users a good idea of what the Challenge is about.
The Challenge Title shows up in various places, for example in the Welcome screen for mappers who are already logged in:
Having a Title is required.
The Blurb is a oneliner that shows up underneath the Title in the sidebar and in the challenge selection window. You could see it as a subtitle.
Having a Blurb is optional but recommended.
The Description is a longer description of your Challenge. Here you can explain in a few sentences what you want mappers to fix, and why. The Description is displayed when a user starts working on a challenge.
You can use Markdown here.
Having a Description is optional but recommended.
The Help is where you can provide mappers with more detailed instructions about how to complete the tasks.
You can use Markdown for the Help.
Having a Help text is optional but recommended.
The Instruction is a prompt telling mappers what you want them to do to complete the Task. The Instruction shows up as a notification every time a user sees a new Task, so it should be brief and to the point.
Each Task can also have its own Instruction. If your Tasks have their own Instructions, these will be displayed instead, and the Challenge Instruction will not be used.
Having an Instruction is required. If you do not supply an Instruction for the Challenge, you will need to supply one for each individual task. We will look into that in the next section.
The Challenge Style Guide has advice on choosing appropriate values for your Challenge.
Now that you have all the required metadata, you will need to create a JSON file from it. We will use this JSON file to talk to the MapRoulette server later. The format is described in the API documentation. It looks like this:
{
"title": "Missing Cuisines",
"blurb": "Add cuisine tag to restaurants",
"description": "Lots of restaurants have no `cuisine` defined in OSM. See if you can help add this valuable information! Check out [http://wiki.openstreetmap.org/wiki/Key:cuisine](the cuisine tag) on the wiki.",
"instruction": "See if you can add the cuisine to this restaurant.",
"help": "This challenge will show you Restaurants in OpenStreetMap that do not have a [http://wiki.openstreetmap.org/wiki/Key:cuisine](cuisine) tag. The cuisine tag tells you what type of restaurant it is. This can be a style or type of food, like `fast_food`, or a regional designation, like `thai`. Follow the link to the wiki for more information. Most of the time, you will be able to tell just from the name. If you are unsure, you can try looking up the web site of the restaurant on the internet, or skip to the next restaurant.",
"difficulty": 1,
"active": false
}The slug is not in the JSON - it will be part of the endpoint, following good RESTful practice. We'll see how that works later.
Save this JSON file somewhere safe.
We have all the information we need for the Challenge, but we don't have any Tasks yet. In the next section, we will talk about how to gather Tasks for your Challenge.
Your MapRoulette Challenge will consist of Tasks. One Task represents one thing you want mappers to fix. Most Challenges have hundreds, or even thousands of Tasks. Once MapRoulette knows about your tasks, it will keep track of their status internally. If someone marks a task as Fixed or Not an Error for example, it will no longer be shown - unless you tell MapRoulette to make it reappear. (More on that later, when we talk about Challenge maintenance.)
Source: Flickr Commons
Each Task needs to have a unique Identifier, Geometries, and optionally an Instruction.
The unique identifier can be any string of 72 characters or less. It just needs to be unique for your Challenge, and persistent, so both MapRoulette and you can keep track of the Task.
Having an Identifier is required.
Each Task has one or more geometries: points, lines or polygons. These are shown on top of the OSM map in MapRoulette and point out to the mapper what it is that we think needs fixing. Often, the geometry belonging to a task will be that of an OSM node or way, but it does not have to be.
In this example, a single Point was supplied as the Geometries for this Task:
In this example, a Linestring was used:
You can supply a mix of Points and Linestrings if you want.
The geometries need to be supplied as a GeoJSON FeatureCollection, even if it is just one Point or Linestring.
If your Geometries correspond to OSM nodes or ways, you should supply the OSM ID in the properties member of your GeoJSON as osmid. The OSM IDs will be passed to the editor when the mapper clicks Edit in JOSM / iD, and the OSM features will be pre-selected. This makes it easier for the mapper to recognize the relevant OSM feature(s).
Here is an OSM node represented as GeoJSON with the osmid property set:
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"osmid": 1834370484
},
"geometry": {
"type": "Point",
"coordinates": [
-111.890752,
40.7695772
]
}
}
]
}See below for a full MapRoulette Task JSON example.
Having Geometries (one or more) is required.
The Instruction is a prompt telling mappers what you want them to do to complete the Task. The Instruction shows up as a notification every time a user sees a new Task, so it should be brief and to the point.
As mentioned, any Instruction provided for a Task will override the Instruction at the Challenge level. This is useful if you need to provide an Instruction that is tailored to each individual task.
Having an Instruction is required. However, in most cases, you will supply it at the Challenge level. You should supply an Instruction for individual Tasks only if you need to have a different instruction text for each task.
You will need to create a JSON file describing the collection of Tasks, containing the elements described just now. How you create that JSON file is up to you, and will probably require some scripting :( The MapRoulette list is a good place to ask for help with this, because most of the folks who have created Challenges before are on there.
We will use this JSON file to talk to the MapRoulette server later. The format is described in the API documentation. Here is an example:
[
{
"geometries": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"osmid": 1834370484
},
"geometry": {
"type": "Point",
"coordinates": [
-111.890752,
40.7695772
]
}
}
]
},
"identifier": "-245422134830019020515072624911431000923134125997",
"instruction": "This is [Nauvoo Cafe](https://www.google.com/#q=Nauvoo+Cafe). Can you add the opening hours?"
},
[....]
]We now have all the information we need to actually submit a challenge to MapRoulette: Challenge metadata and Tasks. In the next sections, we will discuss how to actually submit your work to MapRoulette
At this point, you will have two files:
- A JSON file describing your Challenge metadata.
- A JSON file describing the Tasks for your Challenge.
Source: Flickr Commons
You are now ready to upload your Challenge to the MapRoulette staging server, located at dev.maproulette.org/. This server runs a version of MapRoulette that is very similar to the main server, with the following exceptions:
- The basic authentication username is
devuserand the password ismylittlesony. - The MapRoulette software may be a slightly newer version - but expect no major differences.
The process of uploading a new Challenge consists of two steps: registering the Challenge with MapRoulette, and uploading the Tasks.
For this step, we will use the JSON file with the Challenge metadata. We will send this JSON data as a payload with a POST request to the Challenge create / update API endpoint. How you do this is up to you; curl works just fine, or use a GUI tool like Postman. Here is a curl example:
curl -u devuser:mylittlesony -v -X POST http://dev.maproulette.org/api/admin/challenge/my-awesome-challenge -d @/path/to/challenge.json --header "Content-Type: application:json"```
### Sanity check
Now that your challenge is on the staging area at `dev.maproulette.org`, anyone can see it. At this point, it would be a good idea to ask a few others to look at your Challenge and provide feedback. It is also a good idea to get in touch with Serge and Martijn at [[email protected]](mailto:[email protected]) if you hadn't done that yet. We are always happy to have a look and help out with feedback and debugging. (If you don't hear from us for a couple of days, don't despair. We will get back to you!)
### What's Next?
So your challenge looks OK on the staging environment - great! Let's move on the real thing!
## Step 6 - Getting Access to `maproulette.org`
By now, you have tested your upload workflow on `dev.maproulette.org`. You have sanity tested the challenge, and invited a few others to look at it also. If everything looks good, it's time to finally upload your work to `maproulette.org`!
*Source: [Flickr Commons](https://www.flickr.com/photos/internetarchivebookimages/14780710731)*
Unlike `dev.maproulette.org`, the challenge administration endpoints on `maproulette.org` are only accessible from `localhost`. What that means is that you need to call those endpoints from the same machine, so you will need to have **access to maproulette.org**.
To get access, send an email to [email protected] and we will take care of you. At this point, it is very likely that you have already been in touch with Serge or Martijn, the MapRoulette maintainers. Both of them receive the emails sent to this address. We will ask you for your public SSH key, which we will add to the `authorized_keys` for the `[email protected]` account. (If you are not sure what all this means, please [read up on](https://macnugget.org/projects/publickeys/) public key authentication). We will let you know when that's done, and when it is, you can log on to `[email protected]`.
Note that this account does not have interactive shell privileges, but you can set up a SSH tunnel providing you with all the access you need to the machine :) The way that works is as follows. First you [create the SSH tunnel](http://www.revsys.com/writings/quicktips/ssh-tunnel.html). For example, if you want to tunnel from port 8000 on your local machine to port 80 on `maproulette.org`, you would do that as follows:
```shell
ssh -f [email protected] -L 8000:maproulette.org:80 -NOnce the tunnel is established, you would call the MapRoulett API endpoints as follows:
$ curl localhost:8000/api/ping
["I am alive"]You are now ready to submit your challenge to MapRoulette for real!
Source: Flickr Commons
Now that you really have everything you need to post your Challenge to maproulette.org, you can perform the same sequence of steps you used to test your challenge on dev.maproulette.org - only replacing the server host portion of the URL with localhost:8000, or whatever port you are tunneling from. (This assumes that you have created the SSH tunnel as explained in the previous section.) To repeat:
- Create your challenge
POST /api/admin/challenge/<slug>with the challenge JSON as payload - Upload your tasks
POST /api/admin/challenge/<slug>/taskswith the tasks JSON as payload - Update your challenge to set its status to
activeso it becomes visiblePUT /api/admin/challenge/<slug>with payload{"active": true}. - Go to
maproulette.organd share your new challenge!
You are live! Announce your challenge on the OSM mailing lists, your diary, the forums, twitter, wherever you think it's appropriate.
But... You are not quite done! Now that your Challenge is out there, you need to maintain it as well. The best Challenges are well maintained. We will look at what Challenge maintenance entails in the next and last section.
So your Challenge is live, your Tasks are out there for the community to fix. Why would you need to perform maintenance? Three important reasons:
- Tasks may get fixed outside of MapRoulette.
- Mappers may mark Tasks as Fixed or Not An Error in Maproulette, but they were wrong.
- New errors appear in OSM, and nodes and ways get moved around.
Source: Flickr Commons
Challenge maintenance basically means a periodical 'reality check' for your Tasks: are they still valid, are they really fixed, are they still in the same place, are there new ones?
Technically, this is not a required step, but mappers who log onto MapRoulette and are confronted with Tasks that are already fixed, or don't exist in the location you point them to, will get frustrated and will move on to another, well maintained challenge :)
A Challenge maintenance workflow looks like this:
- Re-run the query or process you use to collect your Tasks
- Get the current status of the Tasks from the MapRoulette server
GET http://localhost:8000/api/admin/challenge/<slug>/tasks - Compare your new list to the server list
- Upload new Tasks
POST http://localhost:8000/api/admin/challenge/<slug>/tasksand update Tasks that need their status changedPUT http://localhost:8000/api/admin/challenge/<slug>/tasks
We suggest that you automate this to run at least once a week, but even better is daily. More than once per day is usually overkill.
There is no Step 9 :)
Thank you for being part of the MapRoulette community! If you have any questions, drop Serge and Martijn a line at [email protected], or subscribe and post to the MapRoulette list. If you think you have found a bug in MapRoulette, please log on to the MapRoulette repository on GitHub and file an issue there.
Source: Flickr Commons