ScaleAPI for Ruby

A simple ruby wrapper for the Scale HTTP API. Documentation for this API is available here.

This project uses {juwelier} for managing and releasing this gem.

Installation

Add this line to your application's Gemfile:

gem 'scaleapi-ruby'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install scaleapi-ruby

Usage

First, you need to initialize the Scale client:

require 'scale'
scale = Scale.setup api_key: 'YOUR_KEY_GOES_HERE',              # Required
                    callback_key: 'YOUR CALLBACK_KEY_GOES_HERE' # Optional

Check {this}[] for further information.

Tasks

Most of these methods will return a Scale::Resources::Task object, which will contain information about the json response (task_id, status…).

Any parameter available in the documentation can be passed as an argument option with the corresponding type.

The following endpoints for tasks are available:

Create categorization task

Check this for further information.

task = scale.create_categorization_task(
  callback_url: 'http://www.example.com/callback',
  instruction: 'Is this company public or private?',
  attachment_type: 'website',
  attachment: 'http://www.google.com/',
  categories: ['public', 'private']
)

Create transcription task

Check this for further information.

task = scale.create_transcription_task(
  callback_url: 'http://www.example.com/callback',
  instruction: 'Transcribe the given fields. Then for each news item on the page, transcribe the information for the row.',
  attachment_type: 'website',
  attachment: 'http://www.google.com/',
  fields: { title: 'Title of Webpage', top_result: 'Title of the top result' },
  row_fields: { username: 'Username of submitter', comment_count: 'Number of comments' }
)

Create phone call task

Check this for further information.

scale.create_phonecall_task(
  callback_url: 'http://www.example.com/callback',
  instruction: "Call this person and tell me his email address. Ask if he's happy too.",
  phone_number: '5055006865',
  entity_name: 'Alexandr Wang',
  script: 'Hello ! Are you happy today? (pause) One more thing - what is your email address?',
  fields: { email: 'Email Address' },
  choices: ['He is happy', 'He is not happy']
)

Create comparison task

Check this for further information.

scale.create_comparison_task(
  callback_url: 'http://www.example.com/callback',
  instruction: 'Do the objects in these images have the same pattern?',
  attachment_type: 'image',
  choices: ['yes', 'no'],
  attachments: [
    'http://i.ebayimg.com/00/$T2eC16dHJGwFFZKjy5ZjBRfNyMC4Ig~~_32.JPG',
    'http://images.wisegeek.com/checkered-tablecloth.jpg'
  ]
)

Create annotation task

Check this for further information.

scale.create_annotation_task(
  callback_url: 'http://www.example.com/callback',
  instruction: 'Draw a box around each baby cow and big cow.',
  attachment_type: "image",
  attachment: "http://i.imgur.com/v4cBreD.jpg",
  objects_to_annotate: ["baby cow", "big cow"],
  examples: [
    {
      correct: false,
      image: 'http://i.imgur.com/lj6e98s.jpg',
      explanation: 'The boxes are tight and accurate'
    },
    {
      correct: true,
      image: 'http://i.imgur.com/HIrvIDq.jpg',
      explanation: 'The boxes are neither accurate nor complete'
    }
  ]
)

Create data collection task

Check this for further information.

scale.create_data_collection_task(
  callback_url: 'http://www.example.com/callback',
  instruction: 'Find the URL for the hiring page for the company with attached website.',
  attachment_type: 'website',
  attachment: 'https://www.scaleapi.com/',
  fields: {
    hiring_page: 'Hiring Page URL'
  }
)

Retrieve task

Check this for further information.

Retrieve a task given its id.

task = scale.retrieve_task 'asdfasdfasdfasdfasdfasdf'
task.id == 'asdfasdfasdfasdfasdfasdf' # true

Cancel task

Check this for further information.

Cancel a task given its id, only if it's not completed.

task = scale.cancel_task 'asdfasdfasdfasdfasdfasdf'

List tasks

Check this for further information.

Retrieve a list (Array) of all tasks.

tasks = scale.tasks # Scale::Resources::Tasks
tasks.all? { |t| t.is_a? Scale::Resources::Task } # true

Callbacks

This gem allows you to create and parse callback data, so it can be easily used for web applications:

For example, for Ruby on Rails:

# app/controllers/scale_api_controller.rb
class ScaleApiController < ApplicationController
  # POST /scale_api
  def create
    callback = scale.build_callback params, 'task', callback_key: request.headers['scale-callback-auth']
    callback.response # Response content hash (code and result)
    callback.task     # Scale::Resources::Task object
  end
end

Please note that callback validation is optional; omit it if no callback_key was passed to Scale.build builder.

If the validation is enabled, the build_callback method will raise a Scale::GenericError, explaning that the tokens don't match. You can also use valid_callback_key? to test it:

# `scale.callback_key` is 'TEST'
scale.valid_callback_key? 'FAKE' # false, because 'TEST' != 'FAKE'

Error handling

If something went wrong while making API calls, then exceptions will be raised automatically as a Scale::GenericError (or Scale::HttpError) runtime error. For example:

begin
  scale.create_categorization_task instructions: 'Some parameters are missing.'
rescue Scale::HttpError => e
  puts e.code # 400
  puts e.exception # Missing parameter X
  pust e.original_exception # Catched exception
rescue Scale::GenericError => e
  puts e.message # Missing parameter X
end

Custom options

The api initialization accepts the following options:

| Name | Description | Default | | —- | ———– | ——- | | endpoint | Endpoint used in the http requests. | 'https://api.scaleapi.com/v1/' | | api_key | API key used in the http requests. | nil | | callback_key | API key used to validate callback POST requests. | nil | | default_request_params | Default parameters (payload) for the API requests | {} |

For example, default_request_params can be used to always set the same callback_url value:

scale = Scale.setup api_key: 'YOUR_KEY_GOES_HERE',              # Required
                    callback_key: 'YOUR CALLBACK_KEY_GOES_HERE' # Optional
                    default_request_params: {
                      callback_url: 'http://www.example.com/callback'
                    }

# All callback requests will posted be made to http://www.example.com/callback
scale.create_comparison_task(
  instruction: 'Draw a box around each baby cow and big cow.',
  attachment_type: "image",
  attachment: "http://i.imgur.com/v4cBreD.jpg",
  objects_to_annotate: ["baby cow", "big cow"]
)

Development

Clone this repository with:

$ git clone https://github.com/wikiti/scaleapi-ruby
$ cd scaleapi-ruby

Install the current development version as a gem with:

$ rake install

Run tests with:

$ SCALE_API_KEY="your_scale_api_key" rake test

Authors

This project has been developed by:

| Avatar | Name | Nickname | Email | | ——- | ————- | ——— | —————— | | | Daniel Herzog | Wikiti | wikiti.doghound@gmail.com |