BaaS Quick Start

Welcome to the Browser as a Service quick start! Here are some options for connecting your scripts or using our REST APIs for common tasks:

• Connecting Puppeteer
• Connecting Playwright
• /pdf API
• /screenshot API

Bot Detection

BaaS features are best suited for sites where bot detection isn’t an issue, especially your own site. For getting past detectors, we’d recommend checking out BrowserQL.

Connecting Puppeteer

Libraries like puppeteer and chrome-remote-interface can hook into an existing Chrome instance by websocket. The hosted Browserless service only supports this type of interface since you can pass in tokens and other query-params. Typically you only need to replace how you start Chrome with a connect-like statement:

import puppeteer from "puppeteer-core";

// Connecting to Chrome locally
const browser = await puppeteer.launch();

// Connecting to Browserless and using a proxy
const browser = await puppeteer.connect({
  browserWSEndpoint: `https://production-sfo.browserless.io/?token=${TOKEN}&proxy=residential`,
});

Refer to the Puppeteer Guide to learn more.

Connecting Playwright

We support all Playwright protocols, and, just like with Puppeteer, you can easily switch to Browserless. The standard connect method uses playwright's built-in browser-server to handle the connection. This, generally, is a faster and more fully-featured method since it supports most of the playwright parameters (such as using a proxy and more).

Javascript

import playwright from "playwright";

// Connecting to Firefox locally
const browser = await playwright.firefox.launch();

// Connecting to Firefox via Browserless and using a proxy
const browser = await playwright.firefox.connect(`https://production-sfo.browserless.io/firefox/playwright?token=${TOKEN}&proxy=residential`);

Python

from playwright.sync_api import sync_playwright

# Connecting to Firefox locally
with sync_playwright() as p:
    browser = p.firefox.launch()

# Connecting to Firefox via Browserless with a proxy
with sync_playwright() as p:
    browser = p.firefox.connect_over_cdp(f"https://production-sfo.browserless.io/firefox/playwright?token={TOKEN}&proxy=residential")

Java

package org.example;

import com.microsoft.playwright.*;
import java.nio.file.Paths;

public class Main {
  public static void main(String[] args) {
    // Connecting to Firefox locally
    Browser browserLocal = playwright.firefox().launch();

    // Connecting to Firefox via Browserless and using a proxy
    String wsEndpoint = String.format(
      "wss://production-sfo.browserless.io/firefox/playwright?token=%s&proxy=residential",
      TOKEN
    );
    BrowserType.ConnectOptions connectOptions = new BrowserType.ConnectOptions();
    connectOptions.setWsEndpoint(wsEndpoint);
  }
}

C#

using System;
using System.Threading.Tasks;
using Microsoft.Playwright;

namespace PlaywrightExample
{
    class Program
    {
        public static async Task Main(string[] args)
        {
            // Connecting to Firefox locally
            using var playwright = await Playwright.CreateAsync();
            var browserLocal = await playwright.Firefox.LaunchAsync();

            // Connecting to Firefox via Browserless and using a proxy
            using var playwright = await Playwright.CreateAsync();
            string wsEndpoint = $"wss://production-sfo.browserless.io/firefox/playwright?token={TOKEN}&proxy=residential";
            var browserRemote = await playwright.Firefox.ConnectAsync(wsEndpoint);
        }
    }
}

Refer to the Playwright Guide to learn more.

/pdf API

The /pdf API allows you to navigate to any website and generate a PDF out of the page. This REST API exposes puppeteer's pdf options via an options property in the JSON body for granular control. Below you can see a basic usage example:

JSON Payload

// JSON body
{
  "url": "https://example.com/",
  "options": {
    "displayHeaderFooter": true,
    "printBackground": false,
    "format": "A0"
    // Queue the lack of a `path` parameter
  }
}

cURL

curl -X POST \
  https://production-sfo.browserless.io/pdf?token=YOUR_API_TOKEN_HERE \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/",
  "options": {
    "displayHeaderFooter": true,
    "printBackground": false,
    "format": "A0"
  }
}'

Javascript

import { writeFile } from 'fs/promises';

const TOKEN = 'YOUR_API_TOKEN_HERE';
const url = `https://production-sfo.browserless.io/pdf?token=${TOKEN}`;
const headers = {
  'Cache-Control': 'no-cache',
  'Content-Type': 'application/json'
};
const data = {
  url: "https://example.com/",
  options: {
    displayHeaderFooter: true,
    printBackground: false,
    format: "A0"
  }
};

const response = await fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
});

const buffer = await response.arrayBuffer();
await writeFile("output.pdf", Buffer.from(buffer));
console.log("PDF saved as output.pdf");

Python

import requests

TOKEN = 'YOUR_API_TOKEN_HERE'
url = f"https://production-sfo.browserless.io/pdf?token={TOKEN}"
headers = {
    "Cache-Control": "no-cache",
    "Content-Type": "application/json"
}
data = {
    "url": "https://example.com/",
    "options": {
        "displayHeaderFooter": True,
        "printBackground": False,
        "format": "A0"
    }
}

response = requests.post(url, headers=headers, json=data)

with open("output.pdf", "wb") as f:
    f.write(response.content)
print("PDF saved as output.pdf")

Java

import java.net.http.*;
import java.net.URI;
import com.google.gson.*;

public class BrowserlessPDF {
    public static void main(String[] args) {
        String TOKEN = "YOUR_API_TOKEN_HERE";
        String url = "https://production-sfo.browserless.io/pdf?token=" + TOKEN;

        HttpClient client = HttpClient.newHttpClient();

        String jsonData = new Gson().toJson(Map.of(
            "url", "https://example.com/",
            "options", Map.of(
                "displayHeaderFooter", true,
                "printBackground", false,
                "format", "A0"
            )
        ));

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/json")
            .header("Cache-Control", "no-cache")
            .POST(HttpRequest.BodyPublishers.ofString(jsonData))
            .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            System.out.println("Response: " + response.body());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

C#

using System.Text;
using System.Text.Json;

class Program
{
    static async Task Main(string[] args)
    {
        string TOKEN = "YOUR_API_TOKEN_HERE";
        string url = $"https://production-sfo.browserless.io/pdf?token={TOKEN}";

        var payload = new
        {
            url = "https://example.com/",
            options = new
            {
                displayHeaderFooter = true,
                printBackground = false,
                format = "A0"
            }
        };

        var jsonContent = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");

        using var httpClient = new HttpClient();
        try
        {
            var request = new HttpRequestMessage(HttpMethod.Post, url)
            {
                Content = jsonContent
            };

            request.Headers.Add("Cache-Control", "no-cache");

            var response = await httpClient.SendAsync(request);
            response.EnsureSuccessStatusCode();
            
            var result = await response.Content.ReadAsStringAsync();
            Console.WriteLine("Response: " + result);
        }
        catch (Exception e)
        {
            Console.WriteLine("Error: " + e.Message);
        }
    }
}

Refer to the /pdf API Guide for more details and usage examples.

/screenshot API

The /screenshot API exposes puppeteer's screenshot API through the posted JSON payload, allowing you to navigate to any website and taking a screenshot out of it. Below you can see a basic usage example:

JSON payload

// JSON body
// `options` are the options available via puppeteer's Page.screenshot() method
// (see https://pptr.dev/api/puppeteer.screenshotoptions)
{
  "url": "https://example.com/",
  "options": {
    "fullPage": true,
    "type": "png"
    // Queue the lack of a `path` parameter
  }
}

cURL

curl -X POST \
  https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/",
  "options": {
    "fullPage": true,
    "type": "png"
  }
}' \
  --output "screenshot.png"

Javascript

import fs from 'fs/promises';

const TOKEN = "YOUR_API_TOKEN_HERE";
const url = `https://production-sfo.browserless.io/screenshot?token=${TOKEN}`;
const headers = {
  "Cache-Control": "no-cache",
  "Content-Type": "application/json"
};

const data = {
  url: "https://example.com/",
  options: {
    fullPage: true,
    type: "png"
  }
};

const takeScreenshot = async () => {
  const response = await fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
  });

  const imageBuffer = await response.arrayBuffer();
  await fs.writeFile("screenshot.png", Buffer.from(imageBuffer));
  console.log("Screenshot saved as screenshot.png");
};

takeScreenshot();

Python

import requests

TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/screenshot?token={TOKEN}"
headers = {
    "Cache-Control": "no-cache",
    "Content-Type": "application/json"
}

data = {
    "url": "https://example.com/",
    "options": {
        "fullPage": True,
        "type": "png"
    }
}

response = requests.post(url, headers=headers, json=data)

with open("screenshot.png", "wb") as file:
    file.write(response.content)

print("Screenshot saved as screenshot.png")

Java

import java.io.*;
import java.net.URI;
import java.net.http.*;
import java.nio.file.*;

public class TakeScreenshot {
    public static void main(String[] args) {
        String TOKEN = "YOUR_API_TOKEN_HERE";
        String url = "https://production-sfo.browserless.io/screenshot?token=" + TOKEN;

        String jsonData = """
        {
            "url": "https://example.com/",
            "options": {
                "fullPage": true,
                "type": "png"
            }
        }
        """;

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Cache-Control", "no-cache")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonData))
            .build();

        try {
            HttpResponse<InputStream> response = client.send(request, HttpResponse.BodyHandlers.ofInputStream());
            Files.copy(response.body(), Paths.get("screenshot.png"), StandardCopyOption.REPLACE_EXISTING);
            System.out.println("Screenshot saved as screenshot.png");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

C#

using System;
using System.IO;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        string TOKEN = "YOUR_API_TOKEN_HERE";
        string url = $"https://production-sfo.browserless.io/screenshot?token={TOKEN}";

        string jsonData = @"
        {
            ""url"": ""https://example.com/"",
            ""options"": {
                ""fullPage"": true,
                ""type"": ""png""
            }
        }";

        using var client = new HttpClient();

        
        var request = new HttpRequestMessage(HttpMethod.Post, url)
        {
            Content = new StringContent(jsonData, Encoding.UTF8, "application/json")
        };

        
        request.Headers.Add("Cache-Control", "no-cache");

        try
        {
            var response = await client.SendAsync(request);
            response.EnsureSuccessStatusCode();

            var imageBytes = await response.Content.ReadAsByteArrayAsync();

            await File.WriteAllBytesAsync("screenshot.png", imageBytes);

            Console.WriteLine("Screenshot saved as screenshot.png");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}

Refer to the /screenshot API Guide for more details and usage examples.

What's Next?

BaaS provides a wide range of functionalities that help your web scraping process. To discover all the capabilities Browserless has to offer, start with the following guides:

• Hosted Services
• HTTP APIs
• Connecting Different Libraries

Advanced Features

Learn about more advanced features that you can take advantage when using BaaS:

• Human-in-the-Loop Automations
• Browser Reconnects
• Screencasting
• Live debugger