URLZ.li API

Overview

The URLZ.li API lets you create short links, list & search your links, delete them, and fetch detailed click logs and click counts. All endpoints accept both GET and POST parameters.

Authentication

Supply your API key via parameter apikey for every request. The key must exist in customer_api.apikey and not be expired: we validate customer_api.dateLimit (YYYY-mm-dd) against today's date.

# Example
GET /url/list?apikey=YOUR_KEY
# or
POST /url/create apikey=YOUR_KEY&fullUrl=https://example.com

Tip: Rotate keys regularly and keep them secret. Only use HTTPS.

Data formats

• Dates: YYYY-mm-dd (e.g., 2025-07-01)
• Times: HH:MM:SS (UTC unless specified)
• Hash format: 4–128 chars [A-Za-z0-9_-]
• Success responses wrap data in {"result": {...}}
• Error responses use {"error": "message"} with proper HTTP code

Errors & Status Codes

Endpoints

POST GET /url/create

Create a short URL for a given destination.

{
  "result": {
    "short_url": "https://urlz.li/7b3c2e5a",
    "hash": "7b3c2e5a",
    "date": "2025-07-01",
    "time": "12:34:56"
  }
}

{"error":"Missing fullUrl parameter"}
{"error":"Invalid API key"}
{"error":"API key expired"}
{"error":"Invalid domain in fullUrl"}
{"error":"Database error"}

DELETE POST GET /url/delete

Delete a short URL you own.

{
  "result": {
    "deleted": 1,
    "hash": "7b3c2e5a",
    "short_url": "https://urlz.li/7b3c2e5a",
    "url_destination": "https://example.com"
  }
}

GET POST /url/list

List and search your short URLs. Defaults to last 100.

{
  "result": {
    "filters": {
      "date": null,
      "from_date": null,
      "to_date": null,
      "url_destination": null,
      "hash": null,
      "order": "desc",
      "limit": 100,
      "offset": 0
    },
    "total": 245,
    "count": 100,
    "items": [
      {
        "id": 1234,
        "date": "2025-07-01",
        "time": "12:11:57",
        "destination": "https://example.com",
        "hash": "7b3c2e5a",
        "hash_retour": "https://urlz.li/7b3c2e5a"
      }
      // ...
    ]
  }
}

GET POST /url/logs

Return click/access logs (traceability) for a given short link hash (stored as url_short_log_access.hash_url).

{
  "result": {
    "hash": "7b3c2e5a",
    "total": 42,
    "limit": 100,
    "offset": 0,
    "order": "DESC",
    "logs": [
      {
        "city": "Paris",
        "state": "IDF",
        "country": "France",
        "country_code": "FR",
        "continent": "Europe",
        "continent_code": "EU",
        "ip_address": "203.0.113.9",
        "session_id": "abc123",
        "visit_time_gmt": "2025-07-01 12:15:05",
        "user_agent": "Mozilla/5.0 ...",
        "language": "fr-FR",
        "device_type": "desktop",
        "browser_name": "Chrome"
      }
      // ... fields may include OS, screen size etc. as stored.
    ]
  }
}

GET POST /url/clicks/count

Return the total click count for a given hash, optionally within a date range.

{
  "result": {
    "hash": "7b3c2e5a",
    "count": 42,
    "date_from": "2025-07-01",
    "date_to": "2025-07-31"
  }
}

Usage Examples

cURL

# Create
curl -G "https://api.urlz.li/url/create" \
  --data-urlencode "apikey=YOUR_KEY" \
  --data-urlencode "fullUrl=https://example.com"

# Delete
curl -X POST "https://api.urlz.li/url/delete" \
  -d "apikey=YOUR_KEY" -d "hash=7b3c2e5a"

# List (last 100)
curl -G "https://api.urlz.li/url/list" \
  --data-urlencode "apikey=YOUR_KEY"

# Logs (range)
curl -G "https://api.urlz.li/url/logs" \
  --data-urlencode "apikey=YOUR_KEY" \
  --data-urlencode "hash=7b3c2e5a" \
  --data-urlencode "date_from=2025-07-01" \
  --data-urlencode "date_to=2025-07-31"

# Count clicks
curl -G "https://api.urlz.li/url/clicks/count" \
  --data-urlencode "apikey=YOUR_KEY" \
  --data-urlencode "hash=7b3c2e5a"

JavaScript (fetch)

// Create
fetch('https://api.urlz.li/url/create?apikey=YOUR_KEY&fullUrl=' + encodeURIComponent('https://example.com'))
  .then(r => r.json())
  .then(console.log)
  .catch(console.error);

// Count
fetch('https://api.urlz.li/url/clicks/count?apikey=YOUR_KEY&hash=7b3c2e5a')
  .then(r => r.json())
  .then(data => console.log('Clicks:', data.result.count));

PHP (basic)

<?php
$base = 'https://api.urlz.li';
$apikey = 'YOUR_KEY';

// Create
$q = http_build_query(['apikey'=>$apikey,'fullUrl'=>'https://example.com']);
$resp = file_get_contents("$base/url/create?$q");
$data = json_decode($resp, true);

// List
$q = http_build_query(['apikey'=>$apikey,'limit'=>50,'order'=>'desc']);
$resp = file_get_contents("$base/url/list?$q");
$list = json_decode($resp, true);

Common Pitfalls

• Expired key: If dateLimit < today you’ll get 403.
• Invalid domain: fullUrl must contain a valid hostname.
• Hash ownership: /url/delete requires the hash to belong to the provided apikey.
• Date ranges: For list/log queries, provide both from_date and to_date.

Security & Limits

• HTTPS required; requests over plain HTTP are not supported.
• Keys are validated against customer_api.apikey and customer_api.dateLimit.
• Recommended rate limit: ≤ 10 req/sec per key (enforce at edge/proxy).
• Sanitize user-entered fullUrl server-side (already enforced by the API).