Capture a website screenshot with Python.

# screenshot.py: request one screenshot and save it.
import os

import requests

response = requests.get(
    "https://api.urlshot.io/v1/screenshot",
    params={
        "url": "https://en.wikipedia.org/wiki/Cartography",
        "format": "webp",
        "quality": 80,
        "viewport_width": 1280,
        "viewport_height": 800,
        "device_scale_factor": 2,
    },
    headers={"Authorization": f"Bearer {os.environ['URLSHOT_API_KEY']}"},
    timeout=60,
)

# Anything that is not an image is the JSON error envelope.
if not response.ok:
    error = response.json()["error"]
    raise RuntimeError(f"{error['code']}: {error['message']} (request {error['requestId']})")

with open("screenshot.webp", "wb") as file:
    file.write(response.content)
print("Wrote screenshot.webp")

# After the request: what it cost, and how to refer to it.
# response.headers ignores the case of a name.
credits = response.headers["X-Urlshot-Credits-Used"]  # "1", or "0" from cache
request_id = response.headers["X-Request-ID"]
print(f"request {request_id} used {credits} credit(s)")

import os
import time

import requests


def screenshot(params, attempts=4):
    """Request a screenshot, retrying only when the API says how long to wait."""
    for attempt in range(1, attempts + 1):
        response = requests.get(
            "https://api.urlshot.io/v1/screenshot",
            params=params,
            headers={"Authorization": f"Bearer {os.environ['URLSHOT_API_KEY']}"},
            timeout=60,
        )
        if response.ok:
            return response.content

        # Only a 429 or 503 carries Retry-After, in seconds. Anything else fails
        # the same way however often it is sent.
        retry_after = response.headers.get("Retry-After")
        error = response.json()["error"]
        if retry_after is None or attempt == attempts:
            raise RuntimeError(f"{error['code']}: {error['message']} (request {error['requestId']})")
        time.sleep(int(retry_after))


image = screenshot({
    "url": "https://en.wikipedia.org/wiki/Cartography",
    "format": "webp",
})
with open("screenshot.webp", "wb") as file:
    file.write(image)
print("Wrote screenshot.webp")

import os

import requests

response = requests.get(
    "https://api.urlshot.io/v1/screenshot",
    # A list becomes the parameter repeated, once for each selector.
    params={
        "url": "https://en.wikipedia.org/wiki/Atlas",
        "full_page": "true",
        "format": "png",
        "hide_selectors": [".vector-header-container", ".mw-footer"],
    },
    headers={"Authorization": f"Bearer {os.environ['URLSHOT_API_KEY']}"},
    timeout=60,
)

# Anything that is not an image is the JSON error envelope.
if not response.ok:
    error = response.json()["error"]
    raise RuntimeError(f"{error['code']}: {error['message']} (request {error['requestId']})")

with open("atlas.png", "wb") as file:
    file.write(response.content)

import os

import requests

response = requests.post(
    "https://api.urlshot.io/v1/screenshot",
    # json= sends Content-Type: application/json, and Python's True and lists
    # as JSON's true and arrays.
    json={
        "url": "https://en.wikipedia.org/wiki/Atlas",
        "full_page": True,
        "format": "png",
        "hide_selectors": [".vector-header-container", ".mw-footer"],
        "custom_css": "#siteNotice { display: none !important }",
    },
    headers={"Authorization": f"Bearer {os.environ['URLSHOT_API_KEY']}"},
    timeout=60,
)

# Anything that is not an image is the JSON error envelope.
if not response.ok:
    error = response.json()["error"]
    raise RuntimeError(f"{error['code']}: {error['message']} (request {error['requestId']})")

with open("atlas.png", "wb") as file:
    file.write(response.content)

pip install fastapi uvicorn httpx

# app.py. Run with: uvicorn app:app
import logging
import os

import httpx
from fastapi import FastAPI, HTTPException, Response

# The pages this app shows previews of. Visitors pick a name, never an
# address: a route that took any URL would render any page on your credits.
PAGES = {
    "home": "https://example.com",
    "atlas": "https://en.wikipedia.org/wiki/Atlas",
}

app = FastAPI()

# One client for the whole app, so connections to the API are reused.
client = httpx.AsyncClient(
    headers={"Authorization": f"Bearer {os.environ['URLSHOT_API_KEY']}"},
    timeout=60,
)


@app.get("/previews/{page}")
async def preview(page: str) -> Response:
    url = PAGES.get(page)
    if url is None:
        raise HTTPException(status_code=404)

    response = await client.get(
        "https://api.urlshot.io/v1/screenshot",
        params={
            "url": url,
            "viewport_width": 1280,
            "format": "webp",
            "cache_ttl": 3600,
        },
    )
    if response.is_error:
        error = response.json()["error"]
        logging.error("%s: %s (request %s)", error["code"], error["message"], error["requestId"])
        raise HTTPException(status_code=502)

    return Response(
        content=response.content,
        media_type=response.headers["Content-Type"],
        headers={"Cache-Control": "public, max-age=3600"},
    )

import hmac, os
from hashlib import sha256
from urllib.parse import urlencode


def signed_url(**options: str) -> str:
    query = urlencode({"key": os.environ["URLSHOT_KEY"], **options})

    signature = hmac.new(
        os.environ["URLSHOT_SIGNING_SECRET"].encode(),
        query.encode(),
        sha256,
    ).hexdigest()

    return f"https://api.urlshot.io/v1/screenshot?{query}&signature={signature}"


src = signed_url(url="https://example.com", viewport_width="1200")