{"id":19500663,"url":"https://github.com/spoo-me/py_spoo_url","last_synced_at":"2025-07-15T19:06:01.747Z","repository":{"id":220329794,"uuid":"751353156","full_name":"spoo-me/py_spoo_url","owner":"spoo-me","description":"Python SDK for spoo.me URL Shortener","archived":false,"fork":false,"pushed_at":"2025-05-22T23:10:14.000Z","size":1245,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-16T10:52:52.917Z","etag":null,"topics":["analytics","pandas","pip","python","python-package","url-shortener","url-shortener-api"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/py-spoo-url/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spoo-me.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-01T12:50:57.000Z","updated_at":"2025-05-22T23:10:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"f4ffcad1-4a1e-4e8b-9f97-ec1c9e516d0b","html_url":"https://github.com/spoo-me/py_spoo_url","commit_stats":{"total_commits":12,"total_committers":3,"mean_commits":4.0,"dds":"0.41666666666666663","last_synced_commit":"4c7aa53dc62db1a99893710ee9e0c5b013a179a9"},"previous_names":["spoo-me/py_spoo_url"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/spoo-me/py_spoo_url","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spoo-me%2Fpy_spoo_url","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spoo-me%2Fpy_spoo_url/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spoo-me%2Fpy_spoo_url/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spoo-me%2Fpy_spoo_url/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spoo-me","download_url":"https://codeload.github.com/spoo-me/py_spoo_url/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spoo-me%2Fpy_spoo_url/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265452660,"owners_count":23767999,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","pandas","pip","python","python-package","url-shortener","url-shortener-api"],"created_at":"2024-11-10T22:09:25.823Z","updated_at":"2025-07-15T19:06:01.737Z","avatar_url":"https://github.com/spoo-me.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=center\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/spoo-me/py_spoo_url/main/assets/py_spoo_url.png\" height=\"50px\" alt=\"py_spoo_url banner\"\u003e\n\u003c/p\u003e\n\n\n### 🚀 Simple URL shortening with advanced analytics, emoji aliases, and more using spoo.me\n\n\u003cbr\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e📖 Table of Contents\u003c/summary\u003e\n\n- [📦 Installing](#-installing)\n- [📥 Importing](#-importing)\n- [✂️ Shortening URL](#️-shortening-url)\n  - [For Non-emoji aliases](#for-non-emoji-aliases)\n  - [😎 For Emoji aliases](#-for-emoji-aliases)\n- [📊 URL Statistics](#-url-statistics)\n  - [🔧 Initializing the class](#-initializing-the-class)\n  - [👀 Viewing the Basic Statistics](#-viewing-the-basic-statistics)\n  - [](#)\n    - [Example Usage](#example-usage)\n  - [📈 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    - [👀 Heatmap Preview](#-heatmap-preview)\n- [📤 Exporting Stats Data](#-exporting-stats-data)\n- [🧳 Dependencies](#-dependencies)\n- [🚨 Error Codes](#-error-codes)\n- [🤝 Support and Issues](#-support-and-issues)\n- [🤗 Contributing](#-contributing)\n- [📜 Licence](#-licence)\n\n\u003c/details\u003e\n\n---\n\n## 📦 Installing\n\nYou can install this package using pip:\n\n```bash\npip install py_spoo_url\n```\n\n---\n\n## 📥 Importing\n\n```python\nfrom py_spoo_url import Shorten, Statistics\n```\n\n## ✂️ 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=\u003cyour_choice\u003e`\n\nprint(f\"Shortened URL: {short_url}\")\n```\n\n### 😎 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=\u003crandom_emoji_sequence\u003e`\n\nprint(f\"Emojified URL: {emoji_url}\")\n```\n\n**Note:** The emoji sequence must contain actual emojies like `😆🤯...`\n\n---\n\n## 📊 URL Statistics\n\nThe Statistics class enables you to retrieve detailed statistics for a given short code.\n\n### 🔧 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### 👀 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\u003cdetails\u003e\n\n\u003csummary\u003e List of the analytics you can access \u003c/summary\u003e\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\u003c/details\u003e\n\n### 📈 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\u003cdetails\u003e\n\u003csummary\u003e List of Available Charts \u003c/summary\u003e\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\u003c/details\u003e\n\n#### 👀 Heatmap Preview\n\n\u003cimg src=\"https://raw.githubusercontent.com/spoo-me/py_spoo_url/main/assets/heatmap-example.png\" alt=\"Heatmap Example Image\"\u003e\n\n## 📤 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## 🧳 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. 🐼\n- `geopandas`: For creating geographical visualizations. 🌎\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## 🚨 Error Codes\n\nTo see the error codes returned by the API, please visit [https://spoo.me/api](https://spoo.me/api)\n\n## 🤝 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## 🤗 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## 📜 Licence\n\nThis package is licensed under the MIT License - see the LICENSE file for details.\n\n---\n![PyPI](https://img.shields.io/pypi/v/py_spoo_url?style=flat-square)\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/spoo-me/py_spoo_url/ci.yml)\n![Codecov](https://img.shields.io/codecov/c/github/spoo-me/py_spoo_url)\n![Downloads](https://img.shields.io/pypi/dm/py_spoo_url?style=flat-square)\n![Last Commit](https://img.shields.io/github/last-commit/spoo-me/py_spoo_url?style=flat-square)\n\n---\n\n\u003ch6 align=\"center\"\u003e\n\u003cimg src=\"https://spoo.me/static/images/favicon.png\" height=30\u003e\n\u003cbr\u003e\n© spoo.me . 2025\n\nAll Rights Reserved\u003c/h6\u003e\n\n\u003cp align=\"center\"\u003e\n\t\u003ca href=\"https://github.com/spoo-me/py_spoo_url/blob/master/LICENSE.txt\"\u003e\u003cimg src=\"https://img.shields.io/static/v1.svg?style=for-the-badge\u0026label=License\u0026message=MIT\u0026logoColor=d9e0ee\u0026colorA=363a4f\u0026colorB=b7bdf8\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspoo-me%2Fpy_spoo_url","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspoo-me%2Fpy_spoo_url","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspoo-me%2Fpy_spoo_url/lists"}