Metadata-Version: 2.1
Name: ensembledata
Version: 0.1.0
Summary: Python bindings for the EnsembleData API
Author-email: EnsembleData <hello@ensembledata.com>, Fayd Speare <fayd@ensembledata.com>
License: LICENCE
Project-URL: Homepage, https://ensembledata.com
Project-URL: Documenation, https://ensembledata.com/apis/docs
Project-URL: Repository, https://github.com/ensembledata/ensembledata-python
Keywords: ensembledata api,tiktok api,instagram api,youtube api,reddit api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: httpx
Requires-Dist: typing-extensions; python_version == "3.7"

# EnsembleData Python API

[![pypi](https://img.shields.io/pypi/v/ensembledata-python?color=%2334D058&label=pypi%20package)](https://pypi.org/project/ensembledata-python/)

## 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-python
```

### 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("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 Usage Docs
Explore the extensive [usage documentation for the TikTok API](https://github.com/ensembledata/tiktok-scraper).

#### Instagram Usage Docs
Explore the extensive [usage documentation for the Instagram API](https://github.com/ensembledata/instagram-scraper).

#### Youtube Usage Docs
Explore more extensive [usage documentation for the Youtube API](https://github.com/ensembledata/youtube-scraper).


&nbsp;

### 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": "..."})
```

&nbsp;

### 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


client = EDClient("API-TOKEN")
try:
    result = client.tiktok.user_info_from_username("daviddobrik")
except EDError as e:

    # Rate limit exceeded...
    if e.status_code == 429:
        print(e.detail)

    # Subscription expired...
    if e.status_code == 493:
        print(e.detail)

except Exception as e:
    # Some other error occurred, unrelated to the EnsembleData API
    # E.g. httpx.RequestError, json.JSONDecodeError
    pass

    
```

&nbsp;


### 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("daviddobrik")

if __name__ == "__main__":
    asyncio.run(main())
```

### 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.
