The Surge Python SDK provides convenient access to the Surge API from applications written in the Python language.
Install this package by using pip:
pip install --upgrade surge-api- Python 3.6+
Documentation and and examples are available here.
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>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?")
multiple_choice_q = MultipleChoiceQuestion(
text="What category does this company belong to?",
options=["Tech", "Sports", "Gaming"])
checkbox_q = CheckboxQuestion(
text="Check all the social media accounts this company has",
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)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)The test suite depends on pytest, which you can install using pip:
pip install pytestTo 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
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent