Spoo.me Python SDK

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

pip3 install py_spoo_url

uv add 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.

string

required

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

string

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

string

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

integer

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

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.

string

required

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

string

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

string

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

integer

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

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.

string

required

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

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.

string

required

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

string

required

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

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:

SpooMeError

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

UrlError

Raised when the provided URL is invalid or missing.

try:
    shortener.shorten("invalid-url")
except UrlError as e:
    print(f"Invalid URL: {e.message}")

AliasError

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}")

PasswordError

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}")

RateLimitError

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

Getting Started

API v1 Reference

API v0 Reference (Legacy)

Tools & Libraries

Self Hosting

Installation

Quick Start

Features

URL Shortening

Statistics

Data Export

Rate Limiting

Usage Examples

Basic URL Shortening

Advanced URL Shortening

URL Statistics

Data Export

Error Handling

API Reference

Shortener Class

`shorten()`

`emoji_shorten()`

Statistics Class

`get_stats()`

DataExport Class

`export_data()`

Configuration

Custom Base URL

Rate Limiting Configuration

Error Types

Complete Documentation

View Complete Documentation

Contributing

GitHub Repository

Support

GitHub Issues

Discord Support

​Installation

​Quick Start

​Features

URL Shortening

Statistics

Data Export

Rate Limiting

​Usage Examples

​Basic URL Shortening

​Advanced URL Shortening

​URL Statistics

​Data Export

​Error Handling

​API Reference

​Shortener Class

​shorten()

​emoji_shorten()

​Statistics Class

​get_stats()

​DataExport Class

​export_data()

​Configuration

​Custom Base URL

​Rate Limiting Configuration

​Error Types

​Complete Documentation

View Complete Documentation

​Contributing

GitHub Repository

​Support

GitHub Issues

Discord Support

Installation

Quick Start

Features

Usage Examples

Basic URL Shortening

Advanced URL Shortening

URL Statistics

Data Export

Error Handling

API Reference

Shortener Class

`shorten()`

`emoji_shorten()`

Statistics Class

`get_stats()`

DataExport Class

`export_data()`

Configuration

Custom Base URL

Rate Limiting Configuration

Error Types

Complete Documentation

Contributing

Support