How to Screenshot using Clearshot API

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

PHP

Python

Node/JS

CURL

				
					curl https://app.clearshotapi.com/api/screenshot? \
url=https://apple.com \
&response_type=image \
&access_token=__YOUR_ACCESS_TOKEN__

PHP

				
					$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);
}

Python

				
					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()

Node/JS

				
					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

Important Please ensure you keep your access token safe from unauthorized access. If you think that someone else is using your access token, you should generate a refresh token in the Clearshot panel.

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

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

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.