PhantomJsCloud.com HTTP Endpoint API Client Library Documentation

This documentation is for the HTTP Endpoint. For GET and POST requests.

Using Curl, C#, PHP, Python, or Node.js?

For API Libraries and Examples in these or other languages, refer to the Docs Index Page

Important Notice: Chrome upgrade

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.

Examples! (Quick Start)

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:

• Minimal GET Request, output as JPEG. Use png if you need transparency (if the backgrounds are weirdly black)
• Minimal GET Request, output as PDF. *PDF's can use CSS @media:print directives if you set IRenderSettings.emulateMedia, but we default to @media:screen for improved compatibility *
• Minimal GET Request, output as JSON.See the output pageResponse.pageRequest for the default values to other parameters.
• Minimal GET Request, sent Base64 Encoded

Advanced Examples:

• New Backend: Use Chrome! Render a PDF using Chrome. The same page rendered in Webkit displays incorrectly.
• Image: Zoom page Same as using the zoom (Ctrl +) feature in Chrome
• Image: select image *runs the CSS Selector and clips the output to the dimensions of the img tag. For more info on using selectors, see IRenderSettings.selector(https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors)
• Image: Render page as thumbnail Sets viewport to 640px width, zooms out, and sets a 640x500 clipRectangle to generate a thumbnail image of the CNN.com website.
• Render Dynamic Content Upload html and render it as if it were loaded from a URL
• Resource Modifier: Change Resource URL using parts of original url The target domain www.highcharts.com has been replaced with wikipedia.org but the path is preserved. read the text of the output error message to see this.
• Resource Modifier:JPG of Amazon.com with CSS blacklisted Note the use of the clearCache:true parameter. This is required so that .css resources are re-requested and blocked.
• Cookies:Set 2 Cookies and view results as JSON See the cookies in the output pageResponses.cookies property.
• Metadata:Return ALL possible data as JSON: Headers, IFrames, etc. Note the use of the clearCache:true parameter. This is required so that all resources are re-requested so headers are populated.
• Headers:Set Request Headers, output as HTML See the Hello:world and Accept-encoding:tacos values in the resulting HTML. Uses our example show request details page
• PDF: Generate an Invoice PDF from a webpage
• PDF: Generate a PDF programatically
• PDF: Generate a single pdf page with all the browser page's contents in it. Useful for sending long form information to customers for their reference/storage
• PDF: Generate a PDF, override using the @media:print css rule. Render a PDF using @media:print. The same page rendered with the default @media:screen type displays differently.
• doneWhen: Render at DomReady By Default PhantomJsCloud waits for all resources to load before rendering. Rendering at DomReady is much faster but depending on the site may be less accurate.
• Scripts: Set ClipRectangle at runtime Set your ClipRectangle to be a domElement, determined by CSS Selector. For more info on using selectors, see This Mozilla page.
• Scripts: Execute arbitrary Javascript that modifies the page See the added "Hello World!" text at the bottom of the page.
• Scripts: LazyLoad then force render Scrolls 50px every 50ms, and renders when done scrolling to the bottom. This tv2.dk site lazy loads images only when it's shown in the browser, so if you take a screenshot without the provided script, the bottom part will be missing images. Important: This page takes aprox 25 seconds to load, and weighs aprox 2mb in size. (Costs about 0.0047 credits)
• Scripts: Highlight text: Load 3rd party script, then Execute arbitrary Javascript See the yellow highlights of the term "Example".
• Scripts: return custom JSON based on script output (Custom Endpoint) This is a very powerful technique, allowing you to construct your own custom API using PhantomJs Cloud to process a webpage. Simply have your script return JSON you want displayed.
• Scripts: return values set by Google Tag Manager (Custom Endpoint) A practical example, showing how to extract the values set by GTM at runtime
• Scripts: inject an external script and return custom JSON from it Inject Script files from your server
• Fonts: render Chinese Mandarin
• Fonts: render a page with popular system fonts not usually found on Linux
• Fonts: any WebFont
• JSONP simple request Be sure to set outputAsJson:true or you will not get usable results
• POST data to the target Url This uses the urlSettings parameter to set the application/json content-type and submit POST data. Check the payload section of the output results.
• PROXY: Use a 3rd Party Proxy Server *You can use your own custom proxy servers or those from services like proxylist.hidemyass.com. When you use proxy servers, be aware that requests will be slower, so consider setting the resourceTimeout parameter like this example does. We will be developing our own proxy service in the coming months.

Other Examples: See the Docs Index Page Usage FAQ for other examples (such as Page Automation / Button Clicking)

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

• /examples/helpers/requestdata outputs details about the request such as POST body, request headers, mime type, etc.
• /examples/helpers/statusCode/${statusCode} a page that returns the statusCode you supply in the url. Examples: 200, 404, 503.
• /examples/helpers/pageRequestDefaults returns the default parameters used in a IPageRequest.
• /examples/corpus/ a selection of pages that can be used for rendering tests.

Usage

To use this API, you need to submit a GET or POST request to the API endpoint:

GET:

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.

• Url (uriComponent encoded requests)
  • 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.
• Url (base64 encoded requests)
  • http(s)://PhantomJsCloud.com/api/browser/v2/[YOUR-KEY]/?requestBase64=[REQUEST-JSON] \t- The entirety of your [REQUEST-JSON] should be Base64 Encoded, do not encode the parts individually, and do not urlEncode before you Base64 Encode.

POST:

• 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

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 one of the following three forms, each of which are described here:

• A single IPageRequest object (the simplest approach)
  • Example: {url:"http://www.example.com",renderType:"jpg",outputAsJson:true}
• 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}]}

IPageRequest Default Values

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

CORS/JSONP (Browser API Support)

You can use CORS (preferred) or JSONP to integrate api calls from PhantomJs Cloud directly into your webpage.

• CORS: All endpoint are CORS enabled by default.
• JSONP: To obtain results in JSONP format, add the ?callback=CALLBACK_FUNCTION_NAMEquerystring to your request (for either GET or POST requests). You MUST set outputAsJson:true for JSONP to work. Here is an example JSONP simple request.

Additional Documentation

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