Skip to main content
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:
Base exception class for all Spoo.me related errors.Attributes:
  • error_type: The type of error (e.g., “UrlError”, “AliasError”)
  • message: Detailed error message
  • status_code: HTTP status code
Raised when the provided URL is invalid or missing.
try:
    shortener.shorten("invalid-url")
except UrlError as e:
    print(f"Invalid URL: {e.message}")
Raised when the requested alias is invalid or already taken.
try:
    shortener.shorten("https://example.com", alias="taken")
except AliasError as e:
    print(f"Alias error: {e.message}")
Raised when the password doesn’t meet requirements.
try:
    shortener.shorten("https://example.com", password="weak")
except PasswordError as e:
    print(f"Password error: {e.message}")
Raised when API rate limits are exceeded.
try:
    shortener.shorten("https://example.com")
except RateLimitError as e:
    print(f"Rate limit exceeded. Retry after: {e.retry_after} seconds")

​
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
⌘I