Skip to main content

​
Overview

The redirect endpoint is the core public-facing feature of Macondo Link Manager. It allows anyone to access a shortened link and be redirected to the original URL while tracking click analytics.
This is the only public endpoint that does not require authentication. All other endpoints require a valid JWT token.

​
Redirect to Original URL

Redirects users to the original URL associated with a short code and tracks analytics.

​
Endpoint

GET /:shortCode

​
Parameters

​
shortCode
string
required
The unique short code identifier for the link (e.g., “abc123”)

​
Response

302 Redirect - The user is automatically redirected to the original URL 404 Not Found - Redirects to frontend error page if short code doesn’t exist

​
Example Request

curl -L https://li.mcd.ppg.br/abc123
Use the -L flag with curl to follow the redirect automatically.

​
Browser Usage

Simply visit the short link URL in any browser: 
https://li.mcd.ppg.br/abc123
The browser will automatically be redirected to the original URL.

​
Click Tracking

When a user accesses a short link, the API automatically tracks the following analytics:

​
Tracked Information

  • Timestamp - Date and time of the click
  • IP Address - User’s IP address (for geolocation)
  • User Agent - Browser and device information
  • Country - Determined via GeoIP lookup
  • City - Determined via GeoIP lookup
  • Bot Detection - Identifies and flags bot traffic

​
Bot Filtering

The system uses sophisticated bot detection to ensure accurate analytics:
The API checks for common bot patterns in the User-Agent string, including:
  • Search engine crawlers (Googlebot, Bingbot, etc.)
  • Social media bots (facebookexternalhit, Twitterbot)
  • Monitoring services
  • Automated testing tools
Clicks identified as bots are marked with isBot: true and excluded from dashboard metrics.

​
Geolocation

The API uses MaxMind GeoLite2 database to determine geographic location from IP addresses: 
// Example click record created
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "linkId": "abc123-link-id",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "ipAddress": "203.0.113.42",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
  "country": "Brazil",
  "city": "São Paulo",
  "isBot": false,
  "botReason": null
}

​
Error Handling

If the short code doesn’t exist in the database, the user is redirected to the frontend error page: 
https://app.mcd.ppg.br/link-not-found
This provides a better user experience than showing a generic 404 error.

​
Implementation Details

The redirect endpoint is implemented in /api/src/routes/redirect.ts and uses the LinksService to look up the short code and track the click.

​
Redirect Flow

1

Short code lookup

The API queries the database for a link matching the provided short code.
2

Validation

If no link is found, redirect to the frontend error page.
3

Click tracking

Record click data including IP, user agent, geolocation, and bot detection.
4

Redirect

Return HTTP 302 redirect to the original URL.

​
Performance Considerations

  • Database query is optimized with an index on shortCode field
  • Click tracking is asynchronous to avoid delaying the redirect
  • GeoIP lookups use an in-memory database for fast location resolution

​
Security

The redirect endpoint does not validate the destination URL. Users should be cautious when clicking unknown short links, as they could redirect to malicious sites.

​
Best Practices

  • Always review links before creating them
  • Use the preview feature in the dashboard to verify destinations
  • Monitor analytics for suspicious activity patterns
  • Consider implementing URL validation rules for your organization

​
Example Use Cases

​
Marketing Campaign

Create a short link for a marketing campaign: 
# Create link via API
curl -X POST https://li.mcd.ppg.br/links \
  -H "Cookie: macondo.token=YOUR_JWT_TOKEN" \
  -d '{
    "originalUrl": "https://example.com/landing-page?utm_source=email&utm_campaign=launch",
    "clientId": "client-uuid",
    "campaignId": "campaign-uuid",
    "tags": ["email", "launch"]
  }'

# Response includes shortCode
{
  "shortCode": "abc123",
  ...
}

# Share the short URL
https://li.mcd.ppg.br/abc123

​
Social Media Sharing

Short links are perfect for character-limited platforms: 
Tweet: Check out our new product! https://li.mcd.ppg.br/xyz789 🚀

​
QR Codes

Generate QR codes that point to short links for print materials and events. The frontend provides built-in QR code generation for every link.

​
Next Steps

Create Links

Learn how to create and manage short links

View Analytics

Track clicks and analyze link performance

Build docs developers (and LLMs) love

Get started for freeTalk to us