<p align=center>
<img src="https://raw.githubusercontent.com/spoo-me/py_spoo_url/main/assets/py_spoo_url.png" height="50px" alt="py_spoo_url banner">
</p>
### 🚀 Simple URL shortening with advanced analytics, emoji aliases, and more using spoo.me
<br>
<details>
<summary>📖 Table of Contents</summary>
- [📦 Installing](#-installing)
- [📥 Importing](#-importing)
- [✂️ Shortening URL](#️-shortening-url)
- [For Non-emoji aliases](#for-non-emoji-aliases)
- [😎 For Emoji aliases](#-for-emoji-aliases)
- [📊 URL Statistics](#-url-statistics)
- [🔧 Initializing the class](#-initializing-the-class)
- [👀 Viewing the Basic Statistics](#-viewing-the-basic-statistics)
- [](#)
- [Example Usage](#example-usage)
- [📈 Generating Insightful Charts](#-generating-insightful-charts)
- [](#-1)
- [Valid Data that can be passed to make the chart](#valid-data-that-can-be-passed-to-make-the-chart)
- [Valid Chart types](#valid-chart-types)
- [Usage Example](#usage-example)
- [👀 Heatmap Preview](#-heatmap-preview)
- [📤 Exporting Stats Data](#-exporting-stats-data)
- [🧳 Dependencies](#-dependencies)
- [🚨 Error Codes](#-error-codes)
- [🤝 Support and Issues](#-support-and-issues)
- [🤗 Contributing](#-contributing)
- [📜 Licence](#-licence)
</details>
---
## 📦 Installing
You can install this package using pip:
```bash
pip install py_spoo_url
```
---
## 📥 Importing
```python
from py_spoo_url import Shorten, Statistics
```
## ✂️ Shortening URL
### For Non-emoji aliases
```python
shortener = Shortener()
long_url = "https://www.example.com"
short_url = shortener.shorten(long_url, password="SuperSecretPassword@444", max_clicks=100)
# for custom alias, put `alias=<your_choice>`
print(f"Shortened URL: {short_url}")
```
### 😎 For Emoji aliases
```python
shortener = Shortener()
long_url = "https://www.example.com"
emoji_url = shorten.emojify(long_url) # pass password and max-clicks as shown above if you want
# for custom emoji alias, put `emoji_alias=<random_emoji_sequence>`
print(f"Emojified URL: {emoji_url}")
```
**Note:** The emoji sequence must contain actual emojies like `😆🤯...`
---
## 📊 URL Statistics
The Statistics class enables you to retrieve detailed statistics for a given short code.
### 🔧 Initializing the class
```python
from spoo_me import Statistics
# Initialize Statistics with a short code
stats = Statistics(short_code="ga") # replace with the shortcode you want
# if the shortUrl is password protected you have to pass the password too
```
### 👀 Viewing the Basic Statistics
```python
print(f"Total Clicks: {stats.total_clicks}")
print(f"Total Unique Clicks: {stats.total_unique_clicks}")
print(f"Average Daily Clicks: {stats.average_daily_clicks}")
print(f"Clicks Analysis: {stats.clicks_analysis}")
print(f"Browser Analysis: {stats.browsers_analysis}")
# ... and more (details below)
```
<details>
<summary> List of the analytics you can access </summary>
###
| **Method/Attribute** | **Description** |
|------------------------------------|---------------------------------------------------------|
| total_clicks | Total number of clicks on the short URL. |
| total_unique_clicks | Total number of unique clicks on the short URL. |
| average_daily_clicks | Average number of clicks per day. |
| average_monthly_clicks | Average number of clicks per month. |
| average_weekly_clicks | Average number of clicks per week. |
| last_click | Information about the last click on the short URL. |
| last_click_browser | Browser used for the last click. |
| last_click_platform | Operating system used for the last click. |
| created_at | Date when the short URL was created. |
| creation_time | Time of day when the short URL was created. |
| browsers_analysis | Analysis of browsers used for clicks. |
| platforms_analysis | Analysis of operating systems used for clicks. |
| country_analysis | Analysis of countries from which clicks originated. |
| referrers_analysis | Analysis of referrers (sources) of clicks. |
| clicks_analysis | Detailed analysis of daily clicks. |
| unique_browsers_analysis | Analysis of unique browsers used for clicks. |
| unique_platforms_analysis | Analysis of unique operating systems for clicks. |
| unique_country_analysis | Analysis of unique countries from which clicks originated. |
| unique_referrers_analysis | Analysis of unique referrers (sources) of clicks. |
| unique_clicks_analysis | Detailed analysis of daily unique clicks. |
| expired | Indicates if the short URL has expired. |
| password | Password associated with the short URL (if any). |
#### Example Usage
```python
print(f"Creation Time: {stats.creation_time}")
```
</details>
### 📈 Generating Insightful Charts
```python
plt = stats.make_chart(data="browsers_analysis", chart_type="bar") # this returns an object of matplotlib
plt.show()
# ... and more (see below)
# generating countries heatmaps
plt = stats.make_countries_heatmap()
plt.savefig("heatmap.png", format="png", bbox_inches="tight", pad_inches=0.5, dpi=300,)
plt = stats.make_unique_countries_heatmap()
plt.savefig("unique_heatmap.png", format="png", bbox_inches="tight", pad_inches=0.5, dpi=300,)
```
<details>
<summary> List of Available Charts </summary>
###
| Method | Description |
|--------------------------|---------------------------------------------------------|
| make_chart | Create various types of charts based on the data provided. |
| Parameters | Description |
|--------------------------|---------------------------------------------------------|
| data | Type of data to visualize (e.g., 'browsers_analysis', see below). |
| chart_type | Type of chart to create (e.g., "bar", "pie", "line", see below). |
| days | Number of days to consider for time-based analysis. (only for `last_n_days_analysis` and `last_n_days_unique_analysis`) |
#### Valid Data that can be passed to make the chart
- `'browsers_analysis'`
- `'platforms_analysis'`
- `'country_analysis'`
- `'referrers_analysis'`
- `'clicks_analysis'`
- `'unique_browsers_analysis'`
- `'unique_platforms_analysis'`
- `'unique_country_analysis'`
- `'unique_referrers_analysis'`
- `'unique_clicks_analysis'`
- `'last_n_days_analysis'`
- `'last_n_days_unique_analysis'`
#### Valid Chart types
- 'bar'
- 'pie'
- 'line'
- 'scatter'
- 'hist'
- 'box'
- 'area'
#### Usage Example
```python
plt = stats.make_chart('browsers_analysis', chart_type="bar")
plt.show()
```
</details>
#### 👀 Heatmap Preview
<img src="https://raw.githubusercontent.com/spoo-me/py_spoo_url/main/assets/heatmap-example.png" alt="Heatmap Example Image">
## 📤 Exporting Stats Data
You can export the statistical data to various file formats, including Excel, CSV, and JSON:
```python
# Export data to Excel
stats.export_data(filename="stats_export.xlsx", filetype="xlsx")
# Export data to CSV and compress into a ZIP file
stats.export_data(filename="stats_export", filetype="csv")
# Export data to Json
stats.export_data(filename="stats_export.json", filetypes="json")
```
---
## 🧳 Dependencies
- `matplotlib`: For creating charts and visualizations.
- `requests`: For making HTTP requests to the Spoo.me API.
- `pandas`: For handling and manipulating data in tabular form. 🐼
- `geopandas`: For creating geographical visualizations. 🌎
**All of the dependencies are automatically installed while installing the package but in case of any errors, you can install all of the dependencies listed in the `requirements.txt` file.**
## 🚨 Error Codes
To see the error codes returned by the API, please visit [https://spoo.me/api](https://spoo.me/api)
## 🤝 Support and Issues
If you encounter any issues or have questions about using the Spoo.me Python package, please open an issue on the GitHub repository.
## 🤗 Contributing
Contributions are welcome! If you have ideas for improvements or new features, feel free to fork the repository, make your changes, and submit a pull request
## 📜 Licence
This package is licensed under the MIT License - see the LICENSE file for details.
---
<a href="https://www.producthunt.com/posts/py-spoo-url?utm_source=badge-featured&utm_medium=badge&utm_souce=badge-py-spoo-url" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=437841&theme=dark" alt="py-spoo-url - URL shortener package supercharged with https://spoo.me | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
---
<h6 align="center">
<img src="https://spoo.me/static/images/favicon.png" height=30>
<br>
© spoo.me . 2024
All Rights Reserved</h6>
<p align="center">
<a href="https://github.com/spoo-me/py_spoo_url/blob/master/LICENSE.txt"><img src="https://img.shields.io/static/v1.svg?style=for-the-badge&label=License&message=MIT&logoColor=d9e0ee&colorA=363a4f&colorB=b7bdf8"/></a>
</p>
Raw data
{
"_id": null,
"home_page": "https://github.com/spoo-me/py_spoo_url",
"name": "py-spoo-url",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "URL shortening,spoo.me,URL analytics,emoji aliases,Python API,custom aliasing,password protection,click tracking,graph creation,country heatmaps,URL management,Python package",
"author": "https://github.com/spoo-me",
"author_email": "support@spoo.me",
"download_url": "https://files.pythonhosted.org/packages/b4/0f/9216bbbb5e465bac5b96bce5d021acb13d8d82cc84b77ab5a168290fc0f2/py_spoo_url-0.0.6.tar.gz",
"platform": null,
"description": "<p align=center>\n <img src=\"https://raw.githubusercontent.com/spoo-me/py_spoo_url/main/assets/py_spoo_url.png\" height=\"50px\" alt=\"py_spoo_url banner\">\n</p>\n\n\n### \ud83d\ude80 Simple URL shortening with advanced analytics, emoji aliases, and more using spoo.me\n\n<br>\n\n<details>\n<summary>\ud83d\udcd6 Table of Contents</summary>\n\n- [\ud83d\udce6 Installing](#-installing)\n- [\ud83d\udce5 Importing](#-importing)\n- [\u2702\ufe0f Shortening URL](#\ufe0f-shortening-url)\n - [For Non-emoji aliases](#for-non-emoji-aliases)\n - [\ud83d\ude0e For Emoji aliases](#-for-emoji-aliases)\n- [\ud83d\udcca URL Statistics](#-url-statistics)\n - [\ud83d\udd27 Initializing the class](#-initializing-the-class)\n - [\ud83d\udc40 Viewing the Basic Statistics](#-viewing-the-basic-statistics)\n - [](#)\n - [Example Usage](#example-usage)\n - [\ud83d\udcc8 Generating Insightful Charts](#-generating-insightful-charts)\n - [](#-1)\n - [Valid Data that can be passed to make the chart](#valid-data-that-can-be-passed-to-make-the-chart)\n - [Valid Chart types](#valid-chart-types)\n - [Usage Example](#usage-example)\n - [\ud83d\udc40 Heatmap Preview](#-heatmap-preview)\n- [\ud83d\udce4 Exporting Stats Data](#-exporting-stats-data)\n- [\ud83e\uddf3 Dependencies](#-dependencies)\n- [\ud83d\udea8 Error Codes](#-error-codes)\n- [\ud83e\udd1d Support and Issues](#-support-and-issues)\n- [\ud83e\udd17 Contributing](#-contributing)\n- [\ud83d\udcdc Licence](#-licence)\n\n</details>\n\n---\n\n## \ud83d\udce6 Installing\n\nYou can install this package using pip:\n\n```bash\npip install py_spoo_url\n```\n\n---\n\n## \ud83d\udce5 Importing\n\n```python\nfrom py_spoo_url import Shorten, Statistics\n```\n\n## \u2702\ufe0f Shortening URL\n\n### For Non-emoji aliases\n\n```python\nshortener = Shortener()\nlong_url = \"https://www.example.com\"\nshort_url = shortener.shorten(long_url, password=\"SuperSecretPassword@444\", max_clicks=100)\n# for custom alias, put `alias=<your_choice>`\n\nprint(f\"Shortened URL: {short_url}\")\n```\n\n### \ud83d\ude0e For Emoji aliases\n\n```python\nshortener = Shortener()\nlong_url = \"https://www.example.com\"\nemoji_url = shorten.emojify(long_url) # pass password and max-clicks as shown above if you want\n# for custom emoji alias, put `emoji_alias=<random_emoji_sequence>`\n\nprint(f\"Emojified URL: {emoji_url}\")\n```\n\n**Note:** The emoji sequence must contain actual emojies like `\ud83d\ude06\ud83e\udd2f...`\n\n---\n\n## \ud83d\udcca URL Statistics\n\nThe Statistics class enables you to retrieve detailed statistics for a given short code.\n\n### \ud83d\udd27 Initializing the class\n\n```python\nfrom spoo_me import Statistics\n\n# Initialize Statistics with a short code\nstats = Statistics(short_code=\"ga\") # replace with the shortcode you want\n# if the shortUrl is password protected you have to pass the password too\n```\n\n### \ud83d\udc40 Viewing the Basic Statistics\n\n```python\nprint(f\"Total Clicks: {stats.total_clicks}\")\nprint(f\"Total Unique Clicks: {stats.total_unique_clicks}\")\nprint(f\"Average Daily Clicks: {stats.average_daily_clicks}\")\nprint(f\"Clicks Analysis: {stats.clicks_analysis}\")\nprint(f\"Browser Analysis: {stats.browsers_analysis}\")\n# ... and more (details below)\n```\n\n<details>\n\n<summary> List of the analytics you can access </summary>\n\n###\n\n| **Method/Attribute** | **Description** |\n|------------------------------------|---------------------------------------------------------|\n| total_clicks | Total number of clicks on the short URL. |\n| total_unique_clicks | Total number of unique clicks on the short URL. |\n| average_daily_clicks | Average number of clicks per day. |\n| average_monthly_clicks | Average number of clicks per month. |\n| average_weekly_clicks | Average number of clicks per week. |\n| last_click | Information about the last click on the short URL. |\n| last_click_browser | Browser used for the last click. |\n| last_click_platform | Operating system used for the last click. |\n| created_at | Date when the short URL was created. |\n| creation_time | Time of day when the short URL was created. |\n| browsers_analysis | Analysis of browsers used for clicks. |\n| platforms_analysis | Analysis of operating systems used for clicks. |\n| country_analysis | Analysis of countries from which clicks originated. |\n| referrers_analysis | Analysis of referrers (sources) of clicks. |\n| clicks_analysis | Detailed analysis of daily clicks. |\n| unique_browsers_analysis | Analysis of unique browsers used for clicks. |\n| unique_platforms_analysis | Analysis of unique operating systems for clicks. |\n| unique_country_analysis | Analysis of unique countries from which clicks originated. |\n| unique_referrers_analysis | Analysis of unique referrers (sources) of clicks. |\n| unique_clicks_analysis | Detailed analysis of daily unique clicks. |\n| expired | Indicates if the short URL has expired. |\n| password | Password associated with the short URL (if any). |\n\n#### Example Usage\n\n```python\nprint(f\"Creation Time: {stats.creation_time}\")\n```\n\n</details>\n\n### \ud83d\udcc8 Generating Insightful Charts\n\n```python\nplt = stats.make_chart(data=\"browsers_analysis\", chart_type=\"bar\") # this returns an object of matplotlib\nplt.show()\n\n# ... and more (see below)\n\n# generating countries heatmaps\nplt = stats.make_countries_heatmap()\nplt.savefig(\"heatmap.png\", format=\"png\", bbox_inches=\"tight\", pad_inches=0.5, dpi=300,)\n\nplt = stats.make_unique_countries_heatmap()\nplt.savefig(\"unique_heatmap.png\", format=\"png\", bbox_inches=\"tight\", pad_inches=0.5, dpi=300,)\n```\n\n<details>\n<summary> List of Available Charts </summary>\n\n###\n\n| Method | Description |\n|--------------------------|---------------------------------------------------------|\n| make_chart | Create various types of charts based on the data provided. |\n\n| Parameters | Description |\n|--------------------------|---------------------------------------------------------|\n| data | Type of data to visualize (e.g., 'browsers_analysis', see below). |\n| chart_type | Type of chart to create (e.g., \"bar\", \"pie\", \"line\", see below). |\n| days | Number of days to consider for time-based analysis. (only for `last_n_days_analysis` and `last_n_days_unique_analysis`) |\n\n#### Valid Data that can be passed to make the chart\n\n- `'browsers_analysis'`\n- `'platforms_analysis'`\n- `'country_analysis'`\n- `'referrers_analysis'`\n- `'clicks_analysis'`\n- `'unique_browsers_analysis'`\n- `'unique_platforms_analysis'`\n- `'unique_country_analysis'`\n- `'unique_referrers_analysis'`\n- `'unique_clicks_analysis'`\n- `'last_n_days_analysis'`\n- `'last_n_days_unique_analysis'`\n\n#### Valid Chart types\n\n- 'bar'\n- 'pie'\n- 'line'\n- 'scatter'\n- 'hist'\n- 'box'\n- 'area'\n\n#### Usage Example\n\n```python\nplt = stats.make_chart('browsers_analysis', chart_type=\"bar\")\nplt.show()\n```\n\n</details>\n\n#### \ud83d\udc40 Heatmap Preview\n\n<img src=\"https://raw.githubusercontent.com/spoo-me/py_spoo_url/main/assets/heatmap-example.png\" alt=\"Heatmap Example Image\">\n\n## \ud83d\udce4 Exporting Stats Data\n\nYou can export the statistical data to various file formats, including Excel, CSV, and JSON:\n\n```python\n# Export data to Excel\nstats.export_data(filename=\"stats_export.xlsx\", filetype=\"xlsx\")\n\n# Export data to CSV and compress into a ZIP file\nstats.export_data(filename=\"stats_export\", filetype=\"csv\")\n\n# Export data to Json\nstats.export_data(filename=\"stats_export.json\", filetypes=\"json\")\n```\n\n---\n\n## \ud83e\uddf3 Dependencies\n\n- `matplotlib`: For creating charts and visualizations.\n- `requests`: For making HTTP requests to the Spoo.me API.\n- `pandas`: For handling and manipulating data in tabular form. \ud83d\udc3c\n- `geopandas`: For creating geographical visualizations. \ud83c\udf0e\n\n**All of the dependencies are automatically installed while installing the package but in case of any errors, you can install all of the dependencies listed in the `requirements.txt` file.**\n\n## \ud83d\udea8 Error Codes\n\nTo see the error codes returned by the API, please visit [https://spoo.me/api](https://spoo.me/api)\n\n## \ud83e\udd1d Support and Issues\n\nIf you encounter any issues or have questions about using the Spoo.me Python package, please open an issue on the GitHub repository.\n\n## \ud83e\udd17 Contributing\n\nContributions are welcome! If you have ideas for improvements or new features, feel free to fork the repository, make your changes, and submit a pull request\n\n## \ud83d\udcdc Licence\n\nThis package is licensed under the MIT License - see the LICENSE file for details.\n\n---\n\n\n\n\n\n<a href=\"https://www.producthunt.com/posts/py-spoo-url?utm_source=badge-featured&utm_medium=badge&utm_souce=badge-py-spoo-url\" target=\"_blank\"><img src=\"https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=437841&theme=dark\" alt=\"py-spoo-url - URL shortener package supercharged with https://spoo.me | Product Hunt\" style=\"width: 250px; height: 54px;\" width=\"250\" height=\"54\" /></a>\n\n---\n\n<h6 align=\"center\">\n<img src=\"https://spoo.me/static/images/favicon.png\" height=30>\n<br>\n\u00a9 spoo.me . 2024\n\nAll Rights Reserved</h6>\n\n<p align=\"center\">\n\t<a href=\"https://github.com/spoo-me/py_spoo_url/blob/master/LICENSE.txt\"><img src=\"https://img.shields.io/static/v1.svg?style=for-the-badge&label=License&message=MIT&logoColor=d9e0ee&colorA=363a4f&colorB=b7bdf8\"/></a>\n</p>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simple URL shortening with advanced analytics, emoji aliases, and more using spoo.me.",
"version": "0.0.6",
"project_urls": {
"Homepage": "https://github.com/spoo-me/py_spoo_url",
"spoo.me Service": "https://spoo.me"
},
"split_keywords": [
"url shortening",
"spoo.me",
"url analytics",
"emoji aliases",
"python api",
"custom aliasing",
"password protection",
"click tracking",
"graph creation",
"country heatmaps",
"url management",
"python package"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4f23b90615171d34e37c2be3a0fffdc946cc463fbc363485b0985f922cdd4d87",
"md5": "f7172828fdf908e39ffbb578d78f04af",
"sha256": "7459b1c716126e92771daba0856ae1667d7aa09f1d5ee0e7dd5cddfe5d39fb9d"
},
"downloads": -1,
"filename": "py_spoo_url-0.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f7172828fdf908e39ffbb578d78f04af",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 9755,
"upload_time": "2024-02-03T12:47:47",
"upload_time_iso_8601": "2024-02-03T12:47:47.307667Z",
"url": "https://files.pythonhosted.org/packages/4f/23/b90615171d34e37c2be3a0fffdc946cc463fbc363485b0985f922cdd4d87/py_spoo_url-0.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b40f9216bbbb5e465bac5b96bce5d021acb13d8d82cc84b77ab5a168290fc0f2",
"md5": "6cdfa12ee91b9adcc93b7a11f6fd7b30",
"sha256": "7a1fecec217ad324c90965a6195ae99530182292552942c352aa8b5b40c6e771"
},
"downloads": -1,
"filename": "py_spoo_url-0.0.6.tar.gz",
"has_sig": false,
"md5_digest": "6cdfa12ee91b9adcc93b7a11f6fd7b30",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12685,
"upload_time": "2024-02-03T12:47:48",
"upload_time_iso_8601": "2024-02-03T12:47:48.349448Z",
"url": "https://files.pythonhosted.org/packages/b4/0f/9216bbbb5e465bac5b96bce5d021acb13d8d82cc84b77ab5a168290fc0f2/py_spoo_url-0.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-03 12:47:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "spoo-me",
"github_project": "py_spoo_url",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "matplotlib",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "geopandas",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "openpyxl",
"specs": []
}
],
"lcname": "py-spoo-url"
}
JSON
