ex_cogmint v0.0.6 ExCogmint

Documentation for ExCogmint, the Elixir client library which is a thin wrapper around the Cogmint.com API.

Cogmint.com is a crowdsourcing / micro task website.

Example configuration (see ExCogmint.Config for more details)

In your app's config.exs file:

  config :ex_cogmint,
    cogmint_api_key: System.get_env("COGMINT_API_KEY"),
    callback_url: System.get_env("COGMINT_CALLBACK_URL")

cogmint_api_key: required. The API key for your Cogmint account.

callback_url: optional. Sets the default callback_url on each task created. If your app has a single endpoint for receiving all callbacks from Cogmint it is recommended to set this, or else you need to set it individually on every task creation API call.

Link to this section Summary

Functions

Add a new task to an existing project.

Retrieve information about a project.

Gets information on a task ("worktask"). Returns the task, including associated submissions as a list of strings.

Link to this section Functions

Link to this function

add_task!(project_uuid, map)

Add a new task to an existing project.

Project_uuid is the project's ID for which you wish to add a new microtask.

The second argument is a map of substitutions you wish to make to the default project task template in order to create the task.

For example, suppose you have a project asking users to determine if a city is a capital city or not. This project likely has a template that looks something like:

"Is [[city]] a capital city?"

For this project template, we can provide a map replacing the variable city with a value by passing in a map like

%{"city" => "Washington, D.C."}

Resulting in a task created for a worker like:

"Is Washington, D.C. a capital city?"

Examples

ExCogmint.add_task!("1234-12345-1234-12345", %{"city" => "Brasilia"})
ExCogmint.add_task!("abc-123-abc", %{"variable_name_to_replace" => "string inserted"})

Potential Responses:

{:ok,
  %{
      data: %{
        prompt: "Hotdog or not hotdog?",
        task_uuid: "1234-1234-1234",
        reward: 4,
        callback_url: "https://yoururl.com/callbackyouspecify",
        required_submissions: 3,
        submission_count: 3,
        checked_out_at: <datetime>,
        allowed_completion_time_seconds: 3600,
        external_image_url: "https://www.imagehostingurl.com/maybehotdog.png",
        submissions: []
      }
    }
  }

or

{:error, "helpful message"}
Link to this function

get_project!(uuid)

Retrieve information about a project.

Example

ExCogmint.get_project!("39a832c4-6ad0-48ef-9cf3-f251efb124f2")

Example response:

{:ok,
  %{
    data: %{
      allowed_completion_time_seconds: 3600,
      available_task_count: 89,
      average_outstanding_task_reward_cents: 50,
      default_required_submissions: 3,
      default_reward: 50,
      display_name: "Great Display Name",
      display_short_description: "A short description, visible to workers",
      has_published_tasks: true,
      lifetime_payments_to_workers_cents: 15000,
      name: "Test Project (using test key)",
      uuid: "39a832c4-6ad0-48ef-9cf3-f251efb124f2"
    }
  }
}
Link to this function

get_task!(uuid)

Gets information on a task ("worktask"). Returns the task, including associated submissions as a list of strings.

Example response:

%{
    data: %{
      prompt: "Hotdog or not hotdog?",
      task_uuid: "1234-1234-1234",
      reward: 4,
      callback_url: "https://yoururl.com/callbackyouspecify",
      required_submissions: 3,
      submission_count: 3,
      checked_out_at: <datetime>,
      allowed_completion_time_seconds: 3600,
      external_image_url: "https://www.imagehostingurl.com/maybehotdog.png",
      submissions: ["yes", "yes", "yes"]
    }
  }