The Clearshot Screenshot API has been built from the ground up to provide a simple, reliable, cost-effective and fast API that any developer/company can use to take perfect website screen captures. Included are a range of features to customize your requests to suit your use case.
To get started fast, here are some examples you can use/test. You’ll need to get a token here.
curl https://app.clearshotapi.com/api/screenshot? \
url=https://apple.com \
&response_type=image \
&access_token=__YOUR_ACCESS_TOKEN__
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://app.clearshotapi.com/api/screenshot/",
CURLOPT_HTTPHEADER =>
array(
"Authorization: Bearer [-- YOUR ACCESS TOKEN HERE --]",
"Accept: application/json"
),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => http_build_query(
array(
"url" => "https://apple.com",
"json" => "true"
)
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
$json_response = json_decode($response);
}
import requests
import json
headers = {
"Authorization": "Bearer [-- YOUR ACCESS TOKEN HERE --]",
"Accept": "application/json"
}
payload = {
"url": "https://apple.com",
"json": "true"
}
url = 'https://app.clearshotapi.com/api/screenshot'
response = requests.post(url, headers = headers, params = {}, data = json.dumps(payload))
response.raise_for_status()
response.json()
var request = require("request");
var options = {
method: "POST",
url: "https://app.clearshotapi.com/api/screenshot",
headers: {
"Authorization": "Bearer [-- YOUR ACCESS TOKEN HERE--]",
"Accept": "application/json"
},
json: true,
form: {
"url": "https://apple.com",
"json": "true"
}
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
var data = body;
});
package main
import (
"encoding/json"
"net/http"
"bytes"
)
type ScreenshotCaptureResult struct {
Image string `json:"image,omitempty"`
Width string `json:"width,omitempty"`
Height string `json:"height,omitempty"`
RemoteStatus string `json:"remote_status,omitempty"`
Cached bool `json:"cached,string,omitempty"`
URL string `json:"url,omitempty"`
}
func main() {
payload := []byte(`{"url":"https://apple.com","json":"true"}`)
client := &http.Client{}
req, err := http.NewRequest("POST", "https://app.clearshotapi.com/api/screenshot", bytes.NewBuffer(payload))
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer [-- YOUR ACCESS TOKEN HERE --]")
req.Header.Set("Accept", "application/json")
resp, err := client.Do(req)
if err != nil {
panic(err)
}
var result ScreenshotCaptureResult
err = json.NewDecoder(resp.Body).Decode(&result)
if err != nil {
panic(err)
}
}
Clearshot provides API access through HTTPS GET and POST endpoints.
All calls to the API need to be authorized using a valid access token which can be managed on the Clearshot admin panel.
For GET requests, the access token should be passed via the query string. Here is an example:
For POST requests, the access token should be passed in the header data.
GET https://app.clearshotapi.com/api/screenshot?access_token=YOUR_ACCESS_TOKEN&url=https://apple.com
Listed below are the available parameters for the screenshot API.
To use a parameter, include the parameter and a value in the query string or POST data.
Here’s an example with providing viewport sizing parameters in a GET request:
GET https://app.clearshotapi.com/api/screenshot?height=1080&width=1920&access_token=YOUR_ACCESS_TOKEN
| Parameter | Default | Description |
|---|---|---|
| access_token (required) | A valid API access token is required to make requests. You can manage your access tokens in the admin panel. | |
| url (required) | The complete URL including protocol of the web page you want to capture. | |
| mode | fullpage | Choose the capture mode. Either fullpage, viewport or element |
| height | 1080 | The height in pixels of the viewport to capture. This is ignored if mode parameter is set to full_page. |
| width | 1920 | The width in pixels of the viewport to capture. |
| response_type | image | Choose a response type. image will return an image type response which you can save directly. json will provide a json response with HTTP status code and a hosted image link. This image should be saved immediately as images are deleted after a pre-determined time period. (Usually 30 days). A json type responsed will contain image, url and remote_status. Image is the URL of the hosted screenshot. URL is the URL of the captured page. Remote_status is the HTTP response code received from the target URL. |
| format | jpeg | The format of the image captured. Chose either jpeg or png. |
| delay | 0 | The delay in seconds (after page load) to wait before capturing a screenshot. Choose from 0 to 10 seconds (maximum). |
| file_name | You can provide a filename which will be used when storing the screenshot. | |
| user_agent | Set a User Agent header to be used when capturing a screenshot, to emulate a device or browser type. Ensure the User Agent string is URL encoded to be used correctly. You can find a list of user agents sorted by device/software/layout engine here. | |
| block_ads | false | Blocks common advertising networks to prevent ads from being captured in screenshots. Set this to true or false. |
| accept_lang | Set the Accept Language header on requests to the target page to capture screenshots in the specified language. More information is available here. | |
| grayscale | false | Apply a grayscale filter to the captured screenshot. |
| js | Javascript string to be injected onto the target page. The string must be URL encoded to be properly parsed and injected. | |
| css | CSS styling string to be injected onto the target page. The string must be URL encoded to be properly parsed and injected. |
If an API request fails, an HTTP error code will be returned. The error codes below provide a description of why the error occurred.
For successful API requests, you can expect the HTTP code 200.
| Code | Type | Description |
|---|---|---|
| 400 | bad_request | Invalid parameters or the target URL provides an error. |
| 401 | unauthorized | An invalid API access key was supplied. |
| 429 | usage_limit_reached | The given user account has reached its monthly allowed request volume. |
| 403 | function_access_restricted | The given API endpoint is not supported on the current subscription plan. |
| 500 | internal_error | An internal error occurred. |
The mode parameter allows you to define the size of the screenshot you will be capturing. Below we’ll run through the 2 different modes and how they operate.
Full page or fullpage as the mode parameter value is the default mode.
As the name suggests, this mode captures a screenshot of the entire target page. The height of the image is determined by the page length. Whilst height is automatic, you can pass a width parameter to determine the width of the page capture.
When capturing full page screenshots, we recommend using the jpeg format (instead of png) to avoid very large file sizes and slower image loading performance.
Viewport mode restricts the render sizing to a specified set of dimensions. To enable viewport capture mode, set mode to the value: viewport.
The viewport dimensions (in pixels) are passed to the API via the width and height parameters.
The default viewport size is 1280×1024.
Note that when providing viewport dimensions, this will affect the webpage render sizing and can trigger responsive breakpoints in the target URLs styling. As a result, the returned image may not always be the exact size of the dimensions passed in the request.
This mode allows you to capture a specific element on the page. To specify what element you wish to capture, simply set your mode to element and provide a CSS selector to element_selector.
The default viewport for element capture is 1280x1024px.
© Clearshot API 2023, All Rights Reserved
Made with ❤️ in 🇬🇧