Skip to content

Go Website Screenshot: Viewport, Full Page, or Element

A screenshot request in Go is an ordinary HTTP GET whose query string tells the rendering service what to capture.

OUTPUT FORMATSHTMLJSONMarkdown

The same client code can return a visible-viewport image, a full-page image, or a single element image; the difference is which capture parameter you add. This guide shows the request shape, the viewport defaults, and how to save the returned image bytes to a file.

Choose the capture mode first

Three capture parameters cover the common cases. Add exactly one of them to the request query string:

  • screenshot set to true or false captures the visible portion of the page.
  • screenshot_full_page set to true or false captures the whole page.
  • screenshot_selector set to a CSS selector captures the matching element.

If you want the footer of a page, for example, use screenshot_selector="footer". If you want everything below the fold, use the full-page parameter. If you want the first screen a visitor sees, use the plain screenshot parameter.

Use this decision table before writing code:

What you needParameter to addNotes
First visible screenscreenshot=trueImage size follows the viewport
Entire page including footerscreenshot_full_page=trueResult can be very tall
One HTML elementscreenshot_selector=<CSS selector>Selector must match an element
Different viewport sizewindow_width and window_heightDefaults are 1920px by 1080px

Keep the capture choice separate from the viewport choice. Viewport settings change the canvas; capture settings change what is included in the image.

Viewport defaults and how to change them

The renderer starts with a viewport of 1920px wide and 1080px high. That default explains why a plain screenshot shows only the top of a long page: the image is limited to the visible viewport, not the document height.

To change the canvas, add window_width and window_height to the same request. Setting them to 1280 and 720 produces a 1280x720 image. These two parameters are independent of the capture mode, so you can combine a custom viewport with a full-page or element capture.

A useful check: if the image looks cropped at the bottom, confirm whether you used screenshot instead of screenshot_full_page. If the image is the wrong shape, check the viewport values.

Request shape in Go

The client workflow is the same for every capture mode:

  1. Build a GET request to the API endpoint.
  2. Add api_key and url to the query string.
  3. Add the capture parameter and any viewport parameters.
  4. Send the request with http.Client.
  5. Check that the response status is 200 before reading the body.
  6. Read the body bytes and write them to a .png file.

The exact request construction, query encoding, error handling, and file-writing code are supplied in the protected code modules code0001, code0002, code0003, and code0004. Those modules are the authoritative implementation for this page; do not retype or paraphrase their field names or numeric values.

One practical detail: the response body is binary image data, not text. Read it with io.ReadAll and write the bytes directly to the file. Do not decode it as a string.

Distinguish the three failure points

A screenshot request can fail at three different stages, and each stage needs a different fix:

  • Request build failure: the URL or query could not be constructed. Check the endpoint and parameter names.
  • HTTP response failure: the service returned a non-200 status. Check the API key, target URL, and capture parameter values.
  • Local file failure: the request succeeded but the file could not be created, written, or closed. Check the output path and disk permissions.

Separating these stages in your error messages makes debugging much faster than a single generic error. The supplied code modules already return distinct messages for each stage.

Pre-flight checklist

Before running the request, confirm:

  • [ ] The API key is set in the request query.
  • [ ] The target URL is the page you want to capture.
  • [ ] Exactly one capture parameter is present: screenshot, screenshot_full_page, or screenshot_selector.
  • [ ] If using screenshot_selector, the CSS selector matches an element on the page.
  • [ ] If a custom size is needed, both window_width and window_height are set.
  • [ ] The output file path ends in .png and is writable.
  • [ ] The response status is checked before reading the body.

After running, verify the image dimensions match the viewport you set, and that the captured region matches the parameter you chose.

Frequently asked questions

Why does my screenshot stop before the footer?

A plain screenshot request captures only the visible viewport, which defaults to 1920x1080. Content below that height is not included. Use screenshot_full_page=true to capture the whole document, or increase window_height if you only need a taller visible area.

What happens if the CSS selector does not match anything?

The request still goes to the service, but the element capture cannot produce the intended image. Confirm the selector against the rendered page, not just the HTML source, because client-side rendering can change which elements exist.

Can I combine a custom viewport with an element screenshot?

Yes. window_width and window_height control the viewport, while screenshot_selector controls which element is captured. They are separate query parameters and can be sent together.

How should I save the response body?

The body is binary image data. Read it with io.ReadAll and write the bytes directly to a file with a .png extension. Do not treat the body as text.