Skip to content

README.md

Latest commit

 

History

History
196 lines (146 loc) · 5.1 KB

README.md

File metadata and controls

196 lines (146 loc) · 5.1 KB

ExportComments API for Python

This is the official Python client for the ExportComments API v3. Export comments and reviews from 40+ social media and review platforms including Instagram, YouTube, TikTok, Facebook, Twitter/X, Reddit, Trustpilot, Amazon, and more.

Installation

pip install exportcomments

Or install from source:

git clone https://github.com/exportcomments/exportcomments-python.git
cd exportcomments-python
pip install -r requirements.txt
python setup.py install

Usage

Initialize the client with your API token (get it at app.exportcomments.com/user/api):

from exportcomments import ExportComments

ex = ExportComments('<YOUR API TOKEN HERE>')

Check API Connectivity

result = ex.ping()
print(result)  # {'message': 'pong'}

Create an Export Job

Start an export by submitting a URL. The queue is limited to 5 concurrent requests.

response = ex.jobs.create(
    url='https://www.instagram.com/p/1234567',
    options={'replies': True, 'limit': 100}
)
guid = response.body['guid']

Check Job Status

response = ex.jobs.check(guid=guid)
status = response.body['status']  # 'queueing', 'progress', 'done', or 'error'

List Jobs

response = ex.jobs.list(page=1, limit=10)
jobs = response.body

Download Export File

Download the Excel/CSV file for a completed job:

# Downloads and saves the file, returns the file path
file_path = ex.jobs.download(guid=guid)
print(f"Saved to: {file_path}")

# Or specify a custom output path
file_path = ex.jobs.download(guid=guid, output_path='my_export.xlsx')

Download Raw JSON Data

Get the exported data as parsed JSON:

data = ex.jobs.download_json(guid=guid)
for comment in data:
    print(comment['message'], comment['author_name'])

Job Options

The API supports various options when creating a job:

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, ex.exports still works as an alias for ex.jobs:

response = ex.exports.create(
    url='https://www.instagram.com/p/1234567',
    options={'replies': True}
)

Handling Errors

from exportcomments.exceptions import ExportCommentsException

try:
    response = ex.jobs.create(
        url='https://www.instagram.com/p/1234567',
        options={'replies': True}
    )
except ExportCommentsException as e:
    print(e)
Exception Class Description
ExportCommentsException Base class for all exceptions.
RequestParamsError Invalid parameter sent. Check the message or response object for details.
AuthenticationError Authentication failed, typically due to an invalid API token.
ForbiddenError Insufficient permissions for the requested action.
PlanRateLimitError Too many requests per minute according to your plan's limits.
ConcurrencyRateLimitError Too many requests per second.

Complete Example

from exportcomments import ExportComments
from exportcomments.exceptions import ExportCommentsException
import time
import sys

ex = ExportComments('<YOUR API TOKEN HERE>')

# Verify connectivity
print(ex.ping())

# Create export
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']

# Poll until done
while True:
    response = ex.jobs.check(guid=guid)
    status = response.body['status']

    if status == 'done':
        break
    elif status == 'error':
        print("Error:", response.body.get('error'))
        sys.exit()

    time.sleep(5)

# Download the file
file_path = ex.jobs.download(guid=guid)
print(f"Downloaded: {file_path}")

# Or get raw JSON data
data = ex.jobs.download_json(guid=guid)
print(f"Got {len(data)} comments")

API v3 Changes

Version 2.0.0 supports API v3:

  • New method names: Use ex.jobs instead of ex.exports (backward compatibility maintained)
  • Updated parameters: create() uses an options dict instead of individual parameters
  • New methods: ping(), download(), download_json()
  • Endpoints: Uses /api/v3/ endpoints

For more information, visit ExportComments API Documentation.