- PHP
- Python
- Nodejs
- jQuery
- Go
- Ruby
Screenshot API Documentation
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.
The following documentation will provide detailed information about API usage, request parameters, responses and available endpoints. Through-out, useful examples are provided to assist you in getting started quickly and easily.
Quick Start
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)
}
}
API Access Key & Authentication
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
Parameters
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. |
API Errors
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
.
Common API Errors:
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. |
Render Modes Explained
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
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
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.
Element
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.
Code Examples
Below are code examples for a range of languages. Implementation in a language/framework that is not listed is usually as simple as using your favourite HTTP request package to make a GET or POST request and receive the response. Should you have any questions about implementation, feel free to reach out to our support team.