ensembledata


Nameensembledata JSON
Version 0.2.4 PyPI version JSON
download
home_pageNone
SummaryPython bindings for the EnsembleData API
upload_time2024-12-18 22:57:18
maintainerNone
docs_urlNone
authorNone
requires_python>=3.7
licenseLICENCE
keywords ensembledata api tiktok api instagram api youtube api reddit api
VCS
bugtrack_url
requirements ruff mypy pytest
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 0.40259s