Convert a website URL to PDF with Node.js and Python

To turn a website URL into a PDF, ask ScreenshotOne for format=pdf and save the response bytes to a file. The page is rendered in a real browser, including content added by JavaScript. For pages that load data later, you may need to wait for a selector or another readiness signal before rendering the PDF.

The scripts below produce an A4 document with margins, which suits most reports and archives. If you need something closer to what you see on screen, or one long page instead of several sheets, see Choose the PDF layout.

Need just one file? The URL-to-PDF tool is quicker. The code is for when PDFs are part of your product: exports, reports, or archiving. More on that on the PDF API page.

Before you start

• Node.js 22+ or Python 3.10+. Both scripts use only the standard library, so there’s no browser or SDK to install.
• A ScreenshotOne access key in the SCREENSHOTONE_ACCESS_KEY environment variable. The scripts send it in the X-Access-Key header. You don’t need the signing secret for server-side requests like these unless you’ve turned on mandatory signing in your account.
• A URL that opens without logging in. The rendering browser doesn’t have your cookies.

Node.js

Save this as url-to-pdf.mjs:

1
import { writeFile } from "node:fs/promises";
2

3
const accessKey = process.env.SCREENSHOTONE_ACCESS_KEY;
4
const [inputUrl, outputPath = "website.pdf"] = process.argv.slice(2);
5

6
if (!accessKey || !inputUrl) {
7
    throw new Error(
8
        "Set SCREENSHOTONE_ACCESS_KEY, then run: node url-to-pdf.mjs URL [output.pdf]"
9
    );
10
}
11

12
const response = await fetch("https://api.screenshotone.com/take", {
13
    method: "POST",
14
    headers: {
15
        "Content-Type": "application/json",
16
        "X-Access-Key": accessKey,
17
    },
18
    body: JSON.stringify({
19
        url: new URL(inputUrl).href,
20
        format: "pdf",
21
        pdf_paper_format: "a4",
22
        pdf_margin: "12mm",
23
        pdf_print_background: true,
24
        media_type: "print",
25
    }),
26
    signal: AbortSignal.timeout(120_000),
27
});
28

29
if (!response.ok) {
30
    throw new Error(`PDF request failed: HTTP ${response.status}`);
31
}
32

33
const pdf = Buffer.from(await response.arrayBuffer());
34
if (pdf.subarray(0, 5).toString() !== "%PDF-") {
35
    throw new Error("The response isn't a PDF; nothing was written.");
36
}
37

38
await writeFile(outputPath, pdf);
39
console.log(`Saved ${outputPath} (${pdf.length} bytes)`);

Run it:

1
node url-to-pdf.mjs 'https://example.com/' example.pdf

The response body is the PDF, so there’s no JSON or base64 to decode. The %PDF- check is cheap insurance: if something goes wrong, you get an error instead of a .pdf file that won’t open.

Python

Save this as url_to_pdf.py:

1
import json
2
import os
3
import sys
4
from pathlib import Path
5
from urllib.error import HTTPError, URLError
6
from urllib.request import Request, urlopen
7

8

9
def main():
10
    access_key = os.environ.get("SCREENSHOTONE_ACCESS_KEY")
11
    if not access_key or len(sys.argv) not in (2, 3):
12
        raise SystemExit(
13
            "Set SCREENSHOTONE_ACCESS_KEY, then run: "
14
            "python3 url_to_pdf.py URL [output.pdf]"
15
        )
16

17
    target = sys.argv[1]
18
    output = Path(sys.argv[2] if len(sys.argv) == 3 else "website.pdf")
19

20
    payload = {
21
        "url": target,
22
        "format": "pdf",
23
        "pdf_paper_format": "a4",
24
        "pdf_margin": "12mm",
25
        "pdf_print_background": True,
26
        "media_type": "print",
27
    }
28
    request = Request(
29
        "https://api.screenshotone.com/take",
30
        data=json.dumps(payload).encode("utf-8"),
31
        headers={
32
            "Content-Type": "application/json",
33
            "X-Access-Key": access_key,
34
        },
35
        method="POST",
36
    )
37

38
    try:
39
        with urlopen(request, timeout=120) as response:
40
            pdf = response.read()
41
    except HTTPError as error:
42
        raise SystemExit(f"PDF request failed: HTTP {error.code}") from None
43
    except (URLError, TimeoutError) as error:
44
        raise SystemExit(f"PDF request didn't complete: {error}") from None
45

46
    if not pdf.startswith(b"%PDF-"):
47
        raise SystemExit("The response isn't a PDF; nothing was written.")
48

49
    output.write_bytes(pdf)
50
    print(f"Saved {output} ({len(pdf)} bytes)")
51

52

53
if __name__ == "__main__":
54
    main()

Run it:

1
python3 url_to_pdf.py 'https://example.com/' example.pdf

Both scripts hold the whole PDF in memory before writing it. That’s fine for normal pages. If you’re archiving thousands of large documents, have the API upload them straight to S3-compatible storage instead.

Choose the PDF layout

These options make the biggest difference to the result:

For a paginated document, set the paper format explicitly instead of relying on the default. For one long page with pdf_fit_one_page: true, remove pdf_paper_format from the examples and set pdf_margin: "0" so a fixed paper size or margins don’t interfere with the calculated page dimensions. The full list is in the PDF options reference.

The media_type choice surprises people the most. Many sites ship print CSS that hides the navigation, swaps colors, and adds page breaks. That often gives you a better document, even though it doesn’t look like the browser tab. If you want a visual record of the page as people see it, use screen.

Also, full_page=true is a screenshot option and doesn’t apply to PDFs. Use the pdf_* options above.

Wait for the content

If your PDF shows an empty dashboard or a spinner, the capture happened before the data loaded. Tell the API what “ready” looks like:

1
{
2
    "wait_for_selector": "[data-report-ready]",
3
    "delay": 1
4
}

A fixed delay on its own is a guess. A selector that only appears once the data is in works much better when load times vary. Charts, fonts, and images all finish at different moments, so open the exported file and check it. Don’t assume the page’s load event means the report is done.

If you control the page, a bit of print CSS goes a long way. Use break-inside: avoid on cards and table rows so they don’t split across pages, and add explicit breaks between sections. Just don’t put break-inside: avoid on anything taller than a page, because it can’t fit anywhere.

When the PDF looks wrong

If you add retries, only retry failures that can recover, such as temporary network or rendering errors. Retrying a bad key or an invalid option won’t fix anything.

Related guides

• Running your own browser? See the Puppeteer PDF guide.
• Converting HTML strings or templates instead of URLs? See HTML to PDF in JavaScript.