API Documentation

Use our simple API to capture screenshots of websites.

Making an API request

To create a screenshot, send a GET or POST request to this endpoint.

https://api.pikwy.com

Authentication

Add the token parameter with your API token to the request to authorize yourself.

https://api.pikwy.com/?token=YOUR_API_TOKEN&url=https://wikipedia.org

Parameters

This is a list of all parameters that you can add to the request. You can use long or short parameter names.

Parameter Type Default value Value range Description
token/tkn string '' '' Your API token.
url/u string '' '' The url of the website. Needs to be URL encoded.
width/w int 1280 100 - 10000 The width of the browser in pixels.
height/h int 1024 100 - 50000 The height of the browser in pixels.
full_page/fs int 0 0, 1 If 1, a screenshot will be taken over the entire height of the web page.
format/f string jpg png, jpg, html, pdf Format of the thumbnail or screenshot
response_type/rt string raw raw, json If you select json, the API will return an image encoded in base64 and additional information: response code, response headers. By default, the API returns the raw image or raw file. In case of unsuccessful response, error text.
timeout/t int 0 0 - 120000 Limits the maximum time in milliseconds for screenshot creation. If screenshot isn't created in time, API return timeout error.
delay/d int 0 0 - 60000 How many milliseconds to wait before taking the screenshot.
refresh/r int 0 0, 1 After the page is fully loaded, Pikwy waits 1 second and refreshes the page.
user_agent/ua string '' '' User variable to set your user-agent. The value have to be url encoded.
headers/hdrs string '' ''
User variable to set your headers fields. Allowed multiple headers parameters.

&headers[Referer]=https://wikipedia.org/&headers[Cache-Control]=max-age=0
&headers[Cookie]=SSID=WX84BVOEA3WEDSHJHG;SEARCH_SAMESITE=CgQI5o4B
In some cases, cookies sent using the &headers[Cookie] to certain sites are not accepted. In this case, you must use the cookie parameter below.
cookie/c string '' '' To send a cookie with one parameter:
&cookie[0][name]=is_mobile_app&cookie[0][value]=true
To send a cookie with multiple parameters:
&cookie[0][name]=is_mobile_app&cookie[0][value]=true&cookie[1][name]=city_id&cookie[1][value]=710000000&cookie[1][domain]=wikipedia.org, etc.
optional keys - “path”, “domain”, “secure”, “expiry”
area/a string '' ''
If you need to get a screenshot not of the whole page, but of a specific area on the page (picture, table, block or chart), you can specify a query in the area XPath parameter to get the desired element (DOM).
Example:
take a screenshot of only the central part of the website wikipedia.org
&area=//div[@class="central-featured"]
hide string '' ''
Using the hide option, you can hide/remove any HTML element before capturing webpage screenshot. You can hide various GDPR/cookie banners or any other elements on the web page.
Any valid CSS selectors separated by comma. More info about CSS Selector Reference.

Examples (www.wikipedia.org):
hide=.central-featured-lang will hide all elements with class="central-featured-lang" before capturing web page screenshot
hide=#js-link-box-en (correctly encoded as hide=#js-link-box-en) will hide element with id="js-link-box-en" before capturing web site screenshot
We recommend using Percent-encoding for the # character or any other reserved characters.
geo/g float 0 latitude range -90 to 90
longitude range -180 to 180
Set custom geolocation on browser.
geo=51.507351,-0.127758 (London)
jscode/js string '' '' Additional JS string to be injected into the page before take screenshot.
jscode=window.scrollBy(0,document.body.scrollHeight);
auth_type/auty string '' basic, form
If you need to take a screenshot of the closed part of the website with login and password authorization.
BASIC mode (HTTP Basic authentication):
If access to a web page is closed using HTTP Basic authentication. (apache, nginx)
auth={https|http}://{user}:{password}@{URL path}
Example:
auty=basic&auth=https://user:password@pikwy.com/login

FORM mode:
If you need to enter your username and password in the authorization form to access the web page.
available options:
auxi - XPATH request if there is an iframe on the authorization web page
auxu - XPATH request for a field with a login or email
auxp - XPATH request for a field with a password
auxb - XPATH request for the "login" button
auwt - XPATH request if you need to wait for some element before clicking on the "login" button
auth - {https|http}://{user}:{password}@{URL path}
Example for pikwy.com website with a POST request on PHP:
$tkn = 'YOUR TOKEN';
$url = 'https://api.pikwy.com/';
$data = [
    'u' => 'https://pikwy.com/billing',
    #
    'auty' => 'form',
    'auxu' => '//input[@id="la"]',
    'auxp' => '//input[@id="lb"]',
    'auxb' => '//button[@type="submit"]',
    'auth' => 'https://email:password@pikwy.com/login',
    'tkn' => $tkn,
];
#
$opts = [
    'http' => [
    'header' => "Content-type: application/x-www-form-urlencoded\r\n",
    'method' => 'POST',
    'content' => http_build_query($data)
   ]
];
$context = stream_context_create($opts);
#
$result = file_get_contents($url, false, $context); if ($result === FALSE)
{
     # Handle error
}
export_ftp/ftp string '' '' Save screenshots to FTP server.
Schema:
{ftp|sftp}://{user}:{password}@{ip|host}:{port}/{Remote Path}/
Example 1:
ftp://{user}:{password}@{ip|host}:{port}/ - save file to the root of the directory
Example 2:
ftp://{user}:{password}@{ip|host}:{port}/folder2/ - save file to /folder2/
After successful upload, a json object will be returned with the date and file name
{
"date":"1665396936",
"name":"1695796934_6343f0c0b381e6645446c668.jpg"
}
export_as3/as3 string '' '' Save screenshots to AWS S3 Bucket.
Schema:
as3://{access_key}:{secret_ket}@{region}/{bucket}/{Remote Path}/
Example 1:
as3://{access_key}:{secret_ket}@{region}/{bucket}/ - save file to the root of the directory
Example 2:
as3://{access_key}:{secret_ket}@{region}/{bucket}/folder/folder2/ - save file to /folder2/
After successful upload, a json object will be returned with the date and file name
{
"date":"1665396934",
"name":"1665396934_6343f0c0b381e6645546c668.jpg"
}
export_azu/azu string '' '' Save screenshots to Azure Blob Storage.
Schema:
{https}://{StorageAccountName}:{containerKey}@blob.core.windows.net/{containerName}/{remote path}/
{containerKey} needs to be URL encoded
Example 1:
{https}://{StorageAccountName}:{containerKey}@blob.core.windows.net/{containerName}/ - save file to the root of the directory
Example 2:
{https}://{StorageAccountName}:{containerKey}@blob.core.windows.net/{containerName}/folder/folder2/ - save file to /folder2/
After successful upload, a json object will be returned with the date and file name
{
"date":"1665396934",
"name":"1665396934_6343f0c0b381e6645546c668.jpg"
}
export_dbx/dbx string '' '' Save screenshots to Dropbox.
Schema:
dbx://{token}/{remote path}/
How to get a {token}, you can read in our article.
Example 1:
dbx://{token}/{remote path}/ - save file to the root of the directory
Example 2:
dbx://{token}/{remote path}/folder/folder2/ - save file to /folder2/
After successful upload, a json object will be returned with the date and file name
{
"date":"1665396934",
"name":"1665396934_6343f0c0b381e6645546c668.jpg"
}
proxy/p string '' ''
Connecting to a proxy server.
Proxy schema:
{http|https|socks4|socks5|socks5h}://{user}:{password}@{ip|host}:{port}

For paid subscription only:
You can use a proxy from pikwy.
proxy=ys - a random proxy will be selected from the available proxy list.
proxy=es - proxy from the specified country will be used.
Available countries: it, es, nl

Code Examples

These code examples show how to save a website screenshot to a file.

GET request

curl --request GET --url https://api.pikwy.com/ 
--header 'Content-Type: application/json' 
--data '{"u":"https://wikipedia.org","fs":0,"rt":"json","tkn":"{YOUR_API_TOKEN}"}'
How to use this function, you can read in our article. https://pikwy.com/blog/how-create-screenshot-with-google-apps-script
function captueScreenshot() {
  // Main parameters
  var websiteURL = "https://wikipedia.org";
  var apiUrl = "https://api.pikwy.com";
  var token = "YOUR TOKEN";
  var driveFolderId = "1iVbOERt6jhzPelIqGwqaVIDdfWFa16fWtdSYn"; // Google Drive Folder ID
  var spreadSheetId = "1MkAe4owv5MFvicHNfDdggRj4FeYcbXY9KD1jGwEsY"; // Google Spreadsheet ID
  var dateAndTime = new Date().toLocaleString('en-US'); ///You can change the date format by replacing en-US
  var additionalParameter = "width=1500&height=2000&delay=2000";

  ///Create a random filename
  var namelength = 30;
  var file_name = '';
  var characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
  var charactersLength = characters.length;
  for ( var i = 0; i < namelength; i++ ) {
    file_name += characters.charAt(Math.floor(Math.random() * charactersLength));
  }

  ///Send request
  var image = UrlFetchApp.fetch(apiUrl, {
		"method": "GET",
		"muteHttpExceptions": true,
		"followRedirects": true,
		"validateHttpsCertificates": true,
		"contentType": "application/x-www-form-urlencoded",
		"payload": "u="+ encodeURIComponent(websiteURL) +"&tkn="+token+additionalParameter
	}).getBlob().getAs('image/jpeg').setName(file_name);

  ///Save screenshot to Google Drive
  var folder = DriveApp.getFolderById(driveFolderId);
  var file = DriveApp.createFile(image);
  Drive.Files.update({"parents": [{"id": folder.getId()}]}, file.getId());
  var driveImageUrl = 'https://drive.google.com/file/d/' + file.getId() + '/view';

  /// Insert data into Google Spreadsheet
  var lastRow = SpreadsheetApp.openById(spreadSheetId).getActiveSheet().getLastRow();
  var insertData = [dateAndTime,screenshotUrl,driveImageUrl]
  SpreadsheetApp.openById(spreadSheetId).getActiveSheet().getRange("A"+ (lastRow+1)+":C"+(lastRow+1)).setValues([insertData]);
}
fetch("https://api.pikwy.com?u=https%3A%2F%2Fwikipedia.org&tkn=%7BYOUR_API_TOKEN%7D&fs=0", {
	"method": "GET",
})
.then(function (response) {
	console.log(response.status);
	return response.text();
}).then(function (data) {
	console.log(data);
})
.catch(function (error) {
	console.log(error.message);
});

var fs = require('fs')
var request = require('request');

// The parameters.
var token = 'YOUR_API_TOKEN';
var url = encodeURIComponent('https://www.wikipedia.org/');
var width = 1280;
var height = 1024;
var response_type = 'image';

// Create the query URL.
var query = "https://api.pikwy.com";
query += `?token=${token}&url=${url}&width=${width}&height=${height}&response_type=${response_type}`;

// Call the API and save the screenshot.
request.get({url: query, encoding: 'binary'}, (err, response, body) => {
    fs.writeFile("screenshot.png", body, 'binary', err => {
        if (err) {
            console.log(err);
        } else {
            console.log("The file was saved!");
        }
    });
});

function SiteScreenshot($token, $url, $width, $height, $response_type = 'image') {
	// Parameters.
	$token = $token; ///YOUR_API_TOKEN
	$url = urlencode($url);
	$width = $width;
	$height = $height;
	$response_type = $response_type; ///Response type: json, image

	// Create the query URL.
	$query = "https://api.pikwy.com/";
	$query .= "?token=$token&url=$url&width=$width&height=$height&response_type=$response_type";

	// Call the API.
	$image = file_get_contents($query);

	// Store the screenshot image.
	file_put_contents('./screenshot.png', $image);
}
#!/usr/bin/python3
import urllib.request
import urllib.parse

def generate_screenshot_api_url(token, options):
  api_url = 'https://api.pikwy.com/?token=' + token
  if token:
    api_url = api_url + '&url=' + options.get('url')
    api_url = api_url + '&width=' + options.get('width')
    api_url = api_url + '&height=' + options.get('height')
    api_url = api_url + '&response_type=' + options.get('response_type')
  return api_url;

token = 'YOUR_API_TOKEN'
options = {
  'url': 'https://www.wikipedia.org/',
  'width': '1280',
  'height': '2000',
  'response_type': 'image'
  }

api_url = generate_screenshot_api_url(token, options)

#
opener = urllib.request.build_opener()
urllib.request.install_opener(opener)
output = 'output.png'
urllib.request.urlretrieve(api_url, output)
require 'net/http'
require 'json'

uri = URI('https://api.pikwy.com')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

req = Net::HTTP::Get.new(uri.path, {
  'Content-Type' => 'application/json'
})

req.body = {
  "u" => "https://wikipedia.org", 
  "tkn" => "{YOUR_API_TOKEN}",
  "f" => "jpg",
  "rt" => "json"
}.to_json

res = http.request(req)
data = JSON.parse(res.body)
Imports System
Imports System.net
				
Public Module PikwyClient
	Public Sub Main()
        Dim token As String
        Dim ApiUrl As String
        Dim UrlOpt As Url_Options	
        token = "YOUR_API_TOKEN"

        UrlOpt.url = "https://www.wikipedia.org/"
        UrlOpt.width = 1280
        UrlOpt.height = 1024
        UrlOpt.response_type = "image"
		
        REM Parameters.
        ApiUrl = "https://api.pikwy.com/?token=" & token
        If token <> "" Then
            ApiUrl = ApiUrl & "&url=" & UrlOpt.url
            ApiUrl = ApiUrl & "&width=" & UrlOpt.width
            ApiUrl = ApiUrl & "&height=" & UrlOpt.height
            ApiUrl = ApiUrl & "&response_type=" & UrlOpt.response_type
        End If
		
        REM Save screenshot as an image.
        Dim Client As New WebClient
        Dim output As String = "\output.png"
		Console.WriteLine(ApiUrl)
        Client.DownloadFile(ApiUrl, output)		
		Console.WriteLine("The file was saved!")
	End Sub
End Module

Module PikwyOptions
    Public Structure Url_Options
        Public url As String
        Public width As Integer
        Public height As Integer
        Public response_type As String
    End Structure
End Module

POST request

curl --request POST --url https://api.pikwy.com/ 
--header 'Content-Type: application/json' 
--data '{"u":"https://wikipedia.org","fs":0,"rt":"json","tkn":"{YOUR_API_TOKEN}"}'
How to use this function, you can read in our article. https://pikwy.com/blog/how-create-screenshot-with-google-apps-script
function captueScreenshot() {
  // Main parameters
  var apiUrl = "https://api.pikwy.com";
  var token = "YOUR TOKEN";
  var driveFolderId = "DRIVE FOLDER ID"; // Google Drive Folder ID
  var spreadSheetId = "SPREADSHEET ID"; // Google Spreadsheet ID
  var dateAndTime = new Date().toLocaleString('en-US'); ///You can change the date format by replacing en-US
  var parsingUrlSpreadSheetId = "PARSING SPREADSHEET ID"; Spreadsheet ID with links
  var numberThreads = 10; ///The number of concurrent requests to take a screenshot. Depends on your chosen plan.

  /// Read data from Google Spreadsheet, A1 colomn
  var parsingUrlLastRow = SpreadsheetApp.openById(parsingUrlSpreadSheetId).getActiveSheet().getLastRow();
  var parsingUrls = SpreadsheetApp.openById(parsingUrlSpreadSheetId).getActiveSheet()
  .getRange("A1:A"+ parsingUrlLastRow).getValues();

  /// Preparing data for a query
  var urlsArr = [];
  for(i in parsingUrls){
    if (parsingUrls[i] != false) {
      let formData = {
		 ///Additional options for taking a screenshot
        'u': encodeURIComponent(parsingUrls[i]),
        'tkn': token,
        'f':'jpg',
        'width':'1500',
        'height':'2000'
      };
      let headersParam = {
          "url": apiUrl,
          "method": "post",
          "muteHttpExceptions": true,
          "followRedirects": true,
          "validateHttpsCertificates": false,
          "contentType": "application/x-www-form-urlencoded",
          "payload": formData};

      urlsArr.push(headersParam);
    }
  }

  var splitUrlsArr = [];
  for (let i = 0; i < urlsArr.length; i += numberThreads) {
      const chunk = urlsArr.slice(i, i + numberThreads);
      splitUrlsArr.push(chunk);
  }

  for(i in splitUrlsArr){
    var responses = UrlFetchApp.fetchAll(splitUrlsArr[i]);
    for(b in responses){
      if(responses[b].getContentText().length > 1000){
          ///Create a random filename
          var namelength = 30;
          var file_name = '';
          var characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
          var charactersLength = characters.length;
          for ( var c = 0; c < namelength; c++ ) {
            file_name += characters.charAt(Math.floor(Math.random() * charactersLength));
          }

          var image = responses[b].getAs('image/jpeg').setName(file_name);

          ///Save screenshot to Google Drive
          var folder = DriveApp.getFolderById(driveFolderId);
          var file = DriveApp.createFile(image);
          Drive.Files.update({"parents": [{"id": folder.getId()}]}, file.getId());
          var driveImageUrl = 'https://drive.google.com/file/d/' + file.getId() + '/view';

          /// Insert data into Google Spreadsheet
          var lastRow = SpreadsheetApp.openById(spreadSheetId).getActiveSheet().getLastRow();
          var insertData = [dateAndTime,decodeURIComponent(splitUrlsArr[i][b]['payload']['u']),driveImageUrl]
          SpreadsheetApp.openById(spreadSheetId).getActiveSheet().getRange("A"+ (lastRow+1)+":C"+(lastRow+1)).setValues([insertData]);
      }
    }
  }
}
fetch("https://api.pikwy.com", {
	"method": "POST",
	"headers": {
		"Content-Type": "application/x-www-form-urlencoded"
	},
	"data": JSON.stringify({"u":"https://wikipedia.org","fs":0,"rt":"json","tkn":"{YOUR_API_TOKEN}"})
})
.then(function (response) {
	console.log(response.status);
	return response.text();
}).then(function (data) {
	console.log(data);
})
.catch(function (error) {
	console.log(error.message);
});
const axios = require('axios');

const options = {
	"method": "POST",
	"url": "https://api.pikwy.com"
	"headers": {
		"Content-Type": "application/x-www-form-urlencoded"
	},
	"data": JSON.stringify({"u":"https://wikipedia.org","fs":0,"tkn":"{YOUR_API_TOKEN}"})
};

axios
   .request(options)
   .then(function (response) {
      console.log(response.data);
   })
   .catch(function (error) {
      console.error(error);
 });
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.pikwy.com/",
  CURLOPT_HTTPHEADER =>
    array(
      "Content-Type: application/x-www-form-urlencoded"
    ),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_SSL_VERIFYPEER => 0,
  CURLOPT_SSL_VERIFYHOST => 0,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => http_build_query(
    array(
          "u" => urlencode("https://www.wikipedia.org/"),
	  "tkn" => "{YOUR_API_TOKEN}",
	  "f" => "jpg"
    )
  ),
));

$result = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if($err) {
	echo "cURL Error #:" . $err;
}else {
	$json_response = json_decode($result); 
}
require 'net/http'
require 'json'

uri = URI('https://api.pikwy.com')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

req = Net::HTTP::Post.new(uri.path, { 
  'Content-Type' => 'application/json'
})

req.body = {
  "u" => "https://wikipedia.org", 
  "tkn" => "{YOUR_API_TOKEN}",
  "rt" => "json"
}.to_json

res = http.request(req)
data = JSON.parse(res.body)