URL Shortener (Public API)

• Shorten
• API
• Stats
• Report URL
• Open-Source ↗
• Contact

Spoo.me Api Documentation

Welcome to the URL Shortener API documentation. This page provides information on how to use the API to shorten URLs and retrieve analytics.

Base URL: https://spoo.me

✂️ Shorten Long URLs

This endpoint is used to shorten a URL. The request payload must contain the URL to be shortened. The response contains the shortened URL.

Endpoint: POST /

Data

The following data parameters that the API understands:

Payload	Data Type	Description	Required
url	String	The long URL to be shortened.	Yes
alias	String	Custom alias for the shortened URL.	No
password	String	Password to access the shortened URL.	No
max-clicks	Integer	Maximum number of clicks allowed for the shortened URL.	No

Note: password must be atleast 8 characters long, must contain atleast a letter and a number and a special character either '@' or '.' and cannot be consecutive.

Headers

The following headers are used in the API requests and responses:

Header	Value
Accept*	application/json
Content-Type*	application/x-www-form-urlencoded

Note: Both of the above headers are compuslary

🧑🏻‍💻 Code Examples

import requests
import json

url = "https://spoo.me"

# Replace these with your actual values
payload = {
    "url": "https://example.com",
    "alias": "example",  # you can choose any other alias
    "max-clicks": 10,
    "password": "SuperStrongPassword@18322"
}

# Necessary to get a non-html response
headers = {
    "Accept": "application/json"
}

response = requests.post(url, data=payload, headers=headers)

if response.status_code == 200:
    # If the request was successful, print the shortened URL
    shortened_url = response.json()
else:
    # If the request failed, print the error message
    print(f"Error: {response.status_code}")
    print(response.text)
        

Response:

{"short_url": "https://spoo.me/example"}

For More code samples you can try the /get-code command of our official discord-bot, spooBot 🤖

🪲 Errors

This section provides information about the various errors that could occur while making requests through this endpoint.

Error Name	Code	Description
UrlError	400	The request does not contain the long URL or contains an invalid url. The url must contain a valid protocol like https, http and must follow rfc-1034 & rfc-2727
AliasError	400	The User requested Alias is invalid or already taken. The alias must be alphanumeric & must be under 15 chars, anything beyond 15 chars would be stripped by the API
PasswordError	400	The user entered password must be atleast 8 characters long, must contain atleast a letter and a number and a special character either '@' or '.' and cannot be consecutive.
MaxClicksError	400	The user entered max-clicks is not a positive integer.

---

😉 Emoji URLs

Spoo.me also provides the ability to shorten URLs with custom emojis.

Endpoint: POST /emoji

Data

The following data parameters that the API understands:

Payload	Data Type	Description	Required
url	String	The long URL to be shortened.	Yes
emojies	String	Custom emojies sequence for the shortened URL. Must contain only emojies, no other character is allowed.	No
password	String	Password to access the shortened URL.	No
max-clicks	Integer	Maximum number of clicks allowed for the shortened URL.	No

Note: password must be atleast 8 characters long, must contain atleast a letter and a number and a special character either '@' or '.' and cannot be consecutive.

Headers

The following headers are used in the API requests and responses:

Header	Value
Accept*	application/json
Content-Type*	application/x-www-form-urlencoded

Note: Both of the above headers are compuslary

🧑🏻‍💻 Code Examples

import requests

url = "https://spoo.me/emoji/"

payload = {
    "url": "https://example.com",
    "alias": "🐍🐍",
    "password": 1000,
    "max-clicks": "Python.Snake63"
}
headers = {
    "Accept": "application/json",
}

response = requests.post(url, data=payload, headers=headers)

if response.status_code == 200:
    print(response.json())
else:
    print(response.text)
        

Response:

{"short_url": "https://spoo.me/🐍🐍"}

🪲 Errors

This section provides information about the various errors that could occur while making requests through this endpoint.

Error Name	Code	Description
UrlError	400	The request does not contain the long URL or contains an invalid url. The url must contain a valid protocol like https, http and must follow rfc-1034 & rfc-2727
EmojiError	400	The User requested Emoji sequence is invalid or already taken. The emoji sequence must contain only emojies, no other character is allowed.
PasswordError	400	The user entered password must be atleast 8 characters long, must contain atleast a letter and a number and a special character either '@' or '.' and cannot be consecutive.
MaxClicksError	400	The user entered max-clicks is not a positive integer.

---

📊 URL Statistics

This endpoint is used to retrieve statistics about a shortened URL. The request must contain the short code of the URL. The response contains the statistics.

Endpoint: POST /stats/{shortCode}

shortCode can also represent the short code of an emoji URL.

Data

The following data parameters that the API understands:

Payload	Description	Required
password	Password of the shortened url if any.	Yes, if and only if the short url is password protected.

Headers

The following headers are used in the API requests and responses:

Header	Value
Content-Type*	application/x-www-form-urlencoded

🧑🏻‍💻 Code Examples

import requests
import json

# Replace these with your actual values
short_code = "exa"
base_url = "https://spoo.me"

payload = {                      # not required if your short url is not password protected
    "password": "Example@12"
}

# Make the request
response = requests.post(
    f"{base_url}/stats/{short_code}",
    data = payload
)

# Check the response
if response.status_code == 200:
    # If the request was successful, print the URL statistics
    url_stats = response.json()
    print(json.dumps(url_stats, indent=4))
else:
    # If the request failed, print the error message
    print(f"Error: {response.status_code}")
    print(response.text)
        

Response:

{
    "_id": "exa",
    "average_daily_clicks": 1.0,
    "average_monthly_clicks": 0.03,
    "average_weekly_clicks": 0.14,
    "browser": {
        "Edge": 1
    },
    "counter": {
        "2023-12-18": 1
    },
    "country": {
        "France": 1
    },
    "creation-date": "2023-12-18",
    "expired": null,
    "last-click": "2023-12-18 22:06:02.298005+00:00",
    "last-click-browser": "Edge",
    "last-click-os": "Windows",
    "max-clicks": null,
    "os_name": {
        "Windows": 1
    },
    "password": "Example@12",
    "referrer": {
        "spoo.me": 1
    },
    "short_code": "exa",
    "total-clicks": 1,
    "total_unique_clicks": 1,
    "unique_browser": {
        "Edge": 1
    },
    "unique_counter": {
        "2023-12-18": 1
    },
    "unique_country": {
        "France": 1
    },
    "unique_os_name": {
        "Windows": 1
    },
    "unique_referrer": {
        "spoo.me": 1
    },
    "url": "https://example.com"
}

📑 Response Analysis

The response contains the following data:

Key	Data Type	Description
_id	Str	The Short Code of the Short Link.
average_daily_clicks	Float	Average Clicks per day since the link was created.
average_monthly_clicks	Float	Average Clicks per month since the link was created.
average_weekly_clicks	Float	Average Clicks per week since the link was created.
browser	Dict	Data about the Browsers in which the short link was accessed.
creation-date	Str	Date when the short link was created.
counter	Dict	Data about the clicks per day since the link was created.
country	Dict	Data about the Countries in which the short link was accessed.
expired*	Bool	Tells whether the link has expired or not.
last-click	Str	Last Time when the short link was accessed.
last-click-browser	Str	Last Browser in which the short link was accessed.
last-click-os	Str	Last Os name in which the short link was accessed.
max-clicks*	Str	Information about the Max Clicks set my the User on the Short Link.
os_name	Dict	Data about the Os names in which the short link was accessed.
password*	Str	The password set by the User on the Short Link.
short_code	Str	The Short Code of the Short Link.
total-clicks	Int	Count of the total clicks made since the short link was created.
total_unique_clicks	Int	Count of the total unique clicks made since the short link was created.
unique_browser	Dict	Data about the Unique Browsers in which the short link was accessed.
unique_counter	Dict	Data about the Unique clicks per day since the link was created.
unique_country	Dict	Data about the Unique Countries in which the short link was accessed.
unique_os_name	Dict	Data about the Unique Os names in which the short link was accessed.
unique_referrer	Dict	Data about the Unique Referrers in which the short link was accessed.
url	Str	Original Long Url which the short link redirects to.

* Null if the Short link didnt have max-clicks set or was not password protected.

🪲 Errors

This section provides information about the various errors that could occur while making requests through the API.

Error Name	Code	Description
UrlError	404	The user requested Url never existed.
PasswordError	400	The user entered password is invalid.

---

📤 Exporting Data

This endpoint is used to export the data of your shortened URL. The request must contain the short code of the URL along with the format in which you want to recieve your data. The response contains the data of the shortened URL.

Endpoint: POST /export/{shortCode}/{exportFormat}

shortCode can also represent the short code of an emoji URL.

Available Export Formats

The following export formats are available:

Format	Description
json	Export the data in JSON format.
csv	Export the data in CSV format. The API will return the data divided in many files zipped together.
xlsx	Export the data in XLSX (Excel file) format.
xml	Export the data in XML format.

You can choose anyone of these formats and pass it in the request parameter

Important Note: The API returns raw data in the specified format, which you may need to store in a file.

Data

The following data parameters that the API understands:

Payload	Description	Required
password	Password of the shortened url if any.	Yes, if and only if the short url is password protected.

Headers

The following headers are used in the API requests and responses:

Header	Value
Content-Type*	application/x-www-form-urlencoded

🧑🏻‍💻 Code Examples

import requests
import json

# Replace these with your actual values
short_code = "exa"
base_url = "https://spoo.me"
export_format = "xlsx"    # You can choose from ["json", "csv", "xlsx", "xml"]

payload = {                      # not required if your short url is not password protected
    "password": "Example@12"
}

# Make the request

response = requests.post(
    f"{base_url}/export/{short_code}/{export_format}",
    data = payload
)

# Check the response
if response.status_code == 200:
    # If the request was successful, store the data in a file
    with open(f"{short_code}.{export_format}", "wb") as file:    # Note if the export format is csv, the file will be a zip file
        file.write(response.content)
else:
    # If the request failed, print the error message
    print(f"Error: {response.status_code}")
    print(response.text)
        

Response:

The API returns raw data in the specified format, which you may need to store in a file.

Download Sample JSON FileDownload Sample CSV FileDownload Sample XLSX FileDownload Sample XML File

🪲 Errors

This section provides information about the various errors that could occur while making requests through the API.

Error Name	Code	Description
UrlError	404	The user requested Url (short_code) never existed.
PasswordError	400	The user entered password is invalid.
FormatError	400	The user entered an invalid export format. The Exportformat must either xml, xlsx, json or csv

Note: If you're exporting your data in CSV format, ensure you save the file with a .zip extension, not .csv. Failure to do so may result in logical errors in your code. You need to save it in a zip file because the API returns the data divided in many files zipped together.

---

📜 API Rate Limits

Spoo.me API has a rate limit of 5 requests per minute, 50 requests per hour and 500 requests per day for the POST /, POST /emoji endpoints. If you exceed this limit, you will receive a 429 status code in response to your requests.

---

📦 Spoo.me Python Library

Spoo.me has a Python library that makes it easy to use the Spoo.me API. You can install it using pip:

pip install py_spoo_url

Once installed, you can use the library to shorten URLs, get the stats of a shortened URL, and export the data of a shortened URL.

Here's a quick example of how to shorten a URL:

from py_spoo_url import Shorten, Statistics

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

Complete documentation for the library can be found here.

---

🤖 SpooBot

SpooBot is a Discord bot that uses the Spoo.me API. It provides the following features:

• Use the /shorten command to shorten URLs.
• Use the /stats command to get the stats of a shortened URL and export its data.
• Use the /get-code command to get the code to shorten URLs in various languages.

SpooBot is available on the Discord Bot List. You can add it to your server by clicking here.

SpooBot is also open source. You can find the source code on GitHub.

---

📚 Conclusion

Spoo.me API is a powerful tool that allows you to shorten URLs, get the stats of a shortened URL, and export the data of a shortened URL. It's easy to use and provides a lot of flexibility. We hope this guide has helped you understand how to use the API and how to integrate it into your applications.

If you have any questions or need further assistance, feel free to reach out to us at support@spoo.me or you can join our official Discord Server. We're always happy to help!

---