## RD Station API Helper
A Python library for interacting with the RD Station API, providing ORM models, authentication, segmentation, contact, and event retrieval, as well as batch and parallel data fetching utilities.
[](https://pypi.org/project/rdstation-api-helper/)
[](https://github.com/machado000/rdstation-api-helper/commits/main)
[](https://github.com/machado000/rdstation-api-helper/issues)
[](https://github.com/machado000/rdstation-api-helper/blob/main/LICENSE)
## Features
- **RD Station API v2 support**: Query segmentations, contacts, leads, and conversion events
- **Batch & Parallel Fetching**: Utilities for efficient data extraction with configurable workers
- **Robust Error Handling**: Comprehensive error handling and retry logic with coordinated barriers
- **Webhook Data Processing**: Fetch and process webhook events from SQL databases
- **PostgreSQL Integration**: Built-in PostgreSQL utilities for data storage and retrieval
- **ORM Models**: SQLAlchemy models for RD Station entities (Segmentation, Contact, Lead, etc.)
- **Logging & Config Utilities**: Easy configuration and logging
- **Type Hints**: Full type hint support for better IDE experience
## Installation
```bash
pip install rdstation-api-helper
```
## Quick Start
### 1. Set up credentials
Create a `secrets/rdstation_secret.json` file with your RD Station API credentials:
```json
{
"RDSTATION_CLIENT_ID": "YOUR_CLIENT_ID",
"RDSTATION_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
"RDSTATION_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN"
}
```
### 2. Basic usage
```python
from rdstation_api_helper import RDStationAPI
# Initialize API client (loads credentials from environment or .env)
client = RDStationAPI()
# Fetch all segmentations
segmentations = client.get_segmentations()
# Fetch contacts for each segmentation
contacts = client.get_segmentation_contacts("segmentations_id")
# Fetch contact data for a specific UUID
status_code, contact_data = client.get_contact_data("contact_uuid")
# Fetch conversion events for a contact
status_code, events = client.get_contact_events("some-contact_uuid")
# Fetch webhook events from database
from rdstation_api_helper.utils import PostgresDB, PgConfig
# Initialize database connection
db = PostgresDB()
# Fetch webhook events within date range
webhook_events = client.get_webhook_events(
start_date="2025-08-01",
end_date="2025-08-28",
engine=db.engine,
table_name="rd_webhook_v1",
api_version="v1"
)
```
## ORM Models
The package provides SQLAlchemy ORM models for RD Station entities, which can be used for database integration.
- `Segmentation`
- `SegmentationContact`
- `Contact`
- `ContactFunnelStatus`
- `ConversionEvents`
- `Lead`
## Database Integration
The library includes PostgreSQL utilities for easy database integration:
```python
from rdstation_api_helper.utils import PostgresDB, PgConfig
# Using environment variables (PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD)
db = PostgresDB()
# Or with custom configuration
config = PgConfig(
host="localhost",
port="5432",
dbname="mydb",
user="myuser",
password="mypass"
)
db = PostgresDB(config=config)
# Save data to database with upsert support
db.save_to_sql(data, Contact, upsert_values=True)
```
## Examples
Check the `examples/` directory for comprehensive usage examples:
- `basic_usage.py` - Simple report extraction
## Parallel & Batch Fetching
The library provides a `parallel_decorator` utility to easily parallelize API calls for batch data fetching. This is used in the following methods of `RDStationAPI`:
- `get_contact_data_parallel(uuids: list[str])`
- `get_contact_events_parallel(uuids: list[str])`
- `get_contact_funnel_status_parallel(uuids: list[str])`
These methods accept a list of UUIDs and fetch the corresponding data in parallel, handling rate limits and transient errors automatically. The decorator coordinates retries for 429/5xx/network errors and ensures each result is tagged with its UUID.
### Usage Example
```python
from rdstation_api_helper import RDStationAPI
client = RDStationAPI()
uuids = ["uuid1", "uuid2", "uuid3"]
# Fetch contact data in parallel
_, contact_results = client.get_contact_data_parallel(uuids)
# Fetch contact events in parallel
_, events_results = client.get_contact_events_parallel(uuids)
# Fetch funnel status in parallel
_, funnel_results = client.get_contact_funnel_status_parallel(uuids)
print(contact_results)
print(events_results)
print(funnel_results)
```
**Features:**
- Automatic parallelization with configurable worker count
- Handles 429/5xx/network errors with coordinated retries
- Appends the UUID to each result for traceability
See the `rdstation_api_helper/utils.py` source for details.
## Requirements
- Python 3.10-3.12
- pandas >= 2.0.0
- python-dotenv >= 1.0.0
- requests >= 2.32.4
- sqlalchemy >= 2.0.0
- psycopg2-binary >= 2.9.0
- tqdm >= 4.65.0
## License
This project is licensed under the GPL License. See [LICENSE](LICENSE) file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Raw data
{
"_id": null,
"home_page": "https://github.com/machado000/rdstation-api-helper",
"name": "rdstation-api-helper",
"maintainer": null,
"docs_url": null,
"requires_python": "<=3.13,>=3.11",
"maintainer_email": null,
"keywords": "rd-station, pandas, etl, data-extraction, reports",
"author": "Joao Brito",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b2/0a/ec08f492ee7ca784e095194a91e56e426235c4b0030cb8b700ab3024d6d6/rdstation_api_helper-1.1.3.tar.gz",
"platform": null,
"description": "## RD Station API Helper\n\nA Python library for interacting with the RD Station API, providing ORM models, authentication, segmentation, contact, and event retrieval, as well as batch and parallel data fetching utilities.\n\n[](https://pypi.org/project/rdstation-api-helper/)\n[](https://github.com/machado000/rdstation-api-helper/commits/main)\n[](https://github.com/machado000/rdstation-api-helper/issues)\n[](https://github.com/machado000/rdstation-api-helper/blob/main/LICENSE)\n\n## Features\n\n- **RD Station API v2 support**: Query segmentations, contacts, leads, and conversion events\n- **Batch & Parallel Fetching**: Utilities for efficient data extraction with configurable workers\n- **Robust Error Handling**: Comprehensive error handling and retry logic with coordinated barriers\n- **Webhook Data Processing**: Fetch and process webhook events from SQL databases\n- **PostgreSQL Integration**: Built-in PostgreSQL utilities for data storage and retrieval\n- **ORM Models**: SQLAlchemy models for RD Station entities (Segmentation, Contact, Lead, etc.)\n- **Logging & Config Utilities**: Easy configuration and logging\n- **Type Hints**: Full type hint support for better IDE experience\n\n## Installation\n\n```bash\npip install rdstation-api-helper\n```\n\n## Quick Start\n\n### 1. Set up credentials\n\nCreate a `secrets/rdstation_secret.json` file with your RD Station API credentials:\n\n```json\n{\n \"RDSTATION_CLIENT_ID\": \"YOUR_CLIENT_ID\",\n \"RDSTATION_CLIENT_SECRET\": \"YOUR_CLIENT_SECRET\",\n \"RDSTATION_REFRESH_TOKEN\": \"YOUR_REFRESH_TOKEN\"\n}\n```\n\n### 2. Basic usage\n\n```python\nfrom rdstation_api_helper import RDStationAPI\n\n# Initialize API client (loads credentials from environment or .env)\nclient = RDStationAPI()\n\n# Fetch all segmentations\nsegmentations = client.get_segmentations()\n\n# Fetch contacts for each segmentation\ncontacts = client.get_segmentation_contacts(\"segmentations_id\")\n\n# Fetch contact data for a specific UUID\nstatus_code, contact_data = client.get_contact_data(\"contact_uuid\")\n\n# Fetch conversion events for a contact\nstatus_code, events = client.get_contact_events(\"some-contact_uuid\")\n\n# Fetch webhook events from database\nfrom rdstation_api_helper.utils import PostgresDB, PgConfig\n\n# Initialize database connection\ndb = PostgresDB()\n\n# Fetch webhook events within date range\nwebhook_events = client.get_webhook_events(\n start_date=\"2025-08-01\",\n end_date=\"2025-08-28\", \n engine=db.engine,\n table_name=\"rd_webhook_v1\",\n api_version=\"v1\"\n)\n```\n## ORM Models\n\nThe package provides SQLAlchemy ORM models for RD Station entities, which can be used for database integration.\n\n- `Segmentation`\n- `SegmentationContact`\n- `Contact`\n- `ContactFunnelStatus`\n- `ConversionEvents`\n- `Lead`\n\n## Database Integration\n\nThe library includes PostgreSQL utilities for easy database integration:\n\n```python\nfrom rdstation_api_helper.utils import PostgresDB, PgConfig\n\n# Using environment variables (PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD)\ndb = PostgresDB()\n\n# Or with custom configuration\nconfig = PgConfig(\n host=\"localhost\",\n port=\"5432\", \n dbname=\"mydb\",\n user=\"myuser\",\n password=\"mypass\"\n)\ndb = PostgresDB(config=config)\n\n# Save data to database with upsert support\ndb.save_to_sql(data, Contact, upsert_values=True)\n```\n\n## Examples\n\nCheck the `examples/` directory for comprehensive usage examples:\n\n- `basic_usage.py` - Simple report extraction\n\n## Parallel & Batch Fetching\n\nThe library provides a `parallel_decorator` utility to easily parallelize API calls for batch data fetching. This is used in the following methods of `RDStationAPI`:\n\n- `get_contact_data_parallel(uuids: list[str])`\n- `get_contact_events_parallel(uuids: list[str])`\n- `get_contact_funnel_status_parallel(uuids: list[str])`\n\nThese methods accept a list of UUIDs and fetch the corresponding data in parallel, handling rate limits and transient errors automatically. The decorator coordinates retries for 429/5xx/network errors and ensures each result is tagged with its UUID.\n\n### Usage Example\n\n```python\nfrom rdstation_api_helper import RDStationAPI\n\nclient = RDStationAPI()\nuuids = [\"uuid1\", \"uuid2\", \"uuid3\"]\n\n# Fetch contact data in parallel\n_, contact_results = client.get_contact_data_parallel(uuids)\n\n# Fetch contact events in parallel\n_, events_results = client.get_contact_events_parallel(uuids)\n\n# Fetch funnel status in parallel\n_, funnel_results = client.get_contact_funnel_status_parallel(uuids)\n\nprint(contact_results)\nprint(events_results)\nprint(funnel_results)\n```\n\n**Features:**\n- Automatic parallelization with configurable worker count\n- Handles 429/5xx/network errors with coordinated retries\n- Appends the UUID to each result for traceability\n\nSee the `rdstation_api_helper/utils.py` source for details.\n\n## Requirements\n\n- Python 3.10-3.12\n- pandas >= 2.0.0\n- python-dotenv >= 1.0.0\n- requests >= 2.32.4\n- sqlalchemy >= 2.0.0\n- psycopg2-binary >= 2.9.0\n- tqdm >= 4.65.0\n\n\n## License\n\nThis project is licensed under the GPL License. See [LICENSE](LICENSE) file for details.\n\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.",
"bugtrack_url": null,
"license": "GPL",
"summary": "ETL module for RD Station API database-optimized DataFrame processing",
"version": "1.1.3",
"project_urls": {
"Homepage": "https://github.com/machado000/rdstation-api-helper",
"Issues": "https://github.com/machado000/rdstation-api-helper/issues"
},
"split_keywords": [
"rd-station",
" pandas",
" etl",
" data-extraction",
" reports"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f4e2d43dfbe7bae2ca7d6b332a3ea6f02aabf3c08e8c45679efa1aef13e55a49",
"md5": "de346440379dbfc85dacd10844b38b69",
"sha256": "39d9c2ee629c8affd19a0de56975c2aaee53b0de7446a95e888a62430a2b7416"
},
"downloads": -1,
"filename": "rdstation_api_helper-1.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "de346440379dbfc85dacd10844b38b69",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<=3.13,>=3.11",
"size": 25936,
"upload_time": "2025-09-01T17:28:56",
"upload_time_iso_8601": "2025-09-01T17:28:56.463693Z",
"url": "https://files.pythonhosted.org/packages/f4/e2/d43dfbe7bae2ca7d6b332a3ea6f02aabf3c08e8c45679efa1aef13e55a49/rdstation_api_helper-1.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b20aec08f492ee7ca784e095194a91e56e426235c4b0030cb8b700ab3024d6d6",
"md5": "d07f6d31f4109c3ae509f7f9dcc3ec88",
"sha256": "890614aab9697a4c19f5c796a56d46bdda85eb01a7e4bc668d0776d1a53dfc71"
},
"downloads": -1,
"filename": "rdstation_api_helper-1.1.3.tar.gz",
"has_sig": false,
"md5_digest": "d07f6d31f4109c3ae509f7f9dcc3ec88",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<=3.13,>=3.11",
"size": 25319,
"upload_time": "2025-09-01T17:28:57",
"upload_time_iso_8601": "2025-09-01T17:28:57.865367Z",
"url": "https://files.pythonhosted.org/packages/b2/0a/ec08f492ee7ca784e095194a91e56e426235c4b0030cb8b700ab3024d6d6/rdstation_api_helper-1.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 17:28:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "machado000",
"github_project": "rdstation-api-helper",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "rdstation-api-helper"
}
JSON
