介绍
# Go2.gg — Edge-Native URL Shortener
URL 缩短、分析、二维码、Webhooks、图库（Link-in-Bio）。基于 Cloudflare 边缘网络构建，全球重定向延迟低于 10ms。
## Setup
从以下地址获取 API 密钥：https://go2.gg/dashboard/api-keys （免费，无需信用卡）
```bash export GO2GG_API_KEY="go2_your_key_here" ```
**API base:** `https://api.go2.gg/api/v1` **Auth:** `Authorization: Bearer $GO2GG_API_KEY` **Docs:** https://go2.gg/docs/api/links
---
## Short Links
创建、管理和跟踪带有自定义 Slug、标签、过期时间、密码以及地理位置/设备定位的短链接。
### Create a Link
```bash curl -X POST "https://api.go2.gg/api/v1/links" \ -H "Authorization: Bearer $GO2GG_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "destinationUrl": "https://example.com/landing-page", "slug": "my-link", "title": "My Campaign Link", "tags": ["marketing", "q1-2025"] }' ```
**Important:** 字段名为 `destinationUrl`（而非 `url`）。Slug 为可选项（若省略则自动生成）。
### Response
```json { "success": true, "data": { "id": "lnk_abc123", "shortUrl": "https://go2.gg/my-link", "destinationUrl": "https://example.com/landing-page", "slug": "my-link", "domain": "go2.gg", "title": "My Campaign Link", "tags": ["marketing", "q1-2025"], "clickCount": 0, "createdAt": "2025-01-01T10:30:00Z" } } ```
### List Links
```bash # List all links (paginated) curl "https://api.go2.gg/api/v1/links?perPage=20&sort=clicks" \ -H "Authorization: Bearer $GO2GG_API_KEY"
# Search links curl "https://api.go2.gg/api/v1/links?search=marketing&tag=q1-2025" \ -H "Authorization: Bearer $GO2GG_API_KEY" ```
**Query params:** `page`, `perPage` (最多 100), `search`, `domain`, `tag`, `archived`, `sort` (created/clicks/updated)
### Update a Link
```bash curl -X PATCH "https://api.go2.gg/api/v1/links/lnk_abc123" \ -H "Authorization: Bearer $GO2GG_API_KEY" \ -H "Content-Type: application/json" \ -d '{"destinationUrl": "https://example.com/updated-page", "tags": ["updated"]}' ```
### Delete a Link
```bash curl -X DELETE "https://api.go2.gg/api/v1/links/lnk_abc123" \ -H "Authorization: Bearer $GO2GG_API_KEY" # Returns 204 No Content ```
### Link Analytics
```bash curl "https://api.go2.gg/api/v1/links/lnk_abc123/stats" \ -H "Authorization: Bearer $GO2GG_API_KEY" ```
返回数据：`totalClicks`, `byCountry`, `byDevice`, `byBrowser`, `byReferrer`, `overTime`
### Advanced Link Options
```bash # Password-protected link curl -X POST "https://api.go2.gg/api/v1/links" \ -H "Authorization: Bearer $GO2GG_API_KEY" \ -H "Content-Type: application/json" \ -d '{"destinationUrl": "https://example.com/secret", "slug": "exclusive", "password": "secure123"}'
# Link with expiration + click limit curl -X POST "https://api.go2.gg/api/v1/links" \ -H "Authorization: Bearer $GO2GG_API_KEY" \ -H "Content-Type: application/json" \ -d '{"destinationUrl": "https://example.com/flash", "expiresAt": "2025-12-31T23:59:59Z", "clickLimit": 1000}'
# Geo-targeted link (different URLs per country) curl -X POST "https://api.go2.gg/api/v1/links" \ -H "Authorization: Bearer $GO2GG_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "destinationUrl": "https://example.com/default", "geoTargets": {"US": "https://example.com/us", "GB": "https://example.com/uk", "IN": "https://example.com/in"} }'
# Device-targeted link + app deep links curl -X POST "https://api.go2.gg/api/v1/links" \ -H "Authorization: Bearer $GO2GG_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "destinationUrl": "https://example.com/default", "deviceTargets": {"mobile": "https://m.example.com"}, "iosUrl": "https://apps.apple.com/app/myapp", "androidUrl": "https://play.google.com/store/apps/details?id=com.myapp" }'
# Link with UTM parameters curl -X POST "https://api.go2.gg/api/v1/links" \ -H "Authorization: Bearer $GO2GG_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "destinationUrl": "https://example.com/product", "slug": "summer-sale", "utmSource": "email", "utmMedium": "newsletter", "utmCampaign": "summer-sale" }' ```
### Create Link Parameters
| Field | Type | Required | Description | |-------|------|----------|-------------| | destinationUrl | string | yes | 重定向的目标 URL | | slug | string | no | 自定义 slug（若省略则自动生成） | | domain | string | no | 自定义域名（默认：go2.gg） | | title | string | no | 链接标题 | | description | string | no | 链接描述 | | tags | string[] | no | 用于筛选的标签 | | password | string | no | 密码保护 | | expiresAt | string | no | ISO 8601 过期日期 | | clickLimit | number | no | 允许的最大点击次数 | | geoTargets | object | no | 国家 → URL 映射 | | deviceTargets | object | no | 设备 → URL 映射 | | iosUrl | string | no | iOS 应用深链接 | | androidUrl | string | no | Android 应用深链接 | | utmSource/Medium/Campaign/Term/Content | string | no | UTM 参数 |
---
## QR Codes
生成可定制的二维码。**二维码生成是免费的，且无需认证。**
### Generate QR Code (No Auth Required)
```bash # Generate SVG QR code (free, no API key needed) curl -X POST "https://api.go2.gg/api/v1/qr/generate" \ -H "Content-Type: application/json" \ -d '{ "url": "https://go2.gg/my-link", "size": 512, "foregroundColor": "#1a365d", "backgroundColor": "#FFFFFF", "cornerRadius": 10, "errorCorrection": "H", "format": "svg" }' -o qr-code.svg
# PNG format curl -X POST "https://api.go2.gg/api/v1/qr/generate" \ -H "Content-Type: application/json" \ -d '{"url": "https://example.com", "format": "png", "size": 1024}' -o qr-code.png ```
### QR Parameters
| Field | Type | Default | Description | |-------|------|---------|-------------| | url | string | required | 待编码的 URL | | size | number | 256 | 像素尺寸 (64-2048) | | foregroundColor | string | #000000 | 模块的十六进制颜色 | | backgroundColor | string | #FFFFFF | 背景的十六进制颜色 | | cornerRadius | number | 0 | 模块圆角半径 (0-50) | | errorCorrection | string | M | L (7%), M (15%), Q (25%), H (30%) | | format | string | svg | svg 或 png |
### Save & Track QR Codes (Auth Required)
```bash # Save QR config for tracking curl -X POST "https://api.go2.gg/api/v1/qr" \ -H "Authorization: Bearer $GO2GG_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Business Card QR", "url": "https://go2.gg/contact", "linkId": "lnk_abc123"}'
# List saved QR codes curl "https://api.go2.gg/api/v1/qr" -H "Authorization: Bearer $GO2GG_API_KEY"
# Download saved QR curl "https://api.go2.gg/api/v1/qr/qr_abc123/download?format=svg" \ -H "Authorization: Bearer $GO2GG_API_KEY" -o qr.svg
# Delete QR curl -X DELETE "https://api.go2.gg/api/v1/qr/qr_abc123" -H "Authorization: Bearer $GO2GG_API_KEY" ```
---
## Webhooks
接收有关链接点击、创建和更新的实时通知。
```bash # Create webhook curl -X POST "https://api.go2.gg/api/v1/webhooks" \ -H "Authorization: Bearer $GO2GG_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Click Tracker", "url": "https://your-server.com/webhook", "events": ["click", "link.created"]}'
# List webhooks curl "https://api.go2.gg/api/v1/webhooks" -H "Authorization: Bearer $GO2GG_API_KEY"
# Test webhook curl -X POST "https://api.go2.gg/api/v1/webhooks/wh_abc123/test" \ -H "Authorization: Bearer $GO2GG_API_KEY"
# Delete webhook curl -X DELETE "https://api.go2.gg/api/v1/webhooks/wh_abc123" \ -H "Authorization: Bearer $GO2GG_API_KEY" ```
**Events:** `click`, `link.created`, `link.updated`, `link.deleted`, `domain.verified`, `qr.scanned`, `*` (所有)
Webhook 载荷包含 `X-Webhook-Signature` (HMAC SHA256) 用于验证。重试策略：5s → 30s → 2m → 10m。
---
## Galleries (Link-in-Bio)
以编程方式创建 Link-in-Bio 页面。
```bash # Create gallery curl -X POST "https://api.go2.gg/api/v1/galleries" \ -H "Authorization: Bearer $GO2GG_API_KEY" \ -H "Content-Type: application/json" \ -d '{"slug": "myprofile", "title": "My Name", "bio": "Creator & developer", "theme": "gradient"}'
# Add link item curl -X POST "https://api.go2.gg/api/v1/galleries/gal_abc123/items" \ -H "Authorization: Bearer $GO2GG_API_KEY" \ -H "Content-Type: application/json" \ -d '{"type": "link", "title": "My Website", "url": "https://example.com"}'
# Add YouTube embed curl -X POST "https://api.go2.gg/api/v1/galleries/gal_abc123/items" \ -H "Authorization: Bearer $GO2GG_API_KEY" \ -H "Content-Type: application/json" \ -d '{"type": "embed", "title": "Latest Video", "embedType": "youtube", "embedData": {"videoId": "dQw4w9WgXcQ"}}'
# Publish gallery (makes it live at go2.gg/bio/myprofile) curl -X POST "https://api.go2.gg/api/v1/galleries/gal_abc123/publish" \ -H "Authorization: Bearer $GO2GG_API_KEY" \ -H "Content-Type: application/json" \ -d '{"isPublished": true}'
# Reorder items curl -X PATCH "https://api.go2.gg/api/v1/galleries/gal_abc123/items/reorder" \ -H "Authorization: Bearer $GO2GG_API_KEY" \ -H "Content-Type: application/json" \ -d '{"itemIds": ["item_3", "item_1", "item_2"]}'
# List galleries curl "https://api.go2.gg/api/v1/galleries" -H "Authorization: Bearer $GO2GG_API_KEY" ```
**Themes:** default, minimal, gradient, dark, neon, custom (配合 customCss) **Item types:** link, header, divider, embed (youtube), image
---
## Python Example
```python import requests
API_KEY = "go2_your_key_here" # or os.environ["GO2GG_API_KEY"] BASE = "https://api.go2.gg/api/v1" headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
# Create short link resp = requests.post(f"{BASE}/links", headers=headers, json={ "destinationUrl": "https://example.com/product", "slug": "my-product", "title": "Product Link", "tags": ["product"] }) link = resp.json()["data"] print(f"Short URL: {link['shortUrl']}")
# Get analytics stats = requests.get(f"{BASE}/links/{link['id']}/stats", headers=headers).json()["data"] print(f"Clicks: {stats['totalClicks']}")
# Generate QR (no auth needed) qr = requests.post(f"{BASE}/qr/generate", json={"url": link["shortUrl"], "size": 512, "format": "png"}) with open("qr.png", "wb") as f: f.write(qr.content) ```
---
## API Endpoint Summary
| Service | Endpoint | Method | Auth | |---------|----------|--------|------| | **Links** create | `/api/v1/links` | POST | yes | | Links list | `/api/v1/links` | GET | yes | | Links get | `/api/v1/links/:id` | GET | yes | | Links update | `/api/v1/links/:id` | PATCH | yes | | Links delete | `/api/v1/links/:id` | DELETE | yes | | Links stats | `/api/v1/links/:id/stats` | GET | yes | | **QR** generate | `/api/v1/qr/generate` | POST | **no** | | QR save | `/api/v1/qr` | POST | yes | | QR list | `/api/v1/qr` | GET | yes | | QR download | `/api/v1/qr/:id/download` | GET | yes | | **Webhooks** | `/api/v1/webhooks` | CRUD | yes | | Webhook test | `/api/v1/webhooks/:id/test` | POST | yes | | **Galleries** | `/api/v1/galleries` | CRUD | yes | | Gallery items | `/api/v1/galleries/:id/items` | CRUD | yes | | Gallery publish | `/api/v1/galleries/:id/publish` | POST | yes |
## Rate Limits
| Plan | Requests/min | |------|-------------| | Free | 60 | | Pro | 300 | | Business | 1000 |
## Error Codes
| Code | Description | |------|-------------| | SLUG_RESERVED | Slug 已被保留 | | SLUG_EXISTS | 该域名下 Slug 已被占用 | | INVALID_URL | 目标 URL 无效 | | LIMIT_REACHED | 已达到当前套餐的链接数量限制 | | DOMAIN_NOT_VERIFIED | 自定义域名未验证 |