Hello, world!
", "block_ads": false}, {"markdown": "**Yes!**"} ] } ``` The options property contains default options that will be applied to every request. And for every request, you can specify options to override the default values. You can specify all [the regular options you use to take a single screenshot](/docs/options). You can specify the access key as a query parameter `access_key=Hello, world!
&viewport_width=1280&viewport_height=1024&block_ads=false&block_cookie_banners=true"} ] } ``` But if you requested to [execute requests](#execute-requests), the result will also contain a summary execution response for each request: ``` [ { "url": "https://api.screenshotone.com/take?url=http://example.com&viewport_width=1280&viewport_height=1024&block_ads=true", "response": { "is_successful": true, "status": 200, "statusText": "OK" } }, { "url": "https://api.screenshotone.com/take?url=https://finance.yahoo.com&viewport_width=1280&viewport_height=1024&block_ads=true&block_cookie_banners=true", "response": { "is_successful": true, "status": 200, "statusText": "OK" } }, { "url": "https://api.screenshotone.com/take?html=Hello, world!
&viewport_width=1280&viewport_height=1024&block_ads=false&block_cookie_banners=true", "response": { "is_successful": true, "status": 200, "statusText": "OK" } }, { "url": "https://api.screenshotone.com/take?markdown=**Yes!**&viewport_width=1280&viewport_height=1024&block_ads=false&block_cookie_banners=true", "response": { "is_successful": true, "status": 200, "statusText": "OK" } } ] ``` As you noticed, images are not returned, but in case of an error, the `is_successful` property will be `false`, and you can expect the `body` property to explore the error: ``` [ { "url": "https://api.screenshotone.com/take?url=http://example.com&viewport_width=1280&viewport_height=1024&block_ads=true", "response": { "is_successful": false, "status": 400, "statusText": "Bad request", body: { "error_code": "concurrency_limit_reached" "error_message": "Concurrency limit is reached" } } } ] ``` ## Execute requests Bulk screenshots are implemented in a lazy loading way. It means that the screenshot is literally taken when you tried to download it, not when you sent a bulk request. If you want to execute each request before you get a response, set the parameter `execute` to `true`: ``` POST https://api.screenshotone.com/bulk { "access_key": "| Device (id) | Viewport (scale) | Mobile | Touch | Landscape |
|---|---|---|---|---|
| User Agent | ||||
| {device.name} ({id}) | {device.viewport.width}x{device.viewport.height} ({device.viewport.deviceScaleFactor}) | {device.viewport.isMobile ? "Yes" : "No"} | {device.viewport.hasTouch ? "Yes" : "No"} | {device.viewport.isLandscape ? "Yes" : "No"} |
| {device.userAgent} | ||||
## SDKs and Code Examples
There is a set of native SDKs you can use:
* [Go](/docs/code-examples/go/)
* [Java](/docs/code-examples/java/)
* [PHP](/docs/code-examples/php/)
* [Ruby](/docs/code-examples/ruby/)
* [Python](/docs/code-examples/python/)
* [C# (.NET)](/docs/code-examples/c-net/)
* [JavaScript and TypeScript (Node.js)](/docs/code-examples/c-net/)
If your language is not supported, please, reach out to support@screenshotone.com and we will try to close it quickly. Otherwise, you can always use any HTTP client.
# Go SDK and Code Examples
import Alert from "@/components/Alert.astro";
### signature
A signature is optional. It is used for [the signed requests](/docs/signed-requests).
### html
HTML you want to render. One of the [Markdown](#markdown), [HTML](#html) or [URL](#url) parameters is required.
An example of the request URL with `html=Hello, world!
`: ``` https://api.screenshotone.com/take?html=Hello,%20world!
&access_key=
### markdown
Markdown you want to render. One of the [Markdown](#markdown), [HTML](#html) or [URL](#url) parameters is required.
An example of the request URL with `markdown=# Hello, world!` (encoded to `markdown=%23%20Hello%2C%20world!`):
```
https://api.screenshotone.com/take?html=%23%20Hello%2C%20world!&access_key=
### format
For the HTML format (`format=html`), consider including the shadow DOM elements with the [`include_shadow_dom`](#include_shadow_dom) option.
### response_type
Available response types:
- `by_format` — return exactly the response defined in the [format option](#format). If `format=png`, the response will be the binary representation of the `png` with the content type header `image/png`. **With this option (default), screenshots are not stored on ScreenshotOne servers** unless you explicitly enable [caching](#caching), [storage](#storing) options or similar.
- `empty` — return only status or error. It is suitable when you want to [upload the screenshot to storage](#storing) and don't care about the results. It also speeds up the response since there are no networking costs involved.
- `json` — A method returns the response in the JSON format, but it is only suitable if you use options that are effective for JSON. By default, the JSON response will be empty. But for example, when you use [caching](#caching), the JSON will be populated with additional data. (This option might temporarily store the rendered content on ScreenshotOne servers to serve the screenshot or other content URLs for you.)
ScreenshotOne API doesn't support the `base64` encoding format. But you can get the screenshot in the binary format and convert it to the `base64` encoding with your language of choice.
The default value is `by_format`.
An example of the request URL:
```
https://api.screenshotone.com/take?response_type=empty&url=https://example.com&access_key=
The same page without selector: ``` https://api.screenshotone.com/take?url=https://scalabledeveloper.com/posts/context-in-go/&access_key=
Setting the [selector](#selector) option changes the behavior of the [capture_beyond_viewport](#capture_beyond_viewport) option, and sets it to `true` by default.
### selector_algorithm
The default algorithm is `default` which means to use the browser tools to screenshot the element by selector. But the new algorithm `clip` allows more flexibility and better results for some cases.
E.g. if you need to screenshot the element by selector and the element is not fully visible, or it requires scrolling to screenshot the element, the `clip` algorithm will be more suitable.
An example of the API request URL with `selector_algorithm=clip`:
```
https://api.screenshotone.com/take?selector_algorithm=clip&selector=h1&url=https://example.com&access_key=
### full_page_scroll
If set to `true`, scrolls to the bottom of the page and back to the top. Default value is `false`.
When `full_page` is set to `true`, `full_page_scroll` is automatically set to `true`, until you override it. It is done to make sure that all lazy loaded images are requested and rendered.
An example of the request URL:
```
https://api.screenshotone.com/take?full_page_scroll=true&full_page=true&url=https://netflix.com&access_key=
### viewport_width
### viewport_height
### device_scale_factor
An example of the request URL with `device_scale_factor=2`:
```
https://api.screenshotone.com/take?device_scale_factor=2&url=https://apple.com&access_key=
### viewport_mobile
### image_width
The `image_width` and `image_height` parameters allow you to create a thumbnail of the screenshot.
By default `image_width` = [viewport_width](#viewport_width) and `image_height` = [viewport_height](#viewport_height).
If you specify image width and height parameters, the API will resize a screenshot, preserving the aspect ratio. The image will be resized to be as large as possible while ensuring its dimensions are less than or equal to the image width and height specified.
If you omit one of the parameters, the other is computed automatically, preserving the aspect ratio.
An example of the request with `image_width=500`:
```
https://api.screenshotone.com/take?image_width=500&url=https://example.com/&access_key=
### reduced_motion
When `reduced_motion` set to `true`, the API will request the site to minimize the amount of non-essential motion it uses. When the site supports it, it should use animations as least as possible.
An example of the request URL with `reduced_motion=true`:
```
https://api.screenshotone.com/take?reduced_motion=true&url=https://tailwindcss.com/&access_key=
### scripts_wait_until
The default value of `scripts_wait_until` is `[]` — nothing, no wait at all.
The `scripts_wait_until` option allows you to wait until a given set of events after the [scripts](#scripts) were executed. You need to use in case, if your script might trigger page reloading, like:
```javascript
window.location = "https://example.com";
```
It accepts the same values as [wait_until](#wait_until) and can have multiple values:
- `load`: the navigation is successful when the load even is fired;
- `domcontentloaded`: the navigation is finished when the DOMContentLoaded even is fired;
- `networkidle0`: the navigation is finished when there are no more than 0 network connections for at least 500 ms;
- `networkidle2`: consider navigation to be finished when there are no more than 2 network connections for at least 500 ms.
The parameter accepts many values. It means that screenshots will be taken after all events occur altogether.
An example of the request with `scripts_wait_until=networkidle2&scripts_wait_until=domcontentloaded`:
```
https://api.screenshotone.com/take?scripts_wait_until=networkidle2&scripts_wait_until=domcontentloaded&url=https://example.com/&access_key=
A screenshot without styles for comparison:
### click
Specify the CSS selector of an element to click on before taking the screenshot. It could be anything, including a button, link, or even a regular `div` element.
Supports `shadow/` selectors which will traverse the shadow DOM elements. It will be slower, and if many elements have the same selectors, the first one will be chosen.
An example of the request URL with `click=.a-some-button-class-selector`:
```
https://api.screenshotone.com/take?click=.a-some-button-class-selector&url=https://example.com&access_key=
An example of the request URL with `block_cookie_banners=false`: ``` https://api.screenshotone.com/take?block_ads=false&url=https://stackoverflow.com&access_key=
### block_banners_by_heuristics
An example of the request URL with `block_chats=false`: ``` https://api.screenshotone.com/take?block_chats=false&url=https://screenshotone.com&access_key=
### block_ads
Blocks ads. Default value is `false` when the `url` option is set..
It is useful when you want to take "clean" screenshots or don't want to generate a loss for advertisers.
An example of the request URL with `block_ads=true`:
```
https://api.screenshotone.com/take?block_ads=true&url=https://scalabledeveloper.com/posts/linux-kernel-coding-style/&access_key=
An example of the request URL with `block_ads=false`: ``` https://api.screenshotone.com/take?block_ads=false&url=https://scalabledeveloper.com/posts/linux-kernel-coding-style/&access_key=
### block_trackers
Block trackers. Default value is `false` when the `url` option is set.
It is useful when you don't want to count screenshots as client visits in your analytics app.
Set `block_trackers=true` to disable all trackers.
### block_requests
Block requests by specifying URL, domain, or even a simple pattern like `block_requests=*.example.com/*`. You can specify the parameter multiple times like `block_requests=example.com&block_requests=http://*`.
Blocking requests by URL or domain can be used to test how the site responds when resources are not available. Or it might be used to speed up page loading.
Or, as an example, another way of blocking ads and trackers with `block_requests=*.carbonads.com&block_requests=*.google-analytics.com`:
```
https://api.screenshotone.com/take?block_requests=*.carbonads.com&url=https://scalabledeveloper.com/posts/linux-kernel-coding-style/&access_key=
### block_resources
Blocks loading resources by type. Available resource types are:
- `document`
- `stylesheet`
- `image`
- `media`
- `font`
- `script`
- `texttrack`
- `xhr`
- `fetch`
- `eventsource`
- `websocket`
- `manifest`
- `other`
Blocking resources might be helpful when you need to optimize page loading speed before taking a screenshot.
You can specify multiple values as `block_resources=stylesheet&block_resources=image`:
```
https://api.screenshotone.com/take?block_resources=stylesheet&block_resources=image&url=https://screenshotone.com&access_key=
## Geolocation
### geolocation_latitude
Set geolocation latitude for the request. Both latitude and longitude are required if one of them is set.
Take a screenshot from Eiffel Tower with accuracy in 50 meters `geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=50`:
```
https://api.screenshotone.com/take?geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=50&url=https://www.infobyip.com/browsergeolocation.php&access_key=
### geolocation_longitude
Set geolocation longitude for the request. Both latitude and longitude are required if one of them is set.
Take a screenshot from Eiffel Tower with accuracy in 50 meters `geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=50`:
```
https://api.screenshotone.com/take?geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=50&url=https://www.infobyip.com/browsergeolocation.php&access_key=
### geolocation_accuracy
Set the geolocation accuracy in meters.
Take a screenshot from Eiffel Tower with accuracy in 50 meters `geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=50`:
```
https://api.screenshotone.com/take?geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=50&url=https://www.infobyip.com/browsergeolocation.php&access_key=
## Request
### ip_country_code
{" "} An example with specified user agent `user_agent=screenshoter`: ``` https://api.screenshotone.com/take?user_agent=screenshoter&url=https://www.whatsmyua.info/&access_key=
### authorization
Set the `Authorization` header for the request.
Setting the authorization header is proper when you want to take a screenshot of the protected page by basic authentication or token.
For example, if use basic authentication with credentials like `username:password`, encode it to Base64 format `dXNlcm5hbWU6cGFzc3dvcmQ=` and then use set the value of the authorization header like `authorization=Basic+dXNlcm5hbWU6cGFzc3dvcmQ=`.
Also, check our guide about [how to screenshot authenticated pages](/docs/guides/authenticated-pages/).
### cookies
Set cookies for the request in format `
### time_zone
Sets time zone for the request. Available time zones are:
- `America/Belize`
- `America/Cayman`
- `America/Chicago`
- `America/Costa_Rica`
- `America/Denver`
- `America/Edmonton`
- `America/El_Salvador`
- `America/Guatemala`
- `America/Guayaquil`
- `America/Hermosillo`
- `America/Jamaica`
- `America/Los_Angeles`
- `America/Mexico_City`
- `America/Nassau`
- `America/New_York`
- `America/Panama`
- `America/Port-au-Prince`
- `America/Santiago`
- `America/Tegucigalpa`
- `America/Tijuana`
- `America/Toronto`
- `America/Vancouver`
- `America/Winnipeg`
- `Asia/Kuala_Lumpur`
- `Asia/Shanghai`
- `Asia/Tashkent`
- `Europe/Berlin`
- `Europe/Kiev`
- `Europe/Lisbon`
- `Europe/London`
- `Europe/Madrid`
- `Pacific/Auckland`
- `Pacific/Majuro`
Default time zone is `GMT +/- 00:00`.
An example with `time_zone=Europe/Madrid`:
```
https://api.screenshotone.com/take?time_zone=Europe/Madrid&url=https://whatismytimezone.com/&access_key=
### bypass_csp
In rare cases, especially when you trying to add [custom scripts] to a website, you need to bypass the content security policies of the website. You need to simplify the set `bypass_csp` to `true`, by default it is `false`.
## Wait
These are one of the most tricky parameters when rendering screenshots of a site. Read on [how to wait until the page is ready](/blog/puppeteer-wait-until-the-page-is-ready/) if you are curious. Or use these `wait` options directly.
### wait_until
Use `wait_until` to wait until an event occurred before taking a screenshot or rendering HTML or PDF.
The default value of `wait_until` is `['load']`. Allowed values are:
- `load`: the navigation is successful when the load even is fired;
- `domcontentloaded`: the navigation is finished when the DOMContentLoaded even is fired;
- `networkidle0`: the navigation is finished when there are no more than 0 network connections for at least 500 ms;
- `networkidle2`: consider navigation to be finished when there are no more than 2 network connections for at least 500 ms.
The parameter accepts many values. It means that screenshots will be taken after all events occur altogether.
An example of the request with `wait_until=networkidle2&wait_until=domcontentloaded`:
```
https://api.screenshotone.com/take?wait_until=networkidle2&wait_until=domcontentloaded&url=https://example.com/&access_key=