# 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:
```bash
pip install --upgrade surge-api
```
### Requirements
* Python 3.6+
## Usage
Documentation and examples are available [here](https://app.surgehq.ai/docs/api#).
### 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:
```python
import surge
surge.api_key = "YOUR API KEY"
```
Or set the API key as an environment variable:
```bash
export SURGE_API_KEY=<YOUR API KEY>
```
### Downloading project results
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.
```python
# 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")
# Download the results for that project
results = project.download_json()
# Alternatively, download the results to a file
project.save_report("export_csv", "results.csv")
```
### Creating projects
If you have a blueprint, 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.
```python
# List blueprint projects
blueprint_projects = surge.Project.list_blueprints()
blueprint = blueprint_projects[0]
# Create a project from a blueprint
project = surge.Project.create("My Labeling Project (July 2023 Batch)", template_id=blueprint.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"
}])
```
### Creating 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.
```python
# 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 |
```python
# 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:
```bash
pip install pytest
```
To run tests from the command line:
```bash
# 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
```
Raw data
{
"_id": null,
"home_page": "https://github.com/surge-ai/surge-python",
"name": "surge-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Surge",
"author_email": "team@surgehq.ai",
"download_url": null,
"platform": null,
"description": "# Surge Python SDK\n\nThe Surge Python SDK provides convenient access to the Surge API from applications written in the Python language.\n\n## Installation\n\nInstall this package by using pip:\n\n```bash\npip install --upgrade surge-api\n```\n\n### Requirements\n\n* Python 3.6+\n\n## Usage\n\nDocumentation and examples are available [here](https://app.surgehq.ai/docs/api#).\n\n### Authentication\n\nThe 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:\n\n```python\nimport surge\nsurge.api_key = \"YOUR API KEY\"\n```\nOr set the API key as an environment variable:\n\n```bash\nexport SURGE_API_KEY=<YOUR API KEY>\n```\n\n### Downloading project results\n\nOnce 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.\n\n```python\n# List your Projects\nprojects = surge.Project.list()\n\n# Print the name of the first Project\nprint(projects[0].name)\n\n# Retrieve a specific Project\nproject = surge.Project.retrieve(\"076d207b-c207-41ca-b73a-5822fe2248ab\")\n\n# Download the results for that project\nresults = project.download_json()\n\n# Alternatively, download the results to a file\nproject.save_report(\"export_csv\", \"results.csv\")\n```\n\n### Creating projects\n\nIf you have a blueprint, you can use it as a template to get a new batch of data annotated.\nYou can add new labeling tasks from a CSV or with a list of dictionaries.\n\n```python\n# List blueprint projects\nblueprint_projects = surge.Project.list_blueprints()\nblueprint = blueprint_projects[0]\n\n# Create a project from a blueprint\nproject = surge.Project.create(\"My Labeling Project (July 2023 Batch)\", template_id=blueprint.id)\n\n# Add data from a CSV file\nproject.create_tasks_from_csv('my_data.csv')\n\n# Or add data directly\ntasks = project.create_tasks([{\n \"company\": \"Surge\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\"\n}])\n```\n\n### Creating tasks\n\nYou can create new Tasks for a project, list all of the Tasks in a given project, or retrieve a specific Task given its ID.\n\n```python\n# Create Tasks for the new Project\ntasks_data = [{\"id\": 1, \"company\": \"Surge AI\"}, {\"id\": 2, \"company\":\"Twitch TV\"}]\ntasks = project.create_tasks(tasks_data)\n\n# List all Tasks in the Project\nall_tasks = project.list_tasks()\n\n# Retrieve a specific Task\ntask = surge.Task.retrieve(task_id = \"eaa44610-c8f6-4480-b746-28b6c8defd4d\")\n\n# Print the fields of that Task\nprint(task.fields)\n```\n\nYou 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.\n\n| id | company |\n| :--- | :----: |\n| 1 | Surge AI |\n| 2 | Twitch TV |\n\n```python\n# Create Tasks in bulk via CSV file\nfile_path = \"./companies_to_classify.csv\"\ntasks = project.create_tasks_from_csv(file_path)\n```\n\n\n## Development\n\nThe test suite depends on `pytest`, which you can install using pip:\n\n```bash\npip install pytest\n```\n\nTo run tests from the command line:\n\n```bash\n# Run all tests\npytest\n\n# Run tests in a specific file\npytest tests/test_projects.py\n\n# Run a specific test\npytest tests/test_projects.py::test_init_complete\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Surge Python SDK",
"version": "1.5.18",
"project_urls": {
"Homepage": "https://github.com/surge-ai/surge-python"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3c5e59c3723f2fbc05ed51d498e28fd15b373bf1ef05e64fc4d0a38bb0536303",
"md5": "32364222ecc98c2c1e43058c89cf92d4",
"sha256": "a364f3859c3d1030982d5e1c7346c6458d5c40edf7a9b8e0640f32d48fd6bc10"
},
"downloads": -1,
"filename": "surge_api-1.5.18-py3-none-any.whl",
"has_sig": false,
"md5_digest": "32364222ecc98c2c1e43058c89cf92d4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 20306,
"upload_time": "2025-10-22T05:29:46",
"upload_time_iso_8601": "2025-10-22T05:29:46.526356Z",
"url": "https://files.pythonhosted.org/packages/3c/5e/59c3723f2fbc05ed51d498e28fd15b373bf1ef05e64fc4d0a38bb0536303/surge_api-1.5.18-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 05:29:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "surge-ai",
"github_project": "surge-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"requirements": [
{
"name": "certifi",
"specs": [
[
"==",
"2025.10.5"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.4.3"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.10"
]
]
},
{
"name": "iniconfig",
"specs": [
[
"==",
"2.1.0"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"25.0"
]
]
},
{
"name": "pluggy",
"specs": [
[
"==",
"1.6.0"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"8.4.2"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.9.0.post0"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.32.5"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.17.0"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"2.5.0"
]
]
}
],
"lcname": "surge-api"
}
JSON
