API Documentation

API Features

Simple, Powerful, and Developer-Friendly

Our API is designed to make integration straightforward with any application

Simple Integration

Integrate our URL shortening service with just a few lines of code. We support multiple programming languages including PHP, JavaScript, Python, and more.

RESTful Design

Our API follows RESTful principles with standardized HTTP methods, status codes, and JSON responses, making it predictable and easy to work with.

Advanced Options

Create password-protected URLs, track click statistics, validate URLs for safety, and utilize intelligent URL reuse - all through simple API parameters.

Documentation

API Reference

Complete documentation for integrating with our URL shortening service

Overview

Base URL: https://adcode.nabzclan.vip/api/

Our API accepts both GET and POST requests. All responses are returned in JSON format.

For production use, we recommend using POST requests with JSON data for better security and flexibility.

Rate Limit: 50 requests per minute per IP address

API Endpoints

GET /api/?url=URL

Create a Basic Shortened URL

Parameters:

url

The URL to shorten (must start with http:// or https://)

Example: https://example.com/very/long/path

URL Reuse: If the URL already exists in our system, the API will return the existing short link instead of creating a new one. The response will include is_existing: true to indicate this.

Example Response:

{
    "status": "success",
    "adcodeurl": "https://adcode.nabzclan.vip/link/abc12",
    "is_existing": false
}

GET /api/?url=URL&pass=PASSWORD

Create a Password-Protected Shortened URL

Parameters:

url

The URL to shorten (must start with http:// or https://)

Example: https://example.com/very/long/path

pass

Password to protect the URL (alphanumeric, underscore, dash only)

Example: my_secure_pass123

Example Response:

{
    "status": "success",
    "adcodeurl": "https://adcode.nabzclan.vip/link/def34",
    "is_existing": false
}

POST /api/

Create URL (Recommended Method)

Request Body (JSON):

{
    "url": "https://example.com/very/long/path",
    "pass": "optional_password"  // Optional
}

Example Response:

{
    "status": "success",
    "adcodeurl": "https://adcode.nabzclan.vip/link/ghi56",
    "is_existing": false
}

Example Response (Existing URL):

{
    "status": "success",
    "adcodeurl": "https://adcode.nabzclan.vip/link/ghi56",
    "is_existing": true
}

Error Responses

In case of an error, the API will return a JSON response with an error message:

{
    "status": "error",
    "message": "Invalid URL format"
}

Common Error Messages:

Missing parameter 'url'
Invalid URL format
Invalid password format
Database error
Rate limit exceeded

HTTP Status Codes:

200 Success - The request was processed successfully
400 Bad Request - Invalid parameters
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server-side error

Rate Limit Error Example:

{
    "status": "error",
    "message": "Rate limit exceeded. Maximum 50 requests per minute allowed.",
    "retry_after": 42
}

The retry_after value indicates the number of seconds to wait before making another request.

Code Examples

Integration Examples

Start integrating with copy-paste ready code examples

PHP Example

<?php
// Create a basic shortened URL
$longUrl = "https://example.com/very/long/url-that-needs-shortening";
$apiUrl = "https://adcode.nabzclan.vip/api/?url=" . urlencode($longUrl);

// For password protection
// $apiUrl = "https://adcode.nabzclan.vip/api/?url=" . urlencode($longUrl) . "&pass=myPassword";

// Using file_get_contents (simple approach)
$response = file_get_contents($apiUrl);
$data = json_decode($response, true);

if ($data['status'] === 'success') {
    echo "Shortened URL: " . $data['adcodeurl'];
} else {
    echo "Error: " . $data['message'];
}

// Alternative: Using cURL (recommended for production)
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://adcode.nabzclan.vip/api/");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'url' => $longUrl,
    'pass' => 'optional_password' // Remove this line if not using password
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
// Process the response as shown above
?>

JavaScript Example

// Using fetch API to create a shortened URL
const longUrl = "https://example.com/very/long/url-that-needs-shortening";

// GET Method (Simple)
const getUrl = async () => {
  const apiUrl = `https://adcode.nabzclan.vip/api/?url=${encodeURIComponent(longUrl)}`;
  
  try {
    const response = await fetch(apiUrl);
    const data = await response.json();
    
    if (data.status === 'success') {
      console.log("Shortened URL:", data.adcodeurl);
      return data.adcodeurl;
    } else {
      console.error("Error:", data.message);
      return null;
    }
  } catch (error) {
    console.error("Network error:", error);
    return null;
  }
};

// POST Method (Recommended for production)
const postUrl = async () => {
  try {
    const response = await fetch('https://adcode.nabzclan.vip/api/', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        url: longUrl,
        pass: 'optional_password'  // Remove this line if not using password
      })
    });
    
    const data = await response.json();
    
    if (data.status === 'success') {
      console.log("Shortened URL:", data.adcodeurl);
      return data.adcodeurl;
    } else {
      console.error("Error:", data.message);
      return null;
    }
  } catch (error) {
    console.error("Network error:", error);
    return null;
  }
};

// Call either getUrl() or postUrl() based on your preference

Python Example

import requests
import urllib.parse

def get_shortened_url(long_url, password=None):
    """
    Get a shortened URL using the GET method
    
    Args:
        long_url (str): The URL to shorten
        password (str, optional): Password to protect the URL
        
    Returns:
        str or None: The shortened URL or None if an error occurred
    """
    # Build the API URL with parameters
    base_url = "https://adcode.nabzclan.vip/api/"
    api_url = f"{base_url}?url={urllib.parse.quote_plus(long_url)}"
    
    # Add password if provided
    if password:
        api_url += f"&pass={urllib.parse.quote_plus(password)}"
    
    try:
        # Make the API request
        response = requests.get(api_url)
        
        # Check if the request was successful
        if response.status_code == 200:
            data = response.json()
            if data['status'] == 'success':
                return data['adcodeurl']
            else:
                print(f"Error: {data['message']}")
                return None
        else:
            print(f"HTTP Error: {response.status_code}")
            return None
            
    except Exception as e:
        print(f"Request Error: {e}")
        return None

def post_shortened_url(long_url, password=None):
    """
    Get a shortened URL using the POST method (recommended)
    
    Args:
        long_url (str): The URL to shorten
        password (str, optional): Password to protect the URL
        
    Returns:
        str or None: The shortened URL or None if an error occurred
    """
    # Prepare the request payload
    payload = {'url': long_url}
    if password:
        payload['pass'] = password
    
    try:
        # Make the API request
        response = requests.post(
            "https://adcode.nabzclan.vip/api/",
            json=payload,
            headers={'Content-Type': 'application/json'}
        )
        
        # Check if the request was successful
        if response.status_code == 200:
            data = response.json()
            if data['status'] == 'success':
                return data['adcodeurl']
            else:
                print(f"Error: {data['message']}")
                return None
        else:
            print(f"HTTP Error: {response.status_code}")
            return None
            
    except Exception as e:
        print(f"Request Error: {e}")
        return None

# Example usage
if __name__ == "__main__":
    long_url = "https://example.com/very/long/url-that-needs-shortening"
    
    # Using GET method
    short_url = get_shortened_url(long_url)
    if short_url:
        print(f"Shortened URL (GET): {short_url}")
    
    # Using POST method (recommended)
    short_url = post_shortened_url(long_url, password="optional_password")
    if short_url:
        print(f"Shortened URL (POST): {short_url}")

cURL Example

# Basic URL shortening with GET method
curl -G "https://adcode.nabzclan.vip/api/" \
  --data-urlencode "url=https://example.com/very/long/url"

# Password protected URL with GET method
curl -G "https://adcode.nabzclan.vip/api/" \
  --data-urlencode "url=https://example.com/very/long/url" \
  --data-urlencode "pass=myPassword"

# Recommended: Basic URL shortening with POST method
curl -X POST "https://adcode.nabzclan.vip/api/" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/very/long/url"}'

# Recommended: Password protected URL with POST method
curl -X POST "https://adcode.nabzclan.vip/api/" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/very/long/url","pass":"myPassword"}'

# Shell script example to process the response
#!/bin/bash
response=$(curl -s -X POST "https://adcode.nabzclan.vip/api/" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/very/long/url"}')

# Parse the JSON response (requires jq)
status=$(echo $response | jq -r '.status')
if [ "$status" = "success" ]; then
  shorturl=$(echo $response | jq -r '.adcodeurl')
  echo "Shortened URL: $shorturl"
else
  error=$(echo $response | jq -r '.message')
  echo "Error: $error"
fi

Best Practices

Implementation Guide

Follow these best practices for a successful implementation

Security Considerations

Always Use HTTPS

Ensure all API calls are made using HTTPS to encrypt data in transit.
Validate User Input

Always validate and sanitize URLs and other input before sending to the API.
Protect Sensitive Links

Use the password protection feature for any links that contain or lead to sensitive information.

Performance Optimization

Implement Caching

Cache shortened URLs to reduce API calls for frequently accessed links.
Respect Rate Limits

Implement exponential backoff when rate limits are hit instead of continuous retries.
Use POST for Multiple Parameters

When sending multiple parameters, prefer POST requests with JSON body over GET with query parameters.

Need Help?

If you need any assistance with implementing the API or have any questions, feel free to contact our support team via the contact form.

Contact Support

Simple, Powerful, and Developer-Friendly

Simple Integration

RESTful Design

Advanced Options

API Reference

Overview

API Endpoints

Create a Basic Shortened URL

Parameters:

Example Response:

Create a Password-Protected Shortened URL

Parameters:

Example Response:

Create URL (Recommended Method)

Request Body (JSON):

Example Response:

Example Response (Existing URL):

Error Responses

Common Error Messages:

HTTP Status Codes:

Rate Limit Error Example:

Integration Examples

PHP Example

JavaScript Example

Python Example

cURL Example

Implementation Guide

Security Considerations

Always Use HTTPS

Validate User Input

Protect Sensitive Links

Performance Optimization

Implement Caching

Respect Rate Limits

Use POST for Multiple Parameters

Need Help?