Url to PDF

Convert any URL to a PDF using a publicly accessible webpage URL or one behind basic authentication or cookie authentication using our authentication mechanisms.

Endpoints

GET /url/pdf

Supports simple requests with only two parameter options.

url (required)
timeout (optional)

GET /url/pdf

https://api.cloudlayer.io/v2/url/pdf?url={url}&timeout={timeout}

POST /url/pdf

Supports all parameters being passed into request as JSON. The following parameter types are supported:

Url Parameters
Batch Url Parameters
Base Parameters
Pdf Parameters

tip

Make sure your Content-Type gets set to application/json, and that you have placed your X-API-Key header with your API Key from your account.

POST /url/pdf

https://api.cloudlayer.io/v2/url/pdf

JSON Payload
{
  "url": "https://google.com"
}

Examples

Viewport Example
{
  "url": "https://google.com",
  "viewPort": {
    "width": 800,
    "height": 400
  }
}

cURL Example
curl --request POST \
  --url https://api.cloudlayer.io/v2/url/pdf \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <YOUR-API-KEY>' \
  --data '{
    "url": "https://google.com"
}' \
--output "google.json"

Wget Example
wget --method POST \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <YOUR-API-KEY>' \
  --body-data '{"url": "https://google.com"}' \
  - https://api.cloudlayer.io/v2/url/pdf \
  -O "google.json"

info

For more examples, checkout the Examples section.

Batch Url Parameters

Parameters that exist on URL based PDF services that can be used for batch processing PDFs.

`batch`

Array of URLs to convert to PDF and then combine into a single PDF file.

Required - Replaces URL parameter if defined.

array Default: []

{
  "batch": [
    "https://google.com",
    "https://wikipedia.com",
    "https://example.com"
  ]
}

Note: Batch counts as multiple API credits, one credit per batch URL, and one credit for the batch call that merges and combines the PDFs. Bytes used and call time are aggregates of all operations. In the above example, four total API credits get used.

Url Parameters

Parameters that exist on URL services.

`authentication`

Provide credentials for HTTP authentication (Basic Auth).

{
  "authentication": {
    "username": "bob",
    "password": "abc123"
  }
}

`cookies`

Sets up one to many cookies for the page prior to navigation.

{
  "cookies": [
    {
      "name": "cookie_notice_accept",
      "value": "1",
      "domain": "www.example.com",
      "path": "/",
      "expires": 1668752280
    },
    {
      "name": "_session_id",
      "value": "ad9a8u90f0df7d87fdas9fa892342",
      "domain": "www.example.com",
      "path": "/",
      "expiration": 1668752280,
      "httpOnly": true
    }
  ]
}

`name`

The name of the cookie to set. Name and value are both required. Required

string Default: ""

{
  "cookies": [
    {
      "name": "myCookie",
      "value": "..."
    }
  ]
}

`value`

The name of the cookie to set. Name and value are both required. Required

string Default: ""

{
  "cookies": [
    {
      "name": "...",
      "value": "SomeCookieValue"
    }
  ]
}

`url`

The url to use for the cookie. This is usually left empty.

string Default: ""

{
  "cookies": [
    {
      "name": "myCookie",
      "value": "some_data",
      "url": "https://www.example.com"
    }
  ]
}

`domain`

Defines the host to which the cookie will be sent. If omitted, this attribute defaults to the host of the current document URL, not including subdomains.

string Default: ""

{
  "cookies": [
    {
      "name": "myCookie",
      "value": "some_data",
      "domain": "www.example.com"
    }
  ]
}

`path`

Indicates the path that must exist in the requested URL for the browser to send the Cookie header.

string Default: ""

{
  "cookies": [
    {
      "name": "myCookie",
      "value": "some_data",
      "path": "/"
    }
  ]
}

`expires`

Indicates the maximum lifetime of the cookie as an Unix time integer.

number Default: <null>

{
  "cookies": [
    {
      "name": "myCookie",
      "value": "some_data",
      "expires": 1668752280
    }
  ]
}

`httpOnly`

Forbids JavaScript from accessing the cookie.

boolean Default: <null>

{
  "cookies": [
    {
      "name": "myCookie",
      "value": "some_data",
      "httpOnly": true
    }
  ]
}

`secure`

Indicates that the cookie is sent to the server only when a request is made with the https: scheme.

boolean Default: <null>

{
  "cookies": [
    {
      "name": "myCookie",
      "value": "some_data",
      "secure": true
    }
  ]
}

`sameSite`

Controls whether or not a cookie is sent with cross-origin requests.

string<"Strict|Lax"> Default: <null>

Values

Strict
Lax

{
  "cookies": [
    {
      "name": "myCookie",
      "value": "some_data",
      "sameSite": "Strict"
    }
  ]
}

`url`

Source URL to use for generating the content.

Required

string Default: ""

{ "url": "http://google.com" }

`username`

The username for authenticating. Username and Password are both required.

Required

string Default: ""

{
  "authentication": {
    "username": "bob",
    "password": "..."
  }
}

`password`

The password for authenticating. Username and Password are both required.

Required

string Default: ""

{
  "authentication": {
    "username": "...",
    "password": "abc123"
  }
}

Base Parameters

Parameters that exist on all services.

`autoScroll`

Will auto-scroll the page down to the very end. Helpful in forcing lazy-loaded content to load.

boolean Default: false

{ "autoScroll": true }

`delay`

The amount of time in milliseconds to wait for the page to complete rendering before conversion.

number Default: 0ms

{ "delay": 1000 }

`filename`

If used with the inline: false, will set the Content-Disposition filename so that the downloaded file will assign to this value in the user's browser. For inline: true, it has no effect.

string Default: ""

{ "filename": "filename.ext" }

`generatePreview`

Generates an image preview (thumbnail) of the image or first page of the PDF document. Storage must be enabled.

All parameters are optional, if you pass in true to generatePreview instead of options it will use defaults.

{
  "width": 600,
  "height": 776,
  "type": "webp",
  "quality": 75
}

`height`

Height of the image to generate for the preview

number Optional - Either width or height must be provided. If maintainAspectRatio is being used, you may specify either one or the other.

 "height": 600

`width`

Width of the image to generate for the preview

number Optional - Either width or height must be provided. If maintainAspectRatio is being used, you may specify either one or the other.

{
  "width": 300
}

`type`

Optional

string Default: "webp"

Type of image to generate for the preview.

Must be one of the following:

png
jpg
webp

{
  "type": "webp"
}

`maintainAspectRatio`

boolean Default: true

Either true or false to indicate if the image generated should maintain aspect ratio based on width/height.

Can result in a blurry and skewed image if the aspect ratio is not maintained

{
  "maintainAspectRatio": true
}

`quality`

string Default: 80

Optional

Specifies the quality of the generated preview.

Must be a number between 0-100.

{
  "quality": 80
}

info

Generating a preview can add significant processing time depending on the quality and size of the preview image and PDF document. It's important to balance quality and rendering time.

`height / width`

`height`

Paper height. Must be supported type of units or number.

string|number Default: <null>

{ "height": 100 }

{ "height": "1.25in" }

`width`

Paper width. Must be supported type of units or number.

string|number Default: <null>

{ "width": 100 }

{ "width": "1.25in" }

`inline`

If set to true, the Content-Disposition gets set to inline. If set to false, it gets set to attachment. See filename property if you want to set the filename value for the attachment.

boolean Default: false

{ "inline": true }

`landscape`

Paper orientation, false sets it to portrait and true to landscape.

boolean `Default: false

{ "landscape": true }

`preferCSSPageSize`

Give any CSS @page size declared in the page priority over what is declared in width and height or format options.

boolean Default: false

{ "preferCSSPageSize": true }

`projectId`

The project's id you would like the job and any assets the job generates to be a member.

string Default: ""

{ "projectId": "N77VCoAVTHHwgmUfCYlD" }

`height`

Page height in pixels only. Required

number Default: <null>

{
  "viewPort": {
    "height": 768
  }
}

`deviceScaleFactor`

Specify device scale factor (DPR). Height and Width are always required.

number Default: 1

{
  "viewPort": {
    "width": 640,
    "height": 480,
    "deviceScaleFactor": 1
  }
}

`isMobile`

Whether the meta viewport tag is taken into account. Height and Width are always required.

boolean Default: false

{
  "viewPort": {
    "width": 640,
    "height": 480,
    "isMobile": true
  }
}

`hasTouch`

Specifies if viewport supports touch events. Height and Width are always required.

boolean Default: false

{
  "viewPort": {
    "width": 640,
    "height": 480,
    "hasTouch": true
  }
}

`isLandscape`

Specifies if viewport is in landscape mode. Height and Width are always required.

boolean Default: false

{
  "viewPort": {
    "width": 640,
    "height": 480,
    "isLandscape": true
  }
}

`scale`

Scale of the webpage rendering. Must be between 0.1 and 2.

number Default: 0

{ "scale": 0.5 }

`timeout`

Amount of time that Chrome is allowed to run. If exceeded, your job will terminate.

number Default: 30000ms

{ "timeout": 30000 }

`timeZone`

Changes the timezone of the page. See ICU's metaZones.txt for a list of supported timezone IDs.

string Default: <null>

{ "timeZone": "Europe/Rome" }

`viewPort`

Set the Viewport of the page before navigation.

{
  "viewPort": {
    "width": 1024,
    "height": 768,
    "deviceScaleFactor": 2
  }
}

`width`

Page width in pixels only. Required

number Default: <null>

{
  "viewPort": {
    "width": 1024
  }
}

`waitForSelector`

Allows for more complex wait behavior to control when the Chrome rendering engine decides when a page has finished before the conversion.

`selector`

The selector of an element to wait for before performing the conversion.

string Default: <null>

{
  "waitForSelector": {
    "selector": "img"
  }
}

`options`

The selector of an element to wait for before performing the conversion.

`visible`

Wait for the selector element to be present in the DOM and to be visible, i.e. to not have display:none or visibility:hidden CSS properties. Not to be combined with the hidden property.

boolean Default: false

{
  "waitForSelector": {
    "selector": "img",
    "options": {
      "visible": true
    }
  }
}

`hidden`

Wait for the selector element to be present in the DOM and to be hidden, i.e. to have display: none or visibility: hidden CSS properties. Not to be combined with the visible property.

boolean Default: false

{
  "waitForSelector": {
    "selector": "img",
    "options": {
      "hidden": true
    }
  }
}

`timeout`

Maximum amount of time to wait in milliseconds for the selector to meet the visible or hidden criteria.

number Default: 30000

visible
{
  "waitForSelector": {
    "selector": "img",
    "options": {
      "visible": true,
      "timeout": 30000
    }
  }
}

hidden
{
  "waitForSelector": {
    "selector": "img",
    "options": {
      "hidden": true,
      "timeout": 30000
    }
  }
}

`waitUntil`

When to consider the navigation has been completed and begin the conversion.

string Default: "networkidle2"

Accepted Values

load - consider navigation to be finished when the load event is fired.
domcontentloaded - consider navigation to be finsihed when the DOMContentLoaded event is fired.
networkidle0 - consider navigation to be finished when there are no more than 0 network connections for at least 500 ms.
networkidle2 - consider navigation to be finished when there are no more than 2 network connections for at least `500' ms.

{ "waitUntil": "load" }

Pdf Parameters

Parameters that exist on all PDF service endpoints.

`pageRanges`

Paper ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages.

string Default: <null>

{ "pageRanges": "1-5" }

`format`

Paper format, which takes priority over width and height. Do not use with width and height. Use one or the other. Must be supported type of formats.

string Default: false

{ "format": "letter" }

`margin`

Paper margins.
(When using templates, the margins are all set to 0 by default.)

{
  "margin": {
    "top": 0,
    "bottom": 0,
    "left": 0,
    "right": 0
  }
}

`top`

Top paper margin, must be supported type of units.

string|number Default: "0.4in"

{
  "margin": {
    "top": 100
  }
}

`bottom`

Bottom paper margin, must be supported type of units.

string|number Default: "0.39in"

{
  "margin": {
    "bottom": 100
  }
}

`left`

Left paper margin, must be supported type of units.

string|number Default: "0.4in"

{
  "margin": {
    "left": 0
  }
}

`right`

Left paper margin, must be supported type of units.

string|number Default: "0.39in"

{
  "margin": {
    "right": 0
  }
}

`printBackground`

Print background graphics.

boolean Default: false

{ "printBackground": true }

`headerTemplate`

Template for the PDF header. There are two types of template styles: a basic HTML template and an HTML body extraction method.

`selector`

Template string if using template method type, otherwise ignored.

string Default: <null>

{ "selector": ".my-div" }

`method`

string Default: "text"

text - Uses the default text template method.
extract - Extracts the header from the HTML body based on the selector, encodes it, and applies styles before adding it to the PDF Header.

{ "method": "extract" }

`margin`

Margin that is applied to the header container. Must be supported type of margin.

string Default: <null>

{
  "margin": {
    "top": "100px",
    "bottom": "100px"
  }
}

`style`

CSS style that gets applied to the header container. Chrome does not support all CSS styles in the header, some values may be ignored.

string Default: <null>

{
  "style": {
    "width": "100%",
    "border": "1px soilid red"
  }
}

`imageStyle`

CSS style that gets applied to the header image container. Chrome does not support all CSS styles in the header, some values may be ignored.

string Default: <null>

{
  "imageStyle": {
    "padding-bottom": "10px",
    "height": "500px",
    "max-width": "75%"
  }
}

Example - Extract Header Template

Html
<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <div class="page-header-bob" style="text-align: center">
      <div id="header">
        <span style="font-size: 20px; color: red">Header</span>
      </div>
    </div>
    <h1>Page 1</h1>
    <div style="height: 842px"></div>
    <h1>Page 2</h1>
  </body>
</html>

Parameters
{
    "html": "PCFET0NUWVBFIGh0bWw+CjxodG1sPgogIDxoZWFkPiA8L2hlYWQ+CiAgPGJvZHk+CiAgICA8ZGl2IGNsYXNzPSJwYWdlLWhlYWRlci1ib2IiIHN0eWxlPSJ0ZXh0LWFsaWduOiBjZW50ZXIiPgogICAgICA8ZGl2IGlkPSJoZWFkZXIiPgogICAgICAgIDxzcGFuIHN0eWxlPSJmb250LXNpemU6IDIwcHg7IGNvbG9yOiByZWQiPkhlYWRlcjwvc3Bhbj4KCiAgICAgIDwvZGl2PgogICAgPC9kaXY+CiAgICA8aDE+UGFnZSAxPC9oMT4KICAgIDxkaXYgc3R5bGU9ImhlaWdodDogODQycHgiPjwvZGl2PgogICAgPGgxPlBhZ2UgMjwvaDE+CiAgPC9ib2R5Pgo8L2h0bWw+Cg=="
    "margin": {
        "top": "120px"
    },
    "headerTemplate": {
        "method": "extract",
        "selector": ".page-header-bob",
        "style": {
            "width": "100%",
            "border": "1px solid red"
        }
    }
}

In the above code snippet called Parameters, the HTML is a base64 encoded string of the Html example above it. In this example, you can see how the div has a class named page-header-bob. This div is the header element extracted out of the body and moved into the header.

A caveat of using headers with PDFs is that the header exists inside the margins on PDF files. So, in this example, a margin-top of 120px is applied to make room for the header element to live. Otherwise, it will be covered up and not visible. By default, when the Chrome rendering engine renders HTML that exists in a header, it uses a font size that is extremely small and not legible, so a font size of 20px gets set on the span inside the header to allow the text to be readable.

`footerTemplate`

Template for the PDF header. See headerTemplate for reference. Can be used identically to the headerTemplate, only difference is the property name.

{
  "footerTemplate": "<...same as headerTemplate>"
}

Units

For properties that accept string unit types, the following units are valid.

Note: If the property accepts a number it defaults to pixels.

px - pixel
in - inch
cm - centimeter
mm - millimeter

px - pixel (number)
{ "width": 100 }

px - pixel
{ "width": "100px" }

in - inch
{ "width": "100in" }

cm - centimeter
{ "width": "100cm" }

mm - millimeter
{ "width": "100mm" }

Formats

The acceptable format options for PDF are valid.

letter: 8.5in x 11in
legal: 8.5in x 14in
tabloid: 11in x 17in
ledger: 17in x 11in
a0: 33.1in x 46.8in
a1: 23.4in x 33.11in
a2: 16.54in x 23.4in
a3: 11.7in x 16.54in
a4: 8.27in x 11.7in
a5: 5.83in x 8.27in
a6: 4.13in x 5.83in

Endpoints​

GET /url/pdf​

POST /url/pdf​

Examples​

Batch Url Parameters​

batch​

Url Parameters​

authentication​

cookies​

name​

value​

url​

domain​

path​

expires​

httpOnly​

secure​

sameSite​

url​

username​

password​

Base Parameters​

autoScroll​

delay​

filename​

generatePreview​

height​

width​

type​

maintainAspectRatio​

quality​

height / width​

height​

width​

inline​

landscape​

preferCSSPageSize​

projectId​

height​

deviceScaleFactor​

isMobile​

hasTouch​

isLandscape​

scale​

timeout​

timeZone​

viewPort​

width​

waitForSelector​

selector​

options​

visible​

hidden​

timeout​

waitUntil​

Accepted Values​

Pdf Parameters​

pageRanges​

format​

margin​

top​

bottom​

left​

right​

printBackground​

headerTemplate​

selector​

method​

margin​

style​

imageStyle​

Example - Extract Header Template​

footerTemplate​

Units​

Formats​

Endpoints

GET /url/pdf

POST /url/pdf

Examples

Batch Url Parameters

`batch`

Url Parameters

`authentication`

`cookies`

`name`

`value`

`url`

`domain`

`path`

`expires`

`httpOnly`

`secure`

`sameSite`

`url`

`username`

`password`

Base Parameters

`autoScroll`

`delay`

`filename`

`generatePreview`

`height`

`width`

`type`

`maintainAspectRatio`

`quality`

`height / width`

`height`

`width`

`inline`

`landscape`

`preferCSSPageSize`

`projectId`

`height`

`deviceScaleFactor`

`isMobile`

`hasTouch`

`isLandscape`

`scale`

`timeout`

`timeZone`

`viewPort`

`width`

`waitForSelector`

`selector`

`options`

`visible`

`hidden`

`timeout`

`waitUntil`

Accepted Values

Pdf Parameters

`pageRanges`

`format`

`margin`

`top`

`bottom`

`left`

`right`

`printBackground`

`headerTemplate`

`selector`

`method`

`margin`

`style`

`imageStyle`

Example - Extract Header Template

`footerTemplate`

Units

Formats