surge-api 1.5.11

Surge Python SDK

Surge Python SDK

The Surge Python SDK provides convenient access to the Surge API from applications written in the Python language.

Installation

Install this package by using pip:

pip install --upgrade surge-api

Requirements

• Python 3.6+

Usage

Documentation and and examples are available here.

Authentication

The library needs to be configured with your account's API key which is available in your Surge Profile. Set surge.api_key to its value:

import surge
surge.api_key = "YOUR API KEY"

Or set the API key as an environment variable:

export SURGE_API_KEY=<YOUR API KEY>

Projects

Once the API key has been set, you can list all of the Projects under your Surge account or retrieve a specific Project by its ID.

# List your Projects
projects = surge.Project.list()

# Print the name of the first Project
print(projects[0].name)

# Retrieve a specific Project
project = surge.Project.retrieve("076d207b-c207-41ca-b73a-5822fe2248ab")

# print the number of tasks in that Project
print(project.num_tasks)

If you have an existing project, you can use it as a template to get a new batch of data annotated. You can add new labeling tasks from a CSV or with a list of dictionaries.

# Create a project from a template
template_project_id = "076d207b-c207-41ca-b73a-5822fe2248ab"
project = surge.Project.create("My Labeling Project (July 2023 Batch)", template_id=template_project_id)

# Add data from a CSV file
project.create_tasks_from_csv('my_data.csv')

# Or add data directly
tasks = project.create_tasks([{
    "company": "Surge",
    "city": "San Francisco",
    "state": "CA"
}])

# Launch the project to send it to the Surge workforce
project.launch()

Or you can create a new project from scratch by creating your own template and list of Question:

from surge.questions import FreeResponseQuestion, MultipleChoiceQuestion, CheckboxQuestion

# Create a new Project
free_response_q = FreeResponseQuestion(
    text="What is this company's website?",
    label="")

multiple_choice_q = MultipleChoiceQuestion(
    text="What category does this company belong to?",
    label="Category",
    options=["Tech", "Sports", "Gaming"])

checkbox_q = CheckboxQuestion(
    text="Check all the social media accounts this company has",
    label="",
    options=["Facebook", "Twitter", "Pinterest", "Google+"])

fields_template_text = '''
    <p>Company: {{company}}</p>
'''

project = surge.Project.create(
    name="Categorize this company",
    instructions="You will be asked to categorize a company.",
    questions=[free_response_q, multiple_choice_q, checkbox_q],
    callback_url="https://customer-callback-url/",
    fields_template=fields_template_text,
    num_workers_per_task=3)

Tasks

You can create new Tasks for a project, list all of the Tasks in a given project, or retrieve a specific Task given its ID.

# Create Tasks for the new Project
tasks_data = [{"id": 1, "company": "Surge AI"}, {"id": 2, "company":"Twitch TV"}]
tasks = project.create_tasks(tasks_data)

# List all Tasks in the Project
all_tasks = project.list_tasks()

# Retrieve a specific Task
task = surge.Task.retrieve(task_id = "eaa44610-c8f6-4480-b746-28b6c8defd4d")

# Print the fields of that Task
print(task.fields)

You can also create Tasks in bulk by uploading a local CSV file. The header of the CSV file must specify the fields that are used in your Tasks.

id	company
1	Surge AI
2	Twitch TV

# Create Tasks in bulk via CSV file
file_path = "./companies_to_classify.csv"
tasks = project.create_tasks_from_csv(file_path)

Development

The test suite depends on pytest, which you can install using pip:

pip install pytest

To run tests from the command line:

# Run all tests
pytest

# Run tests in a specific file
pytest tests/test_projects.py

# Run a specific test
pytest tests/test_projects.py::test_init_complete