#
<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` | 2.2.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.3.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.9 and 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": null,
"docs_url": null,
"requires_python": "<3.14,>=3.8.0",
"maintainer_email": null,
"keywords": null,
"author": "Ethan Henderson",
"author_email": "ethan.henderson.1998@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e4/f6/73992de92b7f9fb014626deab993ba7651938a3ded3737822fe85f1f3deb/analytix-5.3.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` | 2.2.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.3.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.9 and 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.3.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": "d1a1199dd26b0621041620006e7649f070684ce8ac18ae3f4d2d2babdd0c4d10",
"md5": "5ae49c208c57800d15b59086110da7d1",
"sha256": "7f909907a5e5ea1dde1d87ba5c0069aee2089267c974d5dbfc3e7c4fc42a6e52"
},
"downloads": -1,
"filename": "analytix-5.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5ae49c208c57800d15b59086110da7d1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.8.0",
"size": 81253,
"upload_time": "2024-08-11T17:15:45",
"upload_time_iso_8601": "2024-08-11T17:15:45.533755Z",
"url": "https://files.pythonhosted.org/packages/d1/a1/199dd26b0621041620006e7649f070684ce8ac18ae3f4d2d2babdd0c4d10/analytix-5.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e4f673992de92b7f9fb014626deab993ba7651938a3ded3737822fe85f1f3deb",
"md5": "0a480a4b73c0c64fb2086683e3e92022",
"sha256": "0e2bf131cdb5ae362109d6b0e0a1e88ef35658d16d6bc187ad64be4818c8cf05"
},
"downloads": -1,
"filename": "analytix-5.3.0.tar.gz",
"has_sig": false,
"md5_digest": "0a480a4b73c0c64fb2086683e3e92022",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.8.0",
"size": 56779,
"upload_time": "2024-08-11T17:15:46",
"upload_time_iso_8601": "2024-08-11T17:15:46.909180Z",
"url": "https://files.pythonhosted.org/packages/e4/f6/73992de92b7f9fb014626deab993ba7651938a3ded3737822fe85f1f3deb/analytix-5.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-11 17:15:46",
"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
