Building a URL Preview Service in Flask

URL preview services are everywhere — Slack, Discord, Twitter, and most messaging apps generate rich link previews showing the title, description, and thumbnail of shared URLs. In this tutorial, we'll build a simple URL preview microservice using Flask and BeautifulSoup that your application can call to generate OpenGraph-style previews.

The Complete Implementation

Here's our full preview service. It accepts a URL via query parameter, fetches the page, extracts OpenGraph metadata, and returns a JSON response with the preview data:

from flask import Flask, request, jsonify
import requests
from bs4 import BeautifulSoup
from urllib.parse import urlparse

app = Flask(__name__)

@app.route('/preview')
def url_preview():
    """Generate a rich link preview for the given URL."""
    target_url = request.args.get('url')
    if not target_url:
        return jsonify({'error': 'Missing url parameter'}), 400

    # Validate URL format
    parsed = urlparse(target_url)
    if parsed.scheme not in ('http', 'https'):
        return jsonify({'error': 'Invalid URL scheme'}), 400

    # Fetch the target page
    try:
        resp = requests.get(
            target_url,
            headers={'User-Agent': 'PreviewBot/1.0'},
            timeout=10,
            allow_redirects=True
        )
        resp.raise_for_status()
    except requests.RequestException as e:
        return jsonify({'error': f'Failed to fetch: {e}'}), 502

    # Parse OpenGraph metadata
    soup = BeautifulSoup(resp.text, 'html.parser')
    og_title = soup.find('meta', property='og:title')
    og_desc = soup.find('meta', property='og:description')
    og_image = soup.find('meta', property='og:image')
    title = soup.find('title')

    return jsonify({
        'url': target_url,
        'title': og_title['content'] if og_title else (title.string if title else ''),
        'description': og_desc['content'] if og_desc else '',
        'image': og_image['content'] if og_image else '',
        'status_code': resp.status_code,
    })

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

How It Works

The service exposes a single endpoint at /preview?url=https://example.com. When a request comes in, it:

1. Validates that the URL has an http or https scheme
2. Makes a server-side HTTP request to fetch the target page
3. Parses the HTML to extract OpenGraph meta tags
4. Returns the preview data as JSON

Deployment

Deploy this behind Gunicorn with Nginx as a reverse proxy. For production, you'll want to add rate limiting, caching (Redis works well here), and proper error handling. We use this exact pattern at our company to power link previews in our Slack-like internal messaging app.

Here's a quick Docker setup:

# Dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY app.py .
CMD ["gunicorn", "--bind", "0.0.0.0:5000", "app:app"]

Testing

Test it locally:

$ curl "http://localhost:5000/preview?url=https://github.com"
{
  "url": "https://github.com",
  "title": "GitHub: Let's build from here",
  "description": "GitHub is where over 100 million developers...",
  "image": "https://github.githubassets.com/assets/...",
  "status_code": 200
}

That's it! A clean, minimal URL preview service you can integrate into any application. The full source code is available on our GitHub.