#
<div align="center">
<img alt="analytix logo" src="https://raw.githubusercontent.com/parafoxia/analytix/main/assets/logo.png" width="400px">
<br /><br />
A simple yet powerful SDK for the YouTube Analytics API.
<br /><br />
<a href="https://pypi.python.org/pypi/analytix"><img alt="PyPI - Version" src="https://img.shields.io/pypi/v/analytix"></a>
<a href="https://pypi.python.org/pypi/analytix"><img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/analytix"></a>
<a href="https://pypi.python.org/pypi/analytix"><img alt="PyPI - Implementation" src="https://img.shields.io/pypi/implementation/analytix"></a>
<a href="https://pepy.tech/project/analytix"><img alt="Downloads" src="https://static.pepy.tech/badge/analytix"></a>
<br />
<a href="https://github.com/parafoxia/analytix"><img alt="GitHub Workflow Status (CI)" src="https://img.shields.io/github/actions/workflow/status/parafoxia/analytix/ci.yml"></a>
<a href="https://parafoxia.github.io/analytix"><img alt="GitHub Workflow Status (Publish Docs)" src="https://img.shields.io/github/actions/workflow/status/parafoxia/analytix/publish-docs.yml?label=docs"></a>
<a href="https://github.com/parafoxia/analytix"><img alt="Code Climate coverage" src="https://img.shields.io/codeclimate/coverage/parafoxia/analytix"></a>
<a href="https://github.com/parafoxia/analytix"><img alt="Code Climate maintainability" src="https://img.shields.io/codeclimate/maintainability/parafoxia/analytix"></a>
<hr />
</div>
## Features
* Pythonic syntax lets you feel right at home
* Dynamic error handling saves hours of troubleshooting and makes sure only valid requests count toward your API quota
* A clever interface allows you to make multiple requests across multiple sessions without reauthorising
* Extra support enables you to export reports in a variety of filetypes and to a number of DataFrame formats
* Easy enough for beginners, but powerful enough for advanced users
## Installation
### Installing analytix
To install the latest stable version of analytix, use the following command:
```sh
pip install analytix
```
You can also install the latest development version using the following command:
```sh
pip install git+https://github.com/parafoxia/analytix
```
You may need to prefix these commands with a call to the Python interpreter depending on your OS and Python configuration.
### Dependencies
Below is a list of analytix's dependencies.
Note that the minimum version assumes you're using CPython 3.8.
The latest versions of each library are always supported.
| Name | Min. version | Required? | Usage |
|-------------------|--------------|---------------|---------------------------------------------------------------|
| `urllib3` | 1.10.0 | Yes | Making HTTP requests |
| `jwt` | 1.2.0 | No | Decoding JWT ID tokens (from v5.1) |
| `openpyxl` | 3.0.0 | No | Exporting report data to Excel spreadsheets |
| `pandas` | 1.4.0 | No | Exporting report data to pandas DataFrames |
| `polars` | 0.15.17 | No | Exporting report data to Polars DataFrames |
| `pyarrow` | 5.0.0 | No | Exporting report data to Apache Arrow tables and file formats |
## OAuth authentication
All requests to the YouTube Analytics API need to be authorised through OAuth 2.
In order to do this, you will need a Google Developers project with the YouTube Analytics API enabled.
You can find instructions on how to do that in the [API setup guide](https://parafoxia.github.io/analytix/starting/googleapp/).
Once a project is set up, analytix handles authorisation — including token refreshing — for you.
More details regarding how and when refresh tokens expire can be found on the [Google Identity documentation](https://developers.google.com/identity/protocols/oauth2#expiration).
## Usage
### Retrieving reports
The following example creates a CSV file containing basic info for the 10 most viewed videos, from most to least viewed, in the US in 2022:
```py
from datetime import date
from analytix import Client
client = Client("secrets.json")
report = client.fetch_report(
dimensions=("video",),
filters={"country": "US"},
metrics=("estimatedMinutesWatched", "views", "likes", "comments"),
sort_options=("-estimatedMinutesWatched",),
start_date=date(2022, 1, 1),
end_date=date(2022, 12, 31),
max_results=10,
)
report.to_csv("analytics.csv")
```
If you want to analyse this data using additional tools such as *pandas*, you can directly export the report as a DataFrame or table using the `to_pandas()`, `to_arrow()`, and `to_polars()` methods of the report instance.
You can also save the report as a `.tsv`, `.json`, `.xlsx`, `.parquet`, or `.feather` file.
There are more examples in the [GitHub repository](https://github.com/parafoxia/analytix/tree/main/examples).
### Fetching group information
You can also fetch groups and group items:
```py
from analytix import Client
# You can also use the client as context manager!
with Client("secrets.json") as client:
groups = client.fetch_groups()
group_items = client.fetch_group_items(groups[0].id)
```
### Logging
If you want to see what analytix is doing, you can enable the packaged logger:
```py
import analytix
analytix.enable_logging()
```
This defaults to showing all log messages of level INFO and above.
To show more (or less) messages, pass a logging level as an argument.
## Compatibility
CPython versions 3.8 through 3.12 and PyPy versions 3.8 through 3.10 are officially supported*.
CPython 3.13-dev is provisionally supported*.
Windows, MacOS, and Linux are all supported.
*For base analytix functionality; support cannot be guaranteed for functionality requiring external libraries.
## Contributing
Contributions are very much welcome! To get started:
* Familiarise yourself with the [code of conduct](https://github.com/parafoxia/analytix/blob/main/CODE_OF_CONDUCT.md)
* Have a look at the [contributing guide](https://github.com/parafoxia/analytix/blob/main/CONTRIBUTING.md)
## License
The analytix module for Python is licensed under the [BSD 3-Clause License](https://github.com/parafoxia/analytix/blob/main/LICENSE).
Raw data
{
"_id": null,
"home_page": "https://github.com/parafoxia/analytix",
"name": "analytix",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.0,<3.14",
"maintainer_email": "",
"keywords": "",
"author": "Ethan Henderson",
"author_email": "ethan.henderson.1998@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/22/29/db59eb69ab9957853643daad82eaefe01ead94d34f3c472d0d54ceeac19b/analytix-5.2.0.tar.gz",
"platform": null,
"description": "#\n\n<div align=\"center\">\n<img alt=\"analytix logo\" src=\"https://raw.githubusercontent.com/parafoxia/analytix/main/assets/logo.png\" width=\"400px\">\n<br /><br />\nA simple yet powerful SDK for the YouTube Analytics API.\n<br /><br />\n<a href=\"https://pypi.python.org/pypi/analytix\"><img alt=\"PyPI - Version\" src=\"https://img.shields.io/pypi/v/analytix\"></a>\n<a href=\"https://pypi.python.org/pypi/analytix\"><img alt=\"PyPI - Python Version\" src=\"https://img.shields.io/pypi/pyversions/analytix\"></a>\n<a href=\"https://pypi.python.org/pypi/analytix\"><img alt=\"PyPI - Implementation\" src=\"https://img.shields.io/pypi/implementation/analytix\"></a>\n<a href=\"https://pepy.tech/project/analytix\"><img alt=\"Downloads\" src=\"https://static.pepy.tech/badge/analytix\"></a>\n<br />\n<a href=\"https://github.com/parafoxia/analytix\"><img alt=\"GitHub Workflow Status (CI)\" src=\"https://img.shields.io/github/actions/workflow/status/parafoxia/analytix/ci.yml\"></a>\n<a href=\"https://parafoxia.github.io/analytix\"><img alt=\"GitHub Workflow Status (Publish Docs)\" src=\"https://img.shields.io/github/actions/workflow/status/parafoxia/analytix/publish-docs.yml?label=docs\"></a>\n<a href=\"https://github.com/parafoxia/analytix\"><img alt=\"Code Climate coverage\" src=\"https://img.shields.io/codeclimate/coverage/parafoxia/analytix\"></a>\n<a href=\"https://github.com/parafoxia/analytix\"><img alt=\"Code Climate maintainability\" src=\"https://img.shields.io/codeclimate/maintainability/parafoxia/analytix\"></a>\n<hr />\n</div>\n\n## Features\n\n* Pythonic syntax lets you feel right at home\n* Dynamic error handling saves hours of troubleshooting and makes sure only valid requests count toward your API quota\n* A clever interface allows you to make multiple requests across multiple sessions without reauthorising\n* Extra support enables you to export reports in a variety of filetypes and to a number of DataFrame formats\n* Easy enough for beginners, but powerful enough for advanced users\n\n## Installation\n\n### Installing analytix\n\nTo install the latest stable version of analytix, use the following command:\n\n```sh\npip install analytix\n```\n\nYou can also install the latest development version using the following command:\n\n```sh\npip install git+https://github.com/parafoxia/analytix\n```\n\nYou may need to prefix these commands with a call to the Python interpreter depending on your OS and Python configuration.\n\n### Dependencies\n\nBelow is a list of analytix's dependencies.\nNote that the minimum version assumes you're using CPython 3.8.\nThe latest versions of each library are always supported.\n\n| Name | Min. version | Required? | Usage | \n|-------------------|--------------|---------------|---------------------------------------------------------------|\n| `urllib3` | 1.10.0 | Yes | Making HTTP requests |\n| `jwt` | 1.2.0 | No | Decoding JWT ID tokens (from v5.1) |\n| `openpyxl` | 3.0.0 | No | Exporting report data to Excel spreadsheets |\n| `pandas` | 1.4.0 | No | Exporting report data to pandas DataFrames |\n| `polars` | 0.15.17 | No | Exporting report data to Polars DataFrames |\n| `pyarrow` | 5.0.0 | No | Exporting report data to Apache Arrow tables and file formats |\n\n## OAuth authentication\n\nAll requests to the YouTube Analytics API need to be authorised through OAuth 2.\nIn order to do this, you will need a Google Developers project with the YouTube Analytics API enabled.\nYou can find instructions on how to do that in the [API setup guide](https://parafoxia.github.io/analytix/starting/googleapp/).\n\nOnce a project is set up, analytix handles authorisation \u2014 including token refreshing \u2014 for you.\n\nMore details regarding how and when refresh tokens expire can be found on the [Google Identity documentation](https://developers.google.com/identity/protocols/oauth2#expiration).\n\n## Usage\n\n### Retrieving reports\n\nThe following example creates a CSV file containing basic info for the 10 most viewed videos, from most to least viewed, in the US in 2022:\n\n```py\nfrom datetime import date\n\nfrom analytix import Client\n\nclient = Client(\"secrets.json\")\nreport = client.fetch_report(\n dimensions=(\"video\",),\n filters={\"country\": \"US\"},\n metrics=(\"estimatedMinutesWatched\", \"views\", \"likes\", \"comments\"),\n sort_options=(\"-estimatedMinutesWatched\",),\n start_date=date(2022, 1, 1),\n end_date=date(2022, 12, 31),\n max_results=10,\n)\nreport.to_csv(\"analytics.csv\")\n```\n\nIf you want to analyse this data using additional tools such as *pandas*, you can directly export the report as a DataFrame or table using the `to_pandas()`, `to_arrow()`, and `to_polars()` methods of the report instance.\nYou can also save the report as a `.tsv`, `.json`, `.xlsx`, `.parquet`, or `.feather` file.\n\nThere are more examples in the [GitHub repository](https://github.com/parafoxia/analytix/tree/main/examples).\n\n### Fetching group information\n\nYou can also fetch groups and group items:\n\n```py\nfrom analytix import Client\n\n# You can also use the client as context manager!\nwith Client(\"secrets.json\") as client:\n groups = client.fetch_groups()\n group_items = client.fetch_group_items(groups[0].id)\n```\n\n### Logging\n\nIf you want to see what analytix is doing, you can enable the packaged logger:\n\n```py\nimport analytix\n\nanalytix.enable_logging()\n```\n\nThis defaults to showing all log messages of level INFO and above.\nTo show more (or less) messages, pass a logging level as an argument.\n\n## Compatibility\n\nCPython versions 3.8 through 3.12 and PyPy versions 3.8 through 3.10 are officially supported*.\nCPython 3.13-dev is provisionally supported*.\nWindows, MacOS, and Linux are all supported.\n\n*For base analytix functionality; support cannot be guaranteed for functionality requiring external libraries.\n\n## Contributing\n\nContributions are very much welcome! To get started:\n\n* Familiarise yourself with the [code of conduct](https://github.com/parafoxia/analytix/blob/main/CODE_OF_CONDUCT.md)\n* Have a look at the [contributing guide](https://github.com/parafoxia/analytix/blob/main/CONTRIBUTING.md)\n\n## License\n\nThe analytix module for Python is licensed under the [BSD 3-Clause License](https://github.com/parafoxia/analytix/blob/main/LICENSE).\n",
"bugtrack_url": null,
"license": "BSD 3-Clause 'New' or 'Revised' License",
"summary": "A simple yet powerful SDK for the YouTube Analytics API.",
"version": "5.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/parafoxia/analytix/issues",
"CI": "https://github.com/parafoxia/analytix/actions",
"Changelog": "https://github.com/parafoxia/analytix/releases",
"Documentation": "https://parafoxia.github.io/analytix",
"Homepage": "https://github.com/parafoxia/analytix",
"Source": "https://github.com/parafoxia/analytix"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c1ad352e2b2ecca763cabaa8c365f3edddcd277964416a7fd8726e9eb543fd46",
"md5": "fca8f346abe42b29bb27da09313f53f8",
"sha256": "3fff23feefdf82a26b7041d0406a71d26d8a128fb57af80c1958a117100c7c48"
},
"downloads": -1,
"filename": "analytix-5.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fca8f346abe42b29bb27da09313f53f8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0,<3.14",
"size": 83594,
"upload_time": "2024-02-10T11:47:36",
"upload_time_iso_8601": "2024-02-10T11:47:36.344052Z",
"url": "https://files.pythonhosted.org/packages/c1/ad/352e2b2ecca763cabaa8c365f3edddcd277964416a7fd8726e9eb543fd46/analytix-5.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2229db59eb69ab9957853643daad82eaefe01ead94d34f3c472d0d54ceeac19b",
"md5": "f8ab6917561ce5b428a68ff1b9e246e8",
"sha256": "c40cb4bae292fb24b1420851ba04b3055e69086d02a688f4bb3dc420c72b5fbc"
},
"downloads": -1,
"filename": "analytix-5.2.0.tar.gz",
"has_sig": false,
"md5_digest": "f8ab6917561ce5b428a68ff1b9e246e8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.0,<3.14",
"size": 57249,
"upload_time": "2024-02-10T11:47:38",
"upload_time_iso_8601": "2024-02-10T11:47:38.722430Z",
"url": "https://files.pythonhosted.org/packages/22/29/db59eb69ab9957853643daad82eaefe01ead94d34f3c472d0d54ceeac19b/analytix-5.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-10 11:47:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "parafoxia",
"github_project": "analytix",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "analytix"
}
JSON
