Skip to content

quickstart.mdx

Latest commit

 

History

History
371 lines (299 loc) · 8.03 KB

quickstart.mdx

File metadata and controls

371 lines (299 loc) · 8.03 KB
title Quick Start
description Get started with the Spoo.me API in minutes
icon rocket

Get up and running with the Spoo.me v1 API in just a few minutes. This guide will show you how to make your first API call and shorten your first URL.

This guide uses the **v1 API without authentication** (anonymous mode). For higher rate limits and advanced features, check out [API Keys](/api-keys).

Step 1: Make Your First API Call

No registration or API keys required! You can start using the v1 API immediately with anonymous access.

curl -X POST https://spoo.me/api/v1/shorten \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://example.com"
  }'
import requests

response = requests.post(
    "https://spoo.me/api/v1/shorten",
    headers={"Content-Type": "application/json"},
    json={"long_url": "https://example.com"}
)

print(response.json())
fetch('https://spoo.me/api/v1/shorten', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        long_url: 'https://example.com'
    })
})
.then(response => response.json())
.then(data => console.log(data));

Expected Response:

{
  "alias": "abc123",
  "short_url": "https://spoo.me/abc123",
  "long_url": "https://example.com",
  "owner_id": null,
  "created_at": 1704067200,
  "status": "ACTIVE",
  "private_stats": false
}

Step 2: Try Advanced Features

Try features like password protection, custom aliases, and emoji URLs.

Custom Alias

curl -X POST https://spoo.me/api/v1/shorten \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://github.com/spoo-me",
    "alias": "github"
  }'
import requests

response = requests.post(
    "https://spoo.me/api/v1/shorten",
    headers={"Content-Type": "application/json"},
    json={
        "long_url": "https://github.com/spoo-me",
        "alias": "github"
    }
)

print(response.json())

Password Protection

curl -X POST https://spoo.me/api/v1/shorten \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://example.com",
    "password": "secure123"
  }'
import requests

response = requests.post(
    "https://spoo.me/api/v1/shorten",
    headers={"Content-Type": "application/json"},
    json={
        "long_url": "https://example.com",
        "password": "secure123"
    }
)

print(response.json())

Step 3: Get URL Statistics

Retrieve analytics for your shortened URL (public URLs only):

curl -X GET "https://spoo.me/api/v1/stats?scope=anon&short_code=abc123"
import requests

response = requests.get(
    "https://spoo.me/api/v1/stats",
    params={
        "scope": "anon",
        "short_code": "abc123"
    }
)

stats = response.json()
print(f"Total clicks: {stats['summary']['total_clicks']}")
print(f"Unique clicks: {stats['summary']['unique_clicks']}")
**Anonymous stats** can only view statistics for public (non-private) URLs. For full analytics and private URL stats, use [API key authentication](/api-keys).

Step 4: Additional Options

The v1 API supports several additional options:

curl -X POST https://spoo.me/api/v1/shorten \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://example.com",
    "max_clicks": 100
  }'
curl -X POST https://spoo.me/api/v1/shorten \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://example.com",
    "expire_after": 1735689600
  }'
curl -X POST https://spoo.me/api/v1/shorten \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://example.com",
    "block_bots": true
  }'
**Emoji URLs** are available in the legacy v0 API. See our [legacy documentation](/api-reference) for emoji URL creation.

Common Use Cases

```python # Track campaign performance campaign_url = shorten_url( "https://mysite.com/campaign", alias="summer2024", max_clicks=1000 ) ``` ```python # Create shareable social links social_url = shorten_url( "https://mysite.com/article", alias="latest-post" ) ``` ```python # Track email click-through rates email_url = shorten_url( "https://mysite.com/newsletter", alias="newsletter-jan" ) ``` ```python # Create QR-friendly URLs qr_url = shorten_url( "https://mysite.com/menu", alias="menu" ) ```

Next Steps

Check out all available endpoints in our [API Reference](/api-reference/url-shortening/create-shortened-url) Use our [Python library](/tools/python-library) for easier integration Try our [Discord bot](/tools/spoobot) for team collaboration Understand [rate limiting](/rate-limits) to optimize your usage

Error Handling

Always handle potential errors in your applications:

import requests

def safe_shorten_url(long_url, **kwargs):
    try:
        response = requests.post(
            "https://spoo.me/api/v1/shorten",
            headers={"Content-Type": "application/json"},
            json={"long_url": long_url, **kwargs}
        )
        
        if response.status_code == 201:
            return response.json()["short_url"]
        elif response.status_code == 429:
            print("Rate limit exceeded. Please wait.")
            return None
        else:
            error_data = response.json()
            print(f"Error: {error_data.get('error', 'Unknown error')}")
            return None
            
    except requests.RequestException as e:
        print(f"Request failed: {e}")
        return None

# Usage
short_url = safe_shorten_url("https://example.com", alias="test")
if short_url:
    print(f"Success: {short_url}")
async function safeShortenerUrl(long_url, options = {}) {
    try {
        const response = await fetch('https://spoo.me/api/v1/shorten', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({ long_url, ...options })
        });
        
        if (response.status === 201) {
            const data = await response.json();
            return data.short_url;
        } else if (response.status === 429) {
            console.log('Rate limit exceeded. Please wait.');
            return null;
        } else {
            const errorData = await response.json();
            console.log(`Error: ${errorData.error || 'Unknown error'}`);
            return null;
        }
    } catch (error) {
        console.log(`Request failed: ${error.message}`);
        return null;
    }
}

// Usage
const shortUrl = await safeShortenerUrl('https://example.com', { alias: 'test' });
if (shortUrl) {
    console.log(`Success: ${shortUrl}`);
}

Testing Your Integration

Use these test URLs to verify your integration:

**Test URLs:** - `https://httpbin.org/json` - Returns JSON response - `https://httpbin.org/delay/2` - Simulates slow loading - `https://example.com` - Simple test page

Need Help?

Get real-time help from our community Contact us for technical support

You're now ready to start building with the Spoo.me API! 🚀