# EnsembleData Python API
[![pypi](https://img.shields.io/pypi/v/ensembledata?color=%2334D058&label=pypi%20package)](https://pypi.org/project/ensembledata/)
[![pypi](https://img.shields.io/pypi/pyversions/ensembledata.svg)](https://pypi.org/project/ensembledata/)
## Documentation
Check out the [API docs](https://ensembledata.com/apis/docs) to see which endpoints are available for each social media and for detailed descriptions of their parameters and functionality.
## Installation
Install the package with pip as you would any other python package.
```bash
pip install ensembledata
```
### Requirements
- The package only supports Python 3.7 and above.
## Usage
[Register](https://dashboard.ensembledata.com/register) to get your free API token.
```python
from ensembledata.api import EDClient
client = EDClient("API-TOKEN")
result = client.tiktok.user_info_from_username(username="daviddobrik")
print("Data: ", result.data)
print("Units charged:", result.units_charged)
# Other Examples:
# result = client.instagram.user_info(username="daviddobrik")
# result = client.youtube.channel_subscribers(channel_id="UCnQghMm3Z164JFhScQYFTBw")
```
#### TikTok Guide
Get started with the [TikTok API Guide](https://github.com/ensembledata/tiktok-scraper). Find out which endpoints are available, and how you can use them with examples using the ensembledata python package.
#### Instagram Guide
Get started with the [Instagram API Guide](https://github.com/ensembledata/instagram-scraper). Find out which endpoints are available, and how you can use them with examples using the ensembledata python package.
<br>
<br>
### Missing Endpoints / Parameters
If you find that one of the endpoints from our [API docs](https://ensembledata.com/apis/docs) is not yet available in this package, you can use the `EDClient.request` method to specify the endpoint manually in the meantime.
```python
from ensembledata.api import EDClient
client = EDClient("API-TOKEN")
result = client.request("/instagram/[example]", params={"foo": "...", "bar": "..."})
```
If you find that one the parameters to an existing endpoint is missing, you can still send this parameter via the `extra_params` dictionary which is available on all endpoint methods. See the example below:
```python
from ensembledata.api import EDClient
client = EDClient("API-TOKEN")
result = client.instagram.user_info(username="...", extra_params={"baz": "..."})
```
<br>
<br>
### Handling Errors
In the [API docs](https://ensembledata.com/apis/docs), each endpoint lists a handful of possible errors the API may respond with. You can handle these errors by catching the `EDError` exception.
```python
from ensembledata.api import EDClient, EDError, errors
client = EDClient("API-TOKEN")
try:
result = client.tiktok.user_info_from_username(username="daviddobrik")
except EDError as e:
# Rate limit exceeded...
if e.status_code == errors.STATUS_429_RATE_LIMIT_EXCEEDED:
print(e.detail)
# Subscription expired...
if e.status_code == errors.STATUS_493_SUBSCRIPTION_EXPIRED:
print(e.detail)
except Exception as e:
# Some other error occurred, unrelated to the EnsembleData API
# E.g. httpx.RequestError, json.JSONDecodeError
pass
```
<br>
<br>
### Async
This package provides an asynchronous client, `EDAsyncClient`, which will give you access to async versions of all the same methods that can be found on the `EDClient`.
```python
import asyncio
from ensembledata.api import EDAsyncClient
async def main():
client = EDAsyncClient("API-TOKEN")
result = await client.tiktok.user_info_from_username(username="daviddobrik")
if __name__ == "__main__":
asyncio.run(main())
```
### Network Retries
By default the `EDClient` will perform 3 retries when it encounters network issues. If you would like to customise this behaviour, you can pass in the `max_network_retries` param as show below:
Note: if the request times out, it will not be retried.
```python
from ensembledata.api import EDClient
client = EDClient("API-TOKEN", max_network_retries=5)
```
### Configure Timeout
If you would like control over the read timeout, you can configure this either for all request by setting `timeout` when creating the `EDClient`, or you can specify the `timeout` per request, on any of the individual methods as shown below:
Note: the timeout is specified in seconds.
```python
from ensembledata.api import EDClient
client = EDClient("API-TOKEN", timeout=120)
result = client.tiktok.user_info_from_username(username="daviddobrik", timeout=10)
```
### Types
The package uses type hints, and is type checked with the latest version of `mypy`. If you experience any type checking related issues with the package, please let us know by creating an issue.
Raw data
{
"_id": null,
"home_page": null,
"name": "ensembledata",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "ensembledata api, tiktok api, instagram api, youtube api, reddit api",
"author": null,
"author_email": "EnsembleData <hello@ensembledata.com>, Fayd Speare <fayd@ensembledata.com>",
"download_url": "https://files.pythonhosted.org/packages/b5/c6/5479a07d0adc8ef0935a862c406af6f8e2aaaa20efb83c78f8b530d4f7ad/ensembledata-0.2.4.tar.gz",
"platform": null,
"description": "# EnsembleData Python API\n\n[![pypi](https://img.shields.io/pypi/v/ensembledata?color=%2334D058&label=pypi%20package)](https://pypi.org/project/ensembledata/)\n[![pypi](https://img.shields.io/pypi/pyversions/ensembledata.svg)](https://pypi.org/project/ensembledata/)\n\n## Documentation\n\nCheck out the [API docs](https://ensembledata.com/apis/docs) to see which endpoints are available for each social media and for detailed descriptions of their parameters and functionality.\n\n## Installation\n\nInstall the package with pip as you would any other python package.\n\n```bash\npip install ensembledata\n```\n\n### Requirements\n\n- The package only supports Python 3.7 and above.\n\n## Usage\n\n[Register](https://dashboard.ensembledata.com/register) to get your free API token.\n\n```python\nfrom ensembledata.api import EDClient\n\n\nclient = EDClient(\"API-TOKEN\")\nresult = client.tiktok.user_info_from_username(username=\"daviddobrik\")\n\nprint(\"Data: \", result.data)\nprint(\"Units charged:\", result.units_charged)\n\n# Other Examples:\n# result = client.instagram.user_info(username=\"daviddobrik\")\n# result = client.youtube.channel_subscribers(channel_id=\"UCnQghMm3Z164JFhScQYFTBw\")\n```\n\n#### TikTok Guide\nGet started with the [TikTok API Guide](https://github.com/ensembledata/tiktok-scraper). Find out which endpoints are available, and how you can use them with examples using the ensembledata python package.\n\n#### Instagram Guide\nGet started with the [Instagram API Guide](https://github.com/ensembledata/instagram-scraper). Find out which endpoints are available, and how you can use them with examples using the ensembledata python package.\n\n<br>\n<br>\n\n### Missing Endpoints / Parameters\n\nIf you find that one of the endpoints from our [API docs](https://ensembledata.com/apis/docs) is not yet available in this package, you can use the `EDClient.request` method to specify the endpoint manually in the meantime. \n\n```python\nfrom ensembledata.api import EDClient\n\nclient = EDClient(\"API-TOKEN\")\nresult = client.request(\"/instagram/[example]\", params={\"foo\": \"...\", \"bar\": \"...\"})\n```\n\nIf you find that one the parameters to an existing endpoint is missing, you can still send this parameter via the `extra_params` dictionary which is available on all endpoint methods. See the example below:\n```python\nfrom ensembledata.api import EDClient\n\nclient = EDClient(\"API-TOKEN\")\nresult = client.instagram.user_info(username=\"...\", extra_params={\"baz\": \"...\"})\n```\n\n<br>\n<br>\n\n### Handling Errors\n\nIn the [API docs](https://ensembledata.com/apis/docs), each endpoint lists a handful of possible errors the API may respond with. You can handle these errors by catching the `EDError` exception. \n\n```python\nfrom ensembledata.api import EDClient, EDError, errors\n\n\nclient = EDClient(\"API-TOKEN\")\ntry:\n result = client.tiktok.user_info_from_username(username=\"daviddobrik\")\nexcept EDError as e:\n\n # Rate limit exceeded...\n if e.status_code == errors.STATUS_429_RATE_LIMIT_EXCEEDED:\n print(e.detail)\n\n # Subscription expired...\n if e.status_code == errors.STATUS_493_SUBSCRIPTION_EXPIRED:\n print(e.detail)\n\nexcept Exception as e:\n # Some other error occurred, unrelated to the EnsembleData API\n # E.g. httpx.RequestError, json.JSONDecodeError\n pass\n\n \n```\n\n<br>\n<br>\n\n### Async \n\nThis package provides an asynchronous client, `EDAsyncClient`, which will give you access to async versions of all the same methods that can be found on the `EDClient`. \n\n```python\nimport asyncio\n\nfrom ensembledata.api import EDAsyncClient\n\n\nasync def main():\n client = EDAsyncClient(\"API-TOKEN\")\n result = await client.tiktok.user_info_from_username(username=\"daviddobrik\")\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n### Network Retries\n\nBy default the `EDClient` will perform 3 retries when it encounters network issues. If you would like to customise this behaviour, you can pass in the `max_network_retries` param as show below:\n\nNote: if the request times out, it will not be retried.\n\n```python\nfrom ensembledata.api import EDClient\n\nclient = EDClient(\"API-TOKEN\", max_network_retries=5)\n```\n\n### Configure Timeout\n\nIf you would like control over the read timeout, you can configure this either for all request by setting `timeout` when creating the `EDClient`, or you can specify the `timeout` per request, on any of the individual methods as shown below:\n\nNote: the timeout is specified in seconds.\n\n```python\nfrom ensembledata.api import EDClient\n\nclient = EDClient(\"API-TOKEN\", timeout=120)\nresult = client.tiktok.user_info_from_username(username=\"daviddobrik\", timeout=10)\n```\n\n### Types\n\nThe package uses type hints, and is type checked with the latest version of `mypy`. If you experience any type checking related issues with the package, please let us know by creating an issue.\n",
"bugtrack_url": null,
"license": "LICENCE",
"summary": "Python bindings for the EnsembleData API",
"version": "0.2.4",
"project_urls": {
"Documenation": "https://ensembledata.com/apis/docs",
"Homepage": "https://ensembledata.com",
"Repository": "https://github.com/ensembledata/ensembledata-python"
},
"split_keywords": [
"ensembledata api",
" tiktok api",
" instagram api",
" youtube api",
" reddit api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a7ef6eec89f454254064dc2ed478e017fc7ade8a261da820413e98ddac2a9909",
"md5": "28c198a3b7a575a8224e2a387fe03d8a",
"sha256": "f650329ae1d97223beb7a7c2efc90fc9354f2ef5a6c959280c5e27189af01fcb"
},
"downloads": -1,
"filename": "ensembledata-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "28c198a3b7a575a8224e2a387fe03d8a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 12906,
"upload_time": "2024-12-18T22:57:16",
"upload_time_iso_8601": "2024-12-18T22:57:16.573639Z",
"url": "https://files.pythonhosted.org/packages/a7/ef/6eec89f454254064dc2ed478e017fc7ade8a261da820413e98ddac2a9909/ensembledata-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b5c65479a07d0adc8ef0935a862c406af6f8e2aaaa20efb83c78f8b530d4f7ad",
"md5": "7a992900b7e37686fd25667cb7494eb0",
"sha256": "a9f353bfa91b20b6e11763677d79d7c757dce5af0cebe4c63800f5b2abd7b305"
},
"downloads": -1,
"filename": "ensembledata-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "7a992900b7e37686fd25667cb7494eb0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 17839,
"upload_time": "2024-12-18T22:57:18",
"upload_time_iso_8601": "2024-12-18T22:57:18.806355Z",
"url": "https://files.pythonhosted.org/packages/b5/c6/5479a07d0adc8ef0935a862c406af6f8e2aaaa20efb83c78f8b530d4f7ad/ensembledata-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-18 22:57:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ensembledata",
"github_project": "ensembledata-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "ruff",
"specs": [
[
"==",
"0.5.7"
]
]
},
{
"name": "mypy",
"specs": [
[
"==",
"1.11.1"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"7.4.4"
]
]
}
],
"lcname": "ensembledata"
}