The official Python library makes it easy to integrate Spoo.me’s URL shortening service into your Python applications.

​
Installation

Install the library using pip:

pip install py_spoo_url

​
Quick Start

Here’s a simple example to get you started:

from py_spoo_url import Shorten, Statistics

# Initialize the shortener
shortener = Shortener()

# Shorten a URL
long_url = "https://www.example.com"
short_url = shortener.shorten(long_url)
print(f"Shortened URL: {short_url}")

​
Features

URL Shortening

Shorten URLs with custom aliases and settings

Statistics

Get detailed analytics for your shortened URLs

Data Export

Export your URL data in various formats

Rate Limiting

Built-in rate limiting to respect API limits

​
Usage Examples

​
Basic URL Shortening

from py_spoo_url import Shortener

shortener = Shortener()

# Simple shortening
result = shortener.shorten("https://example.com")
print(result)  # https://spoo.me/abc123

​
Advanced URL Shortening

from py_spoo_url import Shortener

shortener = Shortener()

# Shorten with custom parameters
result = shortener.shorten(
    url="https://example.com",
    alias="myalias",
    password="SuperSecretPassword@444",
    max_clicks=100
)
print(f"Shortened URL: {result}")

​
URL Statistics

from py_spoo_url import Statistics

stats = Statistics()

# Get statistics for a shortened URL
url_stats = stats.get_stats("abc123")  # short code
print(url_stats)

# Get statistics for password-protected URL
protected_stats = stats.get_stats("xyz789", password="yourpassword")
print(protected_stats)

​
Data Export

from py_spoo_url import DataExport

exporter = DataExport()

# Export data in JSON format
json_data = exporter.export_data("abc123", format="json")

# Export data in Excel format
excel_data = exporter.export_data("abc123", format="xlsx")

# Save exported data to file
with open("url_data.xlsx", "wb") as f:
    f.write(excel_data)

​
Error Handling

from py_spoo_url import Shortener, SpooMeError

shortener = Shortener()

try:
    result = shortener.shorten("https://example.com", alias="taken-alias")
    print(result)
except SpooMeError as e:
    print(f"Error: {e.error_type} - {e.message}")
    # Handle specific error types
    if e.error_type == "AliasError":
        print("The alias is already taken, try another one")

​
API Reference

​
Shortener Class

​
shorten()

Shortens a URL with optional parameters. Returns a shortened URL string.

​
url
string
required

The URL to shorten. Must be a valid HTTP or HTTPS URL.

​
alias
string

Custom alias for the shortened URL. If not provided, a random short code will be generated.

​
password
string

Password protection for the shortened URL. Users will need to enter this password to access the original URL.

​
max_clicks
integer

Maximum number of clicks allowed for this shortened URL. Once reached, the URL will become inactive.

​
block_bots
boolean

Whether to block bots from accessing the shortened URL. Default is false.

​
emoji_shorten()

Creates emoji-based shortened URLs. Returns a shortened URL string with emojis.

​
url
string
required

The URL to shorten. Must be a valid HTTP or HTTPS URL.

​
emojies
string

Custom emoji sequence for the shortened URL. If not provided, random emojis will be used.

​
password
string

Password protection for the shortened URL. Users will need to enter this password to access the original URL.

​
max_clicks
integer

Maximum number of clicks allowed for this shortened URL. Once reached, the URL will become inactive.

​
block_bots
boolean

Whether to block bots from accessing the shortened URL. Default is false.

​
Statistics Class

​
get_stats()

Retrieves statistics for a shortened URL. Returns a dictionary containing detailed statistics.

​
short_code
string
required

The short code of the URL for which to retrieve statistics.

​
password
string

Password if the URL is protected. Required only for password-protected URLs.

​
DataExport Class

​
export_data()

Exports URL data in various formats. Returns raw data in the specified format.

​
short_code
string
required

The short code of the URL for which to export data.

​
format
string
required

Export format. Supported formats: "json", "csv", "xlsx", "xml".

​
password
string

Password if the URL is protected. Required only for password-protected URLs.

​
Configuration

​
Custom Base URL

from py_spoo_url import Shortener

# Use custom base URL (if needed)
shortener = Shortener(base_url="https://spoo.me")

​
Rate Limiting Configuration

from py_spoo_url import Shortener

# Configure rate limiting
shortener = Shortener(
    rate_limit_per_minute=5,
    rate_limit_per_hour=50,
    rate_limit_per_day=500
)

​
Error Types

The library provides specific error types for different scenarios:

​
Complete Documentation

For comprehensive documentation, code examples, and advanced usage patterns, visit the complete library documentation:

View Complete Documentation

Access detailed documentation, API reference, and advanced examples

​
Contributing

The library is open source and welcomes contributions:

GitHub Repository

Contribute to the project, report issues, or suggest improvements

​
Support

If you encounter any issues with the Python library:

GitHub Issues

Report bugs or request features

Discord Support

Get help from the community