Functionality¶

For usage examples check out this link.

Module: project¶

This module contains the methods that the user will use directly to interact with MapRoulette projects

class maproulette.api.project.Project(config)¶

Bases: maproulette.api.maproulette_server.MapRouletteServer

Class to handle the project-related API requests

add_challenge_to_project(project_id, challenge_id)¶

Method to add a challenge to a virtual project.

Parameters

project_id – the id of the virtual project
challenge_id – the id of the challenge being added

Returns

the API response from the POST request

create_project(data)¶

Method to create a new project

Parameters: data – the data to use to create the new project
Returns: the API response to the POST request

delete_project(project_id, immediate='false')¶

Method to delete a project.

Parameters

project_id – the id of the project being deleted
immediate – whether or not the project should be deleted immediately

Returns

the API response form the DELETE request

find_project(matcher='', limit=10, page=0, only_enabled='true')¶

Method to search for projects based on a specific search criteria

Parameters

matcher – the search string used to match the project names. Default is empty string
limit – the limit to the number of results returned in the response. Default is 10
page – used in conjunction with the limit parameter to page through X number of responses. Default is 0.
only_enabled – flag to set if only wanting enabled projects returned. Default is True.

Returns

the API response from the GET request

get_project_by_id(project_id)¶

Method to fetch a project by unique MapRoulette project ID

Parameters: project_id – the unique project ID
Returns: the API response from the GET request

get_project_by_name(project_name)¶

Method to fetch a project by unique MapRoulette project name

Parameters: project_name – the unique project name
Returns: the API response from the GET request

get_project_challenges(project_id, limit=10, page=0)¶

Method to fetch a list of a project’s challenges.

Parameters

project_id – the id of the parent project
limit – the limit to the number of results returned in the response. Default is 10
page – used in conjunction with the limit parameter to page through X number of responses. Default is 0.

Returns

the API response from the GET request

get_projects_by_ids(project_ids)¶

Method to retrieve projects from comma separated list of ids

Parameters: project_ids – comma separated list of project ids to be retrieved
Returns: the API response from the GET request

get_random_tasks(project_id, limit=1, proximity=-1, search='')¶

Method to retrieve random tasks from a project.

Parameters

project_id – the id of the parent project of tasks
limit – limit amount of results returned
proximity – task to find based on proximity of that task
search – a search parameter object stored in a cookie

Returns

the API response form the GET request

static is_project_model(input_object)¶

Method to determine whether user input is a valid project model

Parameters: input_object – the user’s input to check
Returns: True if instance of model

remove_challenge_from_project(project_id, challenge_id)¶

Method to remove a challenge from a virtual project.

Parameters

project_id – the id of the virtual project
challenge_id – the id of the challenge being removed

Returns

the API response from the POST request

update_project(project_id, data)¶

Method to update an existing project

Parameters

project_id – the id of the project being updated
data – the data to use to update the project

Returns

the API response from the PUT request

Module: challenge¶

This module contains the methods that the user will use directly to interact with MapRoulette challenges

class maproulette.api.challenge.Challenge(config)¶

Bases: maproulette.api.maproulette_server.MapRouletteServer

Class to handle the challenge-related API requests

add_file_tasks_to_challenge(data, challenge_id, line_by_line='true', remove_unmatched='false', data_origin_date='', skip_snapshot='false')¶

Method to add tasks to an existing challenge with tasks as GeoJSON

Parameters

data – a GeoJSON containing geometry of tasks to be added to a challenge
challenge_id – the ID corresponding to the challenge that tasks will be added to
line_by_line – whether or not the provided data is in line-by-line GeoJSON format
remove_unmatched – whether or not the JSON provided includes seperate GeoJSON on each line
data_origin_date – the date the data was sourced on
skip_snapshot – whether or not to skip recording a snapshot before proceeding

Returns

the API response from the PUT request

add_tasks_to_challenge(data, challenge_id)¶

Method to add tasks to an existing challenge

Parameters

data – a GeoJSON containing geometry of tasks to be added to a challenge
challenge_id – the ID corresponding to the challenge that tasks will be added to

Returns

the API response from the PUT request

create_challenge(data)¶

Method to create a new challenge

Parameters: data – a JSON input containing challenge details
Returns: the API response to the POST request

create_virtual_challenge(data)¶

Method to create a new virtual challenge

Parameters: data – a JSON input containing virtual challenge details
Returns: the API response to the POST request

delete_challenge(challenge_id, immediate='false')¶

Method to delete a challenge by using the corresponding challenge ID

Parameters

challenge_id – the ID corresponding to the challenge
immediate – whether or not the challenge should be deleted immediately

Returns

the API response from the DELETE request

delete_challenge_tasks(challenge_id, status_filters='')¶

Method to delete all existing tasks within a challenge, optionally filtering on current task status

Parameters

challenge_id – the ID corresponding to the challenge
status_filters – a comma separate list of status ID’s: 0 = Created, 1 = Fixed, 2 = False Positive, 3 = Skipped, 4 = Deleted, 5 = Already Fixed, 6 = Too Hard

Returns

the API response from the DELETE request

extract_challenge_comments(challenge_id, limit=10, page=0)¶

Method to retrieve all comments for the tasks in a given challenge and respond with a CSV

Parameters

challenge_id – the ID corresponding to the challenge
limit – the limit to the number of results returned in the response. Default is 10
page – used in conjunction with the limit parameter to page through X number of responses. Default is 0.

Returns

the API response from the GET request

extract_task_summaries(challenge_id, limit=10, page=0, status='', review_status='', priority='', export_properties='', task_property_search='')¶

Method to retrieve summaries of all the tasks in a given challenge and respond with a CSV

Parameters

challenge_id – the ID corresponding to the challenge
limit – the limit to the number of results returned in the response. Default is 10
page – used in conjunction with the limit parameter to page through X number of responses. Default is 0.
status – a comma-separated filter for the tasks returned using tasks status values: 0 = Created, 1 = Fixed, 2 = False Positive, 3 = Skipped, 4 = Deleted, 5 = Already Fixed, 6 = Too Hard
review_status – a comma-separated filter for the tasks returned using review status values: 0 - Requested, 1 - Approved, 2 - Rejected, 3 - Assisted, 4 - Disputed
priority – a comma-separated filter for the tasks returned by priority value: 0 - High, 1 - Medium, 2 - Low
export_properties – a comma-separated filter for the properties that should be exported
task_property_search – a filter for the tasks returned using task properties

Returns

the API response from the GET request

get_challenge_by_id(challenge_id)¶

Method to retrieve challenge information via the corresponding challenge ID

Parameters: challenge_id – the ID corresponding to the challenge
Returns: the API response from the GET request

get_challenge_by_name(project_id, challenge_name)¶

Method to retrieve challenge information via the corresponding challenge name and parent (project) ID

Parameters

project_id – the ID of the parent project
challenge_name – the name corresponding to the challenge

Returns

the API response from the GET request

get_challenge_children(challenge_id, limit=10, page=0)¶

Method to retrieve all children from a given challenge in an expanded list. Unlike the get_challenge_tasks() method, this function will wrap the JSON array list inside of the parent challenge object allowing you to see the full hierarchy.

Parameters

challenge_id – the ID corresponding to the challenge
limit – the limit to the number of results returned in the response. Default is 10
page – used in conjunction with the limit parameter to page through X number of responses. Default is 0.

Returns

the API response from the GET request

get_challenge_comments(challenge_id, limit=10, page=0)¶

Method to retrieve all comments for the tasks in a given challenge

Parameters

challenge_id – the ID corresponding to the challenge
limit – the limit to the number of results returned in the response. Default is 10
page – used in conjunction with the limit parameter to page through X number of responses. Default is 0.

Returns

the API response from the GET request

get_challenge_geojson(challenge_id, status='', review_status='', priority='', task_property_search='')¶

Method to retrieve the GeoJSON for a challenge that represents all the task children of the challenge

Parameters

challenge_id – the ID corresponding to the challenge
status – a comma-separated filter for the tasks returned using tasks status values: 0 = Created, 1 = Fixed, 2 = False Positive, 3 = Skipped, 4 = Deleted, 5 = Already Fixed, 6 = Too Hard
review_status – a comma-separated filter for the tasks returned using review status values: 0 - Requested, 1 - Approved, 2 - Rejected, 3 - Assisted, 4 - Disputed
priority – a comma-separated filter for the tasks returned by priority value: 0 - High, 1 - Medium, 2 - Low
task_property_search – a filter for the tasks returned using task properties

Returns

the API response from the GET request

get_challenge_listing(project_ids='', limit=10, page=0, only_enabled='true')¶

Method to retrieve a lightweight list of challenges that belong to the specified project(s)

Parameters

project_ids – a comma-separated list of project IDs for which child challenges are desired. Default is an empty string (i.e. all projects)
limit – the limit to the number of results returned in the response. Default is 10
page – used in conjunction with the limit parameter to page through X number of responses. Default is 0.
only_enabled – whether or not results should be limited to only enabled challenges. Default is true.

Returns

the API response from the GET request

get_challenge_statistics_by_id(challenge_id)¶

Method to retrieve statistics for a challenge using its corresponding ID

Parameters: challenge_id – the ID corresponding to the challenge
Returns: the API response to the GET request

get_challenge_tasks(challenge_id, limit=10, page=0)¶

Method to retrieve all tasks from a given challenge by ID

Parameters

challenge_id – the ID corresponding to the challenge
limit – the limit to the number of results returned in the response. Default is 10
page – used in conjunction with the limit parameter to page through X number of responses. Default is 0.

Returns

the API response from the GET request

get_challenges_by_tags(challenge_tags, limit=10, page=0)¶

Method to retrieve challenge information via tags applied to the challenge

Parameters

challenge_tags – a comma-separated list of tags to search challenges for
limit – the limit to the number of results returned in the response. Default is 10
page – used in conjunction with the limit parameter to page through X number of responses. Default is 0.

Returns

the API response from the GET request

get_virtual_challenge_by_id(challenge_id)¶

Method to retrieve an existing virtual challenge

Parameters: challenge_id – the ID corresponding to the virtual challenge
Returns: the API response from the GET request

static is_challenge_model(input_object)¶

Method to determine whether user input is a valid challenge model

Parameters: input_object – the user’s input to check
Returns: True if instance of model

rebuild_challenge(challenge_id, remove_unmatched=False, skip_snapshot=False)¶

Rebuild the challenge by re-creating the tasks from the task data source

Parameters

challenge_id – the ID corresponding to the challenge
remove_unmatched – Used to remove incomplete tasks that have been addressed externally since the last rebuild, assuming the source data represents all tasks outstanding. If set to true, all existing tasks in CREATED or SKIPPED status (only) will be removed prior to rebuilding with the assumption that they will be recreated if they still appear in the updated source data. If set to false, unmatched existing tasks are simply left as-is. Default: False
skip_snapshot – Whether to skip recording a snapshot before proceeding. Default: False

reset_task_instructions(challenge_id)¶

Method to reset all the task instructions so that they revert to the challenge instructions

Parameters: challenge_id – the ID corresponding to the challenge
Returns: the API response from the PUT request

update_challenge(challenge_id, data)¶

Method to update a challenge by using the corresponding challenge ID

Parameters

challenge_id – the ID corresponding to the challenge
data – a JSON input containing challenge details

Returns

the API response from the PUT request

update_task_priorities(challenge_id)¶

Method to update all the task priorities for a given challenge based on the priority rules in the challenge

Parameters: challenge_id – the ID corresponding to the challenge
Returns: the API response from the PUT request

Module: task¶

This module contains the methods that the user will use directly to interact with MapRoulette tasks

class maproulette.api.task.Task(config)¶

Bases: maproulette.api.maproulette_server.MapRouletteServer

Class to handle the task-related API requests

static batch_generator(input_list, chunk_size)¶

Method to yield successive n-sized chunks from input_list

Parameters

input_list – the list to break into chunks
chunk_size (int) – the number of list items to include per chunk

Returns

an iterator for the n-sized chunks of the input_list

create_task(data)¶

Method to create a single task using an input JSON of task details.

Parameters: data – a JSON input containing task details
Returns: the API response from the POST request

create_tasks(data, batch_size=5000)¶

Method to create a batch of tasks using the specified batch_size.

Parameters

data – a JSON input containing task details
batch_size (int) – the number of tasks to post per API call. The default is 5000.

Returns

the API response from the POST request

delete_task_tags(task_id, tags)¶

Method to delete the supplied tags from a task using the corresponding task ID

Parameters

task_id – the ID corresponding with the task
tags – a comma-separated list of tags to be deleted

Returns

the API response from the DELETE request

get_task_by_id(task_id)¶

“Method to retrieve task information using the corresponding task ID

Parameters: task_id – the ID corresponding with the task
Returns: the API response from the GET request

get_task_comments(task_id)¶

Method to retrieve the comments for a task using the corresponding task ID

Parameters: task_id – the ID corresponding with the task
Returns: the API response from the GET request

get_task_history(task_id)¶

Method to retrieve task history using the corresponding task ID

Parameters: task_id – the ID corresponding with the task
Returns: the API response from the GET request

get_task_tags(task_id)¶

Method to retrieve the tags for a task using the corresponding task ID

Parameters: task_id – the ID corresponding with the task
Returns: the API response from the GET request

get_tasks_by_bounding_box(left, bottom, right, top, limit=10000, page=0, exclude_locked='false', order='ASC', include_total='false', include_geometries='false', include_tags='false')¶

Method to retrieve tasks by a bounding box defined by left, bottom, right, and top lat/long values

Parameters

left – the minimum latitude of the bounding box
bottom – the minimum longitude of the bounding box
right – the maximum latitude of the bounding box
top – the maximum longitude of the bounding box
limit – the limit to the number of results returned in the response. Default is 10,000.
page – used in conjunction with the limit parameter to page through X number of responses. Default is 0.
exclude_locked – boolean indicating whether to exclude locked tasks. Default is ‘false’.
order – the order of the results. Default is ‘ASC’
include_total – whether to include total or not. Default is ‘false’
include_geometries – whether to include geometries or not. Default is ‘false’
include_tags – whether to include tags or not. Default is ‘false’

Returns

the API response from the PUT request

get_tasks_by_tags(tags, limit=10, page=0)¶

Method to retrieve tasks that have the specified tags

Parameters

tags – a comma-separated list of tags to be searched for
limit – the limit to the number of results returned in the response. Default is 10
page – used in conjunction with the limit parameter to page through X number of responses. Default is 0.

Returns

the API response from the GET request

static is_task_model(input_object)¶

Method to determine whether user input is a valid task model

Parameters: input_object – the user’s input to check
Returns: True if instance of model

update_task_status(task_id, status, comment=None, tags=None, request_review=None, completion_responses=None)¶

Method to update a task’s status to one of the following: 0 - Created, 1 - Fixed, 2 - False Positive, 3 - Skipped, 4 - Deleted, 5 - Already Fixed, 6 - Too Hard.

Parameters

task_id – the ID corresponding with the task
status – the status to update the task to
comment – optional comment that is provided by the user when setting the status
tags – optional tags to associate with this task
request_review – optional boolean indicating if a review is requested on this task
completion_responses – optional key/value JSON to be stored within this task

Returns

the API response from the PUT request

update_task_tags(task_id, tags)¶

Method to update a task’s tags using the supplied tags and corresponding task ID

Parameters

task_id – the ID corresponding with the task
tags – a comma-separated list of tags to be updated. If empty all tags will be removed.

Returns

the API response from the GET request

update_tasks(data)¶

Method to update a batch of tasks

Parameters: data – a JSON input containing task details
Returns: the API response from the PUT request

Module: user¶

This module contains the methods that the user will use directly to interact with MapRoulette users

class maproulette.api.user.User(config)¶

Bases: maproulette.api.maproulette_server.MapRouletteServer

Class to handle the user-related API requests

add_user_list_to_project(user_ids, project_id, group_type, is_osm_user_id='true')¶

Method to add a user to a project group

Parameters

user_ids – a list of user IDs to add to the specified project group. IDs should be integers.
project_id – the ID of the project
group_type – the group type to add the user to (1 - Admin, 2 - Write, 3 - Read)
is_osm_user_id – whether or not the specified user ID is an OSM user ID. Default is ‘false’.

Returns

the API response from the PUT request

add_user_to_project(user_id, project_id, group_type, is_osm_user_id='true')¶

Method to add a user to a project group

Parameters

user_id – the user ID to add to the specified project group
project_id – the ID of the project
group_type – the group type to add the user to (1 - Admin, 2 - Write, 3 - Read)
is_osm_user_id – whether or not the specified user ID is an OSM user ID. Default is ‘false’.

Returns

the API response from the POST request

find_user_by_username(username, limit=10, page=0)¶

Method to search for a user based on a specific username

Parameters

username – the username to search for.
limit – the limit to the number of results returned in the response. Default is 10
page – used in conjunction with the limit parameter to page through X number of responses. Default is 0.

Returns

the API response from the GET request

Module: configuration¶

This module contains the basic configuration object that is used to communicate with the MapRoulette API.

class maproulette.api.configuration.Configuration(hostname='maproulette.org', protocol='https', api_version='/api/v2', api_key=None, certs=None, verify=True)¶

Configuration object that specifies how to connect to the MapRoulette server.

Parameters

hostname (str, optional) – Optional parameter to specify the hostname of the MapRoulette instance being addressed. Do not include the protocol (https, http). Default value is ‘maproulette.org’.
protocol (str, optional) – Optional parameter to specify the protocol to use for the connection to the MapRoulette instance being addressed such as https or http. Default value is ‘https’.
api_version (str, optional) – Optional parameter to specify the API version to use. The default is ‘/api/v2’.
api_key (str, optional) – Optional parameter to pass the user-specific API key. This key is necessary for some actions.
certs (str or tuple, optional) – Optional parameter to pass the client-side certificate and key if necessary to make connection with the MapRoulette instance being addressed. Can be either a tuple containing the cert and key file paths (in that order) or a string representing the filepath to both the cert and key stored in a single file.
verify (bool, optional) – Optional parameter to specify whether to verify SSL certificates for HTTPS requests. Default is True.

__init__(hostname='maproulette.org', protocol='https', api_version='/api/v2', api_key=None, certs=None, verify=True)¶: Initialize self. See help(type(self)) for accurate signature.

__weakref__¶: list of weak references to the object (if defined)