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.
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:
screenshotset totrueorfalsecaptures the visible portion of the page.screenshot_full_pageset totrueorfalsecaptures the whole page.screenshot_selectorset 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 need | Parameter to add | Notes |
|---|---|---|
| First visible screen | screenshot=true | Image size follows the viewport |
| Entire page including footer | screenshot_full_page=true | Result can be very tall |
| One HTML element | screenshot_selector=<CSS selector> | Selector must match an element |
| Different viewport size | window_width and window_height | Defaults 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:
- Build a GET request to the API endpoint.
- Add
api_keyandurlto the query string. - Add the capture parameter and any viewport parameters.
- Send the request with
http.Client. - Check that the response status is 200 before reading the body.
- Read the body bytes and write them to a
.pngfile.
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, orscreenshot_selector. - [ ] If using
screenshot_selector, the CSS selector matches an element on the page. - [ ] If a custom size is needed, both
window_widthandwindow_heightare set. - [ ] The output file path ends in
.pngand 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.