Options
All
  • Public
  • Public/Protected
  • All
Menu

PhantomJsCloud.com Standard JSON API Documentation

This documentation is for the HTTP based Standard JSON API. For POST requests made in any programming language, (you can use GET in a pinch too)

IMPORTANT TIPS

There are some important considerations when you call a browser from an API. Here are some tips to improve your performance and get what you want.

  • LOWER YOUR COST: Use requestSettings:{"doneWhen":[{ "event":"domReady"},]} as shown in this example. That page loads in about 6 seconds, where the original without domReady loads in about 20 seconds. The difference is that we render when the browser signals domReady. Normally we wait until all resources (ads,css,images,etc) are loaded.
  • TRACK COST: View the HTTP Response Headers we send back with every api call. This includes detals such as the cost of your page and how many credits remain. See all the pjsc-billing-* headers.
  • WHAT RESOURCES FAILED TO LOAD: Some pages have resources (images, css, fonts, etc) that fail to load. Usually due to broken links. You can track this by inspecting the HTTP Response Headers. See all the pjsc-content-resource-* headers.
  • ALL METADATA ABOUT THE PAGE / PROCESSING: use the outputAsJson:true property. This will return your content and all details about load times, cookies, iFrames, sub resources, etc.
  • GET IMAGE AND HTML: choose renderType:"jpeg, outputAsJson:true. The image will be base64 encoded. The html will be shown under the main frame contents.

NEW AUTOMATION API

This api allows unparalleled control over your browser request. Using this Automation API you will be able to do the following things easily:

  • USER INPUT: Control the Keyboard, Mouse, or Touchscreen directly, as a human would.
  • MULTI-RENDERS: Render multiple screenshots or PDF's of the page, at times you decide.
  • CUSTOM LOGIC: A secure sandbox allows custom code (ES2018 javascript) execution inside your API call. This enables dynamic query/manipulation of the page. Full control over the browser.
  • PUPPETEER SCRIPTS: Puppeteer script compatibility. Currently 80% of Puppeteer API's are supported

See the New Automation API Docs for more information.

Usage

To use this API, you need to submit a GET or POST request to the API endpoint. GET requests are the simplest way of showing examples and getting started, but it is strongly suggested you use the POST endpoint for "real" usage, because GET requests have a limited length and you need to escape special characters like ?.

POST

Submit your IPageRequest as a HTTP POST request.

  • Url
    • http(s)://PhantomJsCloud.com/api/browser/v2/[YOUR-KEY]/
  • Post Body
    • [REQUEST-JSON]
    • You should not Base64 Encode, nor UrlEncode your Post Body, or any of it's parts.
  • Content Type
    • application/json

GET

Basic GET using uriComponent encoded requests

  • Endpoint Url
    • http(s)://PhantomJsCloud.com/api/browser/v2/[YOUR-KEY]/?request=[REQUEST-JSON]
  • The entirety of your [REQUEST-JSON] should be encoded via encodeURIComponent(), do not encode the parts individually.

GET using Base64 encoding

  • Endpoint Url
    • http(s)://PhantomJsCloud.com/api/browser/v2/[YOUR-KEY]/?requestBase64=[REQUEST-JSON]
  • The entirety of your [REQUEST-JSON] should be Base64 Encoded, do not encode the parts individually, and do not urlEncode before you Base64 Encode.

Input Parameters

[YOUR-KEY]

Your key used for creditBalance/billing. You can obtain this by signing up, or use the special key a-demo-key-with-low-quota-per-ip-address for testing.

[REQUEST-JSON]

The details of your request as a JSON object. This JSON can take the following form:

  • A single IPageRequest object
    • Example: {url:"http://www.example.com",renderType:"jpg",outputAsJson:true}

DEPRECATED The following Request-JSON forms are deprecated in favor of the new Automation API, but you can still use them if you need:

  • Array of IPageRequest objects. This will cause each page to be visited in order, with the last IPageRequest being rendered.
    • Example: [{url:"http://www.google.com"},{url:"https://www.google.com/doodles/",renderType:"jpg",outputAsJson:true}]
  • A IUserRequest object (Most complex: required if you want to use Proxy Servers).
    • Example: {proxy:false,pages:[{url:"http://www.google.com"},{url:"https://www.google.com/doodles/",renderType:"jpg",outputAsJson:true}]}

Default Values

While the url is required in a IPageRequest, everything else is optional. Click here to view the default values if you leave the various parameters blank

Examples

These examples use GET requests because they are the simplest way of showing examples and getting started, but it is strongly suggested you use the POST endpoint for "real" usage.

Basic Examples

Advanced Examples

Script Examples

IMPORTANT NOTE ON SCRIPTS The Script API is deprecated. While it will continue to work, we suggest you switch to The New Automation API. The Automation API is easier to use and more powerful.
Please see the Automation API Examples.

Proxy Examples

The following examples use IPageRequest.proxy which is an "easy to use shortcut" to common proxy settings.

If you want full customization of proxy settings use IProxyOptions as shown in this example:

Test Pages

These pages are used in some of the above examples, and might be useful to you when evaluating this service:

Misc

Additional Documentation

Please refer to the main Docs Index Page for Basic Troubleshooting, Testing and Performance Optimization, Usage FAQ, and language-specific samples.

Want to use Webkit instead of Chrome?

We have introduced a new rendering engine based on Chrome. It offers a superior experience to Webkit, the old rendering system. If you want to use the old webkit rendering, include backend:"webkit" in your request. Here is an example request using Webkit {pages:[{url:"http://localhost/examples/corpus/flexbox.html",renderType:"jpeg",}],backend:"webkit"} displays incorrectly.*

Recent Big Changes

  • 20210215: Upgrade underlying Chrome latest and greatly improve render speeds in some situations (upstream load/domReady on some complex pages).
  • 20190801: new Automation API released, deprecating scripts and _pjscMeta
  • 20190610: allow customizing the outputAsJson response. see IPageRequest.queryJson.
  • 20190517: add builtin proxy: static IP and anon options.
  • 20190503: big upgrade to browser-api performance. (Fixes sub-resource stalls on complex pages)

Last change

  • 20210323@1242pst

Index

Type aliases

IBackendType

IBackendType: "default" | "chrome" | "webkit" | "preview" | "webkit pjs2.1.1" | "webkit pjs2.5beta"

select the browser engine you will use

you may choose from the following shortcuts: "default", "preview", "webkit", "chrome"

default: currently points to chrome

preview: currently chrome. may change at any time as this is for testing new backends or feature enhancements.

webkit: the latest stabke version of the default PhantomJs rendering engine: webkit pjs2.1.1

chrome: the latest stable version of chrome

or choose a specific backend: chrome, webkit pjs2.1.1, webkit pjs2.5beta

IPageEventPhase

IPageEventPhase: "initialRequest" | "pageNavigated" | "domReady" | "load"

the different event phases that a page goes through

IResourceSummary

IResourceSummary: { aborted: number; active: number; complete: number; failed: number; late: number; orphaned: number }

new for Chrome backend. summary of all resources requested during the page execution, and their current status upon page completion.

Type declaration

  • aborted: number

    aborted because the resource exceeded IRequestSettings.resourceTimeout

  • active: number

    requests that were still active (but healthy) upon page completion

  • complete: number

    successfully completed resource loads

  • failed: number

    failed due to normal browser workflows

  • late: number

    requests that were still active (but took longer than IRequestSettings.resourceWait) upon page completion

  • orphaned: number

    if the browser looses track of resource request/response pairs, it will be put here (should never happen)