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 Example: area XPath parameter to get the desired element (DOM).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)