Jo4 - 网址缩短与数据分析API

Jo4是一款集成了二维码生成与详细链接分析功能的现代化网址缩短服务。

身份验证

所有受保护的接口端点都需要API密钥。请将您的API密钥设置为环境变量：

export JO4_API_KEY="your-api-key"

获取API密钥的地址：https://jo4.io/api-keys

API基础URL

https://jo4-api.jo4.io/api/v1

接口端点

创建短链接（需身份验证）

curl -X POST "https://jo4-api.jo4.io/api/v1/protected/url" \
  -H "X-API-Key: $JO4_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "longUrl": "https://example.com/very-long-url",
    "title": "My Link"
  }'

请求体：

• longUrl（必填） - 目标网址（最长2048字符）
• title（可选） - 链接标题（最长200字符）
• description（可选） - 链接描述（最长500字符）
• shortUrl（可选） - 自定义别名（最长16字符，仅限字母数字/连字符/下划线）
• expirationTime（可选） - 链接失效的Unix时间戳
• passwordProtected（可选）- 用于启用密码保护的布尔值
• 密码（可选）- 受保护时的密码（4-128个字符）

UTM参数：

• utmSource,utmMedium,utmCampaign,utmTerm,utmContent

响应：

{
  "response": {
    "id": 123,
    "slug": "abc123",
    "shortUrl": "abc123",
    "fullShortUrl": "https://jo4.io/a/abc123",
    "longUrl": "https://example.com/very-long-url",
    "title": "My Link",
    "qrCodeUrl": "https://jo4.io/qr/abc123"
  }
}

创建匿名短链接（无需认证）

curl -X POST "https://jo4-api.jo4.io/api/v1/public/url" \
  -H "Content-Type: application/json" \
  -d '{"longUrl": "https://example.com"}'

功能有限，无法访问分析数据。

获取链接详情

curl -X GET "https://jo4-api.jo4.io/api/v1/protected/url/{slug}" \
  -H "X-API-Key: $JO4_API_KEY"

获取链接分析数据

curl -X GET "https://jo4-api.jo4.io/api/v1/protected/url/{slug}/stats" \
  -H "X-API-Key: $JO4_API_KEY"

响应内容包括：

• 总点击次数
• 按日期统计的点击次数
• 地理分布
• 设备/浏览器细分
• 引荐来源

列出我的链接

curl -X GET "https://jo4-api.jo4.io/api/v1/protected/url/myurls?page=0&size=20" \
  -H "X-API-Key: $JO4_API_KEY"

更新URL

curl -X PUT "https://jo4-api.jo4.io/api/v1/protected/url/{id}" \
  -H "X-API-Key: $JO4_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "longUrl": "https://new-destination.com"
  }'

删除URL

curl -X DELETE "https://jo4-api.jo4.io/api/v1/protected/url/{id}" \
  -H "X-API-Key: $JO4_API_KEY"

二维码

每个短链接会自动生成一个二维码，地址如下：

https://jo4.io/qr/{shortUrl}

速率限制

速率限制因套餐而异：

• 免费版：每分钟60次请求
• 专业版：最高每分钟10,000次请求
• 匿名用户（公共端点）：每分钟10次请求

API文档

完整的OpenAPI/Swagger文档：https://jo4-api.jo4.io/swagger-ui/index.html

常见用例

1. 为分享缩短URL

curl -X POST "https://jo4-api.jo4.io/api/v1/protected/url" \
  -H "X-API-Key: $JO4_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"longUrl": "https://example.com/article", "title": "Article"}'

2. 创建活动跟踪链接

curl -X POST "https://jo4-api.jo4.io/api/v1/protected/url" \
  -H "X-API-Key: $JO4_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "longUrl": "https://mysite.com/landing",
    "title": "Q1 Campaign",
    "utmSource": "twitter",
    "utmMedium": "social",
    "utmCampaign": "q1-2026"
  }'

3. 创建过期链接

curl -X POST "https://jo4-api.jo4.io/api/v1/protected/url" \
  -H "X-API-Key: $JO4_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "longUrl": "https://mysite.com/promo",
    "title": "Limited Offer",
    "expirationTime": 1738454400
  }'

错误代码