Introduction

The 24Browser API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns image or JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

24Browser uses API keys to allow access to the API. You can get an API key by sign up 24Browser.

24Browser expects the API key to be included in all API requests to the server in a request parameter named apiKey.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Parameters

Parameter Default Description
apiKey
string
required
API Key to use API.
url
string
required
URL to screenshot. The url should include scheme, e.g. https://.
ttl
integer
86400 Number of seconds where the screenshot will be cached.
fresh
boolean
false Force to generate screenshot even there is existing cached one.
fullPage
boolean
false When true, takes a screenshot of the full scrollable page.
scrollPage
boolean
false When true, scroll entire page before generate screenshot.
width
integer
1920 Page width in pixels.
height
integer
1080 Page height in pixels.
format
string
jpeg Specify screenshot type, can be either jpeg or png.
quality
integer
80 The quality of the image, between 0-100.
Only applicable to jpeg image format.
transparent
boolean
false Hides default white background and allows capturing screenshot with transparency.
Only applicable to png image format.
deviceScaleFactor
float
1 Specify device scale factor (can be thought of as dpr).
userAgent
string
User agent used to generate screenshot.
acceptLanguage
string
en-US Accept language used to generate screenshot.
timeZone
string
UTC TimeZone used to generate screenshot.
latitude
float
Latitude used to generate screenshot.
longitude
float
Longitude used to generate screenshot.
accuracy
float
Accuracy used to generate screenshot.
Only applicable if both latitude and longitude are specified.
css
string
Inject custom CSS before generate screenshot.
js
string
Inject custom JavaScript before generate screenshot.
delay
integer
Delay in seconds before generate screenshot.
waitFor
string
CSS selector used to wait for before generate screenshot.
element
string
CSS selector used to generate element screenshot.
mediaType
enum
screen CSS media type used to generate screenshot, can be either screen or print.
proxy
string
Route all request through proxy.
noAds
boolean
false When set to true, block ads before generate screenshot.
noTrackers
boolean
false When set to true, block trackers before generate screenshot.
noCookieBanners
boolean
false When set to true, block cookie banners before generate screenshot.

Errors

24Browser uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with 24Browser's servers (these are rare).

The 24Browser API uses the following error codes:

Error Code Description
200 OK - Everything worked as expected.
400 Bad Request - The request was unacceptable, often due to missing a required parameter.
401 Unauthorized - No valid API key provided.
402 Request Failed - The parameters were valid but the request failed.
403 Forbidden - The API key doesn't have permissions to perform the request.
404 Not Found - The requested resource doesn't exist.
429 Too Many Requests - Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 Server Error - We had a problem with our server. Try again later.

Examples

Bash

apiKey="e8746a84-844f-4ed4-afa7-83d13f59109b"
url="https://example.com"

curl --request GET --url "https://api.24browser.com/v1/screenshots?apiKey=${apiKey}&url=${url}" > screenshot.jpeg

C#

using System.Net;

public class ApiExample
{
    private const string ApiEndpoint = "https://api.24browser.com/v1/screenshots";

    public static void Main ()
    {
        using(var webClient = new WebClient())
        {
            var parameters = System.Web.HttpUtility.ParseQueryString(string.Empty);
            parameters["apiKey"] = "e8746a84-844f-4ed4-afa7-83d13f59109b";
            parameters["url"] = "https://example.com";

            webClient.DownloadFile(ApiEndpoint + "?" + parameters, "screenshot.jpeg");
        }
    }
}

Go

package main

import (
	"io"
	"net/http"
	"os"
)

func main() {

	ApiEndpoint := "https://api.24browser.com/v1/screenshots"
	request, _ := http.NewRequest("GET", ApiEndpoint, nil)
	query := request.URL.Query()
	query.Add("apiKey", "e8746a84-844f-4ed4-afa7-83d13f59109b")
	query.Add("url", "https://example.com")
	request.URL.RawQuery = query.Encode()

	client := &http.Client{}
	response, _ := client.Do(request)
	defer response.Body.Close()

	image, _ := os.Create("screenshot.jpeg")
	io.Copy(image, response.Body)
	image.Close()

}

Java

import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.URL;

public class Main {

    private static String API_KEY = "e8746a84-844f-4ed4-afa7-83d13f59109b";
    private static String API_ENDPOINT = "https://api.24browser.com/v1/screenshots";

    public static void main(String[] args) throws Exception {

        URL url = new URL(String.format("%s?apiKey=%s&url=https://example.com", API_ENDPOINT, API_KEY));
        InputStream inputStream = url.openStream();
        OutputStream outputStream = new FileOutputStream("screenshot.jpeg");

        byte[] b = new byte[2048];
        int length;

        while ((length = inputStream.read(b)) != -1) {
            outputStream.write(b, 0, length);
        }

        inputStream.close();
        outputStream.close();
    }
}

NodeJS

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

const api_endpoint = 'https://api.24browser.com/v1/screenshots';
const parameters = {
    apiKey:'e8746a84-844f-4ed4-afa7-83d13f59109b',
    url: 'https://www.google.com'
};
const output = 'screenshot.jpeg';

const download = (parameters, path, callback) => {
    request.head(api_endpoint, (err, res, body) => {
        request({uri: api_endpoint, qs: parameters})
            .pipe(fs.createWriteStream(path))
            .on('close', callback);
    });
};

download(parameters, output, () => {
    console.log('Done!');
});

PHP

<?php

$params = http_build_query(array(
    "apiKey" => "e8746a84-844f-4ed4-afa7-83d13f59109b",
    "url" => "https://example.com",
));
$output="screenshot.jpeg";
$image_data = file_get_contents("https://api.24browser.com/v1/screenshots?" . $params);
file_put_contents(output, $image_data);

?>

Python

import requests # to get image from the web
import shutil # to save it locally

api_endpoint = 'https://api.24browser.com/v1/screenshots'
payload = {
    'apiKey': 'e8746a84-844f-4ed4-afa7-83d13f59109b',
    'url': 'https://www.google.com'
}
output = 'screenshot.jpeg'

# Open the url image, set stream to True, this will return the stream content.
response = requests.get(api_endpoint, params=payload, stream=True)

# Check if the image was retrieved successfully
if response.status_code == 200:
    # Set decode_content value to True, otherwise the downloaded image file's size will be zero.
    response.raw.decode_content = True

    # Open a local file with wb ( write binary ) permission.
    with open(output, 'wb') as file:
        shutil.copyfileobj(response.raw, file)

    print('Image successfully Downloaded: ', output)
else:
    print('Image Could\'t be retrieved')

Ruby

require "open-uri"

File.open('screenshot.jpeg', 'wb') do |fo|
  params = URI.encode_www_form("apiKey" => "e8746a84-844f-4ed4-afa7-83d13f59109b",
                               "url" => "https://example.com")
  fo.write open("https://api.24browser.com/v1/screenshots?" + params).read
end