# ExportComments API for Python
This is the official Python client for the ExportComments API v3, designed to facilitate the integration of advanced language processing capabilities into Python applications. Utilize this client to efficiently build and manage machine learning models for natural language processing directly from your Python environment.
## Installation
To integrate the ExportComments library into your project, you can easily install it using pip:
```bash
pip install exportcomments
```
Alternatively, if you prefer to install from source or want to contribute to the project, clone the repository and install it manually:
```bash
git clone https://github.com/exportcomments/exportcomments-python.git
cd exportcomments-python
pip install -r requirements.txt
python setup.py install
```
## Usage
To begin utilizing the ExportComments API, you must first instantiate the ExportComments client with your API key, which is available on your ExportComments account.
```python
from exportcomments import ExportComments
# Initialize the client with your API key
ex = ExportComments('<YOUR API TOKEN HERE>')
```
Start an export process by submitting a URL to the API. This places the URL in the processing queue. Please note, the queue is limited to 5 concurrent requests.
```python
response = ex.jobs.create(
url='https://www.instagram.com/p/1234567',
options={'replies': True, 'limit': 100}
)
```
To monitor the status of your export, retrieve the GUID from the initial response and query the export's status.
```python
guid = response.body['guid']
response = ex.jobs.check(guid=guid)
```
The status of the export can be checked as follows, with potential statuses including "queueing", "error", "done", or "progress":
```python
status = response.body['status']
```
### Listing Your Jobs
You can list your existing jobs with pagination:
```python
response = ex.jobs.list(page=1, limit=10)
jobs = response.body
```
### Job Options
The new API supports various options that can be passed when creating a job:
```python
response = ex.jobs.create(
url='https://www.instagram.com/p/1234567',
options={
'replies': True,
'limit': 500,
'minTimestamp': 1622505600,
'maxTimestamp': 1625097600,
'vpn': 'Norway',
'cookies': {
'sessionid': 'your_session_id'
}
}
)
```
### Backward Compatibility
For backward compatibility, you can still use `ex.exports` which will work the same as `ex.jobs`:
```python
# This still works for backward compatibility
response = ex.exports.create(
url='https://www.instagram.com/p/1234567',
options={'replies': True}
)
```
### Handling Errors
The API might raise exceptions during endpoint calls. Below is an example of how to catch and handle these exceptions:
```python
from exportcomments.exceptions import ExportCommentsException
try:
response = ex.jobs.create(
url='https://www.instagram.com/p/1234567',
options={'replies': True}
)
except ExportCommentsException as e:
# Handles all exceptions derived from ExportCommentsException
print(e)
```
The following table outlines the available exceptions and their descriptions:
| Exception Class | Description |
| ---------------------------- | ----------------------------------------------------------------------------------------------- |
| `ExportCommentsException` | The base class for all exceptions listed below. |
| `RequestParamsError` | Indicates an invalid parameter was sent. Check the message or response object for details. |
| `AuthenticationError` | Occurs when authentication fails, typically due to an invalid API token. |
| `ForbiddenError` | Indicates insufficient permissions for the requested action on the specified resource. |
| `PlanRateLimitError` | Triggered by too many requests in a minute, according to your subscription plan's limits. |
| `ConcurrencyRateLimitError` | Triggered by too many requests in a second, indicating a rate limit on concurrent requests. |
You can download the resulting Excel file by using requests.get. Here's a good example:
```python
import requests
import pkg_resources
# download_link is retrieved from the .check method
download_link = response.body['download_link']
# Set headers for download
headers = {
'X-AUTH-TOKEN': "Your API Token",
'Content-Type': 'application/json',
'User-Agent': 'python-sdk-{}'.format(pkg_resources.get_distribution('exportcomments').version),
}
# Get the excel
response = requests.get(download_link, headers=headers)
# Handle the excel if it is available
if response.status_code == 200:
# Create an excel and save it
with open("result.xlsx", "wb") as output:
output.write(response.content)
print(f"[SUCCESSFUL DOWNLOAD] File Downloaded: {download_link}")
else:
print(f"[FAILED TO DOWNLOAD] Status Code: {response.status_code}")
```
## Development
If you want to contribute to this project, install the development dependencies:
```bash
pip install -r requirements.txt
```
Run tests:
```bash
pytest
```
## Code example
Here's a comprehensive example demonstrating a typical workflow when only using 1 URL:
```python
import requests
import pkg_resources
from exportcomments import ExportComments, ExportCommentsException
import time
import sys
ex = ExportComments('<YOUR API TOKEN HERE>')
def get_response(guid):
while True:
response = ex.jobs.check(guid=guid)
status = response.body['status']
if status == 'done':
break
elif status == 'error':
print("Error generating your file.")
sys.exit()
time.sleep(20)
download_link = response.body['download_link']
headers = {
'X-AUTH-TOKEN': "Your API Token",
'Content-Type': 'application/json',
'User-Agent': 'python-sdk-{}'.format(pkg_resources.get_distribution('exportcomments').version),
}
response = requests.get(download_link, headers=headers)
if response.status_code == 200:
with open("result.xlsx", "wb") as output:
output.write(response.content)
print(f"[SUCCESSFUL DOWNLOAD] File Downloaded: {download_link}")
else:
print(f"[FAILED TO DOWNLOAD] Status Code: {response.status_code}")
if __name__ == '__main__':
try:
response = ex.jobs.create(
url='https://www.instagram.com/p/1234567',
options={'replies': True, 'limit': 100}
)
except ExportCommentsException as e:
print(e)
sys.exit()
guid = response.body['guid']
get_response(guid)
```
## API v3 Changes
This version (2.0.0) introduces breaking changes to support API v3:
- **New method names**: Use `ex.jobs` instead of `ex.exports` (backward compatibility maintained)
- **Updated parameters**: The `create()` method now uses an `options` parameter instead of individual parameters
- **Response structure**: Responses now have a simplified structure with direct access to properties
- **New endpoints**: Updated to use `/api/v3/` endpoints
For more information about the API, visit [ExportComments API Documentation](https://exportcomments.com/api).
Raw data
{
"_id": null,
"home_page": "https://github.com/exportcomments/exportcomments-python",
"name": "exportcomments",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "exportcomments, export social media comments, python, api v3",
"author": "ExportComments",
"author_email": "sales@exportcomments.com",
"download_url": "https://files.pythonhosted.org/packages/30/a0/424040b102d686cb29e756640855f861a778e4b072eef9fba6c8b593bb65/exportcomments-2.0.0.tar.gz",
"platform": null,
"description": "# ExportComments API for Python\n\nThis is the official Python client for the ExportComments API v3, designed to facilitate the integration of advanced language processing capabilities into Python applications. Utilize this client to efficiently build and manage machine learning models for natural language processing directly from your Python environment.\n\n## Installation\n\nTo integrate the ExportComments library into your project, you can easily install it using pip:\n\n```bash\npip install exportcomments\n```\n\nAlternatively, if you prefer to install from source or want to contribute to the project, clone the repository and install it manually:\n\n```bash\ngit clone https://github.com/exportcomments/exportcomments-python.git\ncd exportcomments-python\npip install -r requirements.txt\npython setup.py install\n```\n\n## Usage\n\nTo begin utilizing the ExportComments API, you must first instantiate the ExportComments client with your API key, which is available on your ExportComments account.\n\n```python\nfrom exportcomments import ExportComments\n\n# Initialize the client with your API key\nex = ExportComments('<YOUR API TOKEN HERE>')\n```\n\nStart an export process by submitting a URL to the API. This places the URL in the processing queue. Please note, the queue is limited to 5 concurrent requests.\n\n```python\nresponse = ex.jobs.create(\n url='https://www.instagram.com/p/1234567',\n options={'replies': True, 'limit': 100}\n)\n```\n\nTo monitor the status of your export, retrieve the GUID from the initial response and query the export's status.\n\n```python\nguid = response.body['guid']\nresponse = ex.jobs.check(guid=guid)\n```\n\nThe status of the export can be checked as follows, with potential statuses including \"queueing\", \"error\", \"done\", or \"progress\":\n\n```python\nstatus = response.body['status']\n```\n\n### Listing Your Jobs\n\nYou can list your existing jobs with pagination:\n\n```python\nresponse = ex.jobs.list(page=1, limit=10)\njobs = response.body\n```\n\n### Job Options\n\nThe new API supports various options that can be passed when creating a job:\n\n```python\nresponse = ex.jobs.create(\n url='https://www.instagram.com/p/1234567',\n options={\n 'replies': True,\n 'limit': 500,\n 'minTimestamp': 1622505600,\n 'maxTimestamp': 1625097600,\n 'vpn': 'Norway',\n 'cookies': {\n 'sessionid': 'your_session_id'\n }\n }\n)\n```\n\n### Backward Compatibility\n\nFor backward compatibility, you can still use `ex.exports` which will work the same as `ex.jobs`:\n\n```python\n# This still works for backward compatibility\nresponse = ex.exports.create(\n url='https://www.instagram.com/p/1234567',\n options={'replies': True}\n)\n```\n\n### Handling Errors\n\nThe API might raise exceptions during endpoint calls. Below is an example of how to catch and handle these exceptions:\n\n```python\nfrom exportcomments.exceptions import ExportCommentsException\n\ntry:\n response = ex.jobs.create(\n url='https://www.instagram.com/p/1234567',\n options={'replies': True}\n )\nexcept ExportCommentsException as e:\n # Handles all exceptions derived from ExportCommentsException\n print(e)\n```\n\nThe following table outlines the available exceptions and their descriptions:\n\n| Exception Class | Description |\n| ---------------------------- | ----------------------------------------------------------------------------------------------- |\n| `ExportCommentsException` | The base class for all exceptions listed below. |\n| `RequestParamsError` | Indicates an invalid parameter was sent. Check the message or response object for details. |\n| `AuthenticationError` | Occurs when authentication fails, typically due to an invalid API token. |\n| `ForbiddenError` | Indicates insufficient permissions for the requested action on the specified resource. |\n| `PlanRateLimitError` | Triggered by too many requests in a minute, according to your subscription plan's limits. |\n| `ConcurrencyRateLimitError` | Triggered by too many requests in a second, indicating a rate limit on concurrent requests. |\n\nYou can download the resulting Excel file by using requests.get. Here's a good example:\n```python\nimport requests\nimport pkg_resources\n\n# download_link is retrieved from the .check method\ndownload_link = response.body['download_link']\n\n# Set headers for download\nheaders = {\n 'X-AUTH-TOKEN': \"Your API Token\",\n 'Content-Type': 'application/json',\n 'User-Agent': 'python-sdk-{}'.format(pkg_resources.get_distribution('exportcomments').version),\n}\n\n# Get the excel\nresponse = requests.get(download_link, headers=headers)\n\n# Handle the excel if it is available\nif response.status_code == 200:\n # Create an excel and save it\n with open(\"result.xlsx\", \"wb\") as output:\n output.write(response.content)\n\n print(f\"[SUCCESSFUL DOWNLOAD] File Downloaded: {download_link}\")\nelse:\n print(f\"[FAILED TO DOWNLOAD] Status Code: {response.status_code}\")\n```\n\n## Development\n\nIf you want to contribute to this project, install the development dependencies:\n\n```bash\npip install -r requirements.txt\n```\n\nRun tests:\n```bash\npytest\n```\n\n## Code example\nHere's a comprehensive example demonstrating a typical workflow when only using 1 URL:\n```python\nimport requests\nimport pkg_resources\nfrom exportcomments import ExportComments, ExportCommentsException\nimport time\nimport sys\n\nex = ExportComments('<YOUR API TOKEN HERE>')\n\ndef get_response(guid):\n while True:\n response = ex.jobs.check(guid=guid)\n status = response.body['status']\n\n if status == 'done':\n break\n elif status == 'error':\n print(\"Error generating your file.\")\n sys.exit()\n\n time.sleep(20)\n\n download_link = response.body['download_link']\n headers = {\n 'X-AUTH-TOKEN': \"Your API Token\",\n 'Content-Type': 'application/json',\n 'User-Agent': 'python-sdk-{}'.format(pkg_resources.get_distribution('exportcomments').version),\n }\n\n response = requests.get(download_link, headers=headers)\n\n if response.status_code == 200:\n with open(\"result.xlsx\", \"wb\") as output:\n output.write(response.content)\n print(f\"[SUCCESSFUL DOWNLOAD] File Downloaded: {download_link}\")\n else:\n print(f\"[FAILED TO DOWNLOAD] Status Code: {response.status_code}\")\n\nif __name__ == '__main__':\n try:\n response = ex.jobs.create(\n url='https://www.instagram.com/p/1234567',\n options={'replies': True, 'limit': 100}\n )\n except ExportCommentsException as e:\n print(e)\n sys.exit()\n\n guid = response.body['guid']\n get_response(guid)\n```\n\n## API v3 Changes\n\nThis version (2.0.0) introduces breaking changes to support API v3:\n\n- **New method names**: Use `ex.jobs` instead of `ex.exports` (backward compatibility maintained)\n- **Updated parameters**: The `create()` method now uses an `options` parameter instead of individual parameters\n- **Response structure**: Responses now have a simplified structure with direct access to properties\n- **New endpoints**: Updated to use `/api/v3/` endpoints\n\nFor more information about the API, visit [ExportComments API Documentation](https://exportcomments.com/api).\n",
"bugtrack_url": null,
"license": null,
"summary": "Official Python client for the ExportComments API v3",
"version": "2.0.0",
"project_urls": {
"Download": "https://github.com/exportcomments/exportcomments-python/tarball/v2.0.0",
"Homepage": "https://github.com/exportcomments/exportcomments-python"
},
"split_keywords": [
"exportcomments",
" export social media comments",
" python",
" api v3"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "19310962c24f95e24250dbb19c7221972552513ca6c061c18a95027306d63b68",
"md5": "afc848792b5d5f9a1ab6d215bd9c6f45",
"sha256": "7a3c1315b81ccb254766268ea3cb1ab8126e7d9c2457b188ca64e1d4c0d73589"
},
"downloads": -1,
"filename": "exportcomments-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "afc848792b5d5f9a1ab6d215bd9c6f45",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 10178,
"upload_time": "2025-07-09T18:35:37",
"upload_time_iso_8601": "2025-07-09T18:35:37.519513Z",
"url": "https://files.pythonhosted.org/packages/19/31/0962c24f95e24250dbb19c7221972552513ca6c061c18a95027306d63b68/exportcomments-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "30a0424040b102d686cb29e756640855f861a778e4b072eef9fba6c8b593bb65",
"md5": "b9ad7684d11ea04965053a5f412e9c99",
"sha256": "80d666b1c0b358fefb730420df9deb9b97cd15c67ef023c2e3553c5f1c256a9c"
},
"downloads": -1,
"filename": "exportcomments-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "b9ad7684d11ea04965053a5f412e9c99",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10741,
"upload_time": "2025-07-09T18:35:38",
"upload_time_iso_8601": "2025-07-09T18:35:38.335471Z",
"url": "https://files.pythonhosted.org/packages/30/a0/424040b102d686cb29e756640855f861a778e4b072eef9fba6c8b593bb65/exportcomments-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 18:35:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "exportcomments",
"github_project": "exportcomments-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.8.1"
]
]
},
{
"name": "six",
"specs": [
[
">=",
"1.10.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"6.0.0"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
">=",
"2.10.0"
]
]
},
{
"name": "flake8",
"specs": [
[
">=",
"3.8.0"
]
]
},
{
"name": "black",
"specs": [
[
">=",
"21.0.0"
]
]
},
{
"name": "twine",
"specs": [
[
">=",
"3.4.0"
]
]
}
],
"lcname": "exportcomments"
}
JSON
