HTML to PDF API
We offer a professional API for webpage or HTML to PDF conversion. It lets you create high-quality PDF documents quickly, efficiently and cost-effectively. Use it to create high-quality invoices, reports, tickets, e-books, brochures and much more!
Features
- Supports full HTML with JavaScript, including modern frameworks like Bootstrap.
- Has many options for PDF layout, headers and footers and much more!
- Can add watermarks, stamps and/or (full) page backgrounds.
- Can encrypt and protect your PDF documents.
- Can convert web pages in your secure members area or local intranet.
- Can convert or exclude parts of a webpage
- Ready to use code examples for .NET / C#, Java, JavaScript, PHP, Perl, Ruby, Python and VB.net!
- No installation required, but we do have a .NET component and a PHP library available!
Basic Usage
The PDFmyURL API is easy to use. It takes a license and either a URL or raw HTML as input and returns the PDF.
You just send a request similar to this, which converts http://www.example.com to PDF:
https://pdfmyurl.com/api?license=yourlicensekey&url=http://www.example.com
The request should at least have the following components:
- endpoint: this should be http://pdfmyurl.com/api or https://pdfmyurl.com/api for secure access
- license: this is mandatory and you will get yours when you sign up
- url: the web page that you want to convert OR
- html: the raw HTML code that you want to convert
By default we will use all the conversion defaults you set in our members area. Other than that you can use a lot of additional parameters in the API call, which give you access to all the features for conversion. These are all specified below.
NB: You can use both GET as well as POST requests as long as you properly URL encode the data that you pass.
Setting Options
The sections below describe all the options that you will be able to use with the API. Just attach each parameter to the request.
Example: If you want a PDF in A4 format and portrait orientation, you would use the following request.
https://pdfmyurl.com/api?license=yourlicensekey&url=http://www.example.com&page_size=A4&orientation=portrait
Page Dimensions
The table below shows the settings that you can change to control the page settings. These will determine the layout of the resulting PDF.
| Parameter | Description |
|---|---|
| page_size | Page size, such as A4, Letter etc. See the full list for details. |
| orientation | Portrait or Landscape orientation |
| width | Width of the page in unit |
| height | Height of the page in unit. If you specify a width, but not a height, then we generate one long single page PDF. |
| top | Top margin in unit |
| bottom | Bottom margin in unit |
| left | Left margin in unit |
| right | Right margin in unit |
| unit | Measurement unit, which is applied to the margins as well as the width and height. This can be mm (millimeters), in (inches) or pt (points). The default is millimeters. |
Viewport Dimensions new
Our latest rendering engine has two parameters that let you determine at which screen size / viewport we grab the page. This can be useful if you want to grab the mobile version of a webpage or a desktop version at e.g. 2048*1024. Please note that this functionality is currently in beta.
| Parameter | Description |
|---|---|
| screen_width | Width of the screen - by default this is 1024 |
| screen_height | Height of the screen - by default this is 768 |
Conversion Parameters
The table below shows the settings that you can change to control the conversion process. These will largely determine the contents of the resulting PDF.
| Parameter | Description |
|---|---|
| content | Controls which content of the page you want to convert or exclude. See part of page conversion for more info. |
| css | Use custom CSS to style the page to your needs |
| css_media_type | Use print for the print friendly layout (CSS media type 'print') if your web page has one |
| bookmarks | Convert the headers <h1> through <h4> to bookmarks in your PDF so you click through to those different sections. |
| zoom_factor | Use this zoom factor during conversion, this may alter/improve font kerning e.g. 1.03 for a 3% zoom |
| grayscale | Convert to a grayscale PDF |
| no_background | Do not show the web page background in the PDF |
| no_images | Do not include any images from the web page in the PDF |
| no_external_links | Do not show hyperlinks to other domains in the PDF |
| no_internal_links | Do not show hyperlinks within the domain in the PDF |
| no_javascript | Convert the page with JavaScript switched off |
| javascript_time | Wait this time in milliseconds for JavaScript to complete, default is 200 |
| title | Set the title of the PDF instead of the value of the <title> tag from the web page |
| filename | Set the filename of the PDF, which you see in the top bar when you open the PDF in Adobe Reader. |
| toc | Include a table of contents at the beginning of the PDF. |
Header and Footer settings
The header and footer can be specified in HTML and we also support extra parameters for dates and page numbers. Have a look at the extensive documentation.
| Parameter | Description |
|---|---|
| header | HTML that you want to use as header |
| footer | HTML that you want to use as footer |
| page_offset | Number that will be added to the page number, by default this is 0 so page numbers will start at 1. Example: set this to -1 if you want the page numbers to start at 0. |
Watermarking and Stamping
You can use your own image or text as watermark or stamp for the PDFs that you create. We treat watermarks and stamps as the same thing, because we always place them in the foreground. When you use an opacity of 1 your image will appear as a stamp, otherwise it will look like a watermark.
Watermarks are inserted over the contents of the page only, not over the margins. You can adjust this by using negative positions if you want.
| Parameter | Description |
|---|---|
| wm | URL of the watermark image |
| wm_text | Text to use as watermark. This will only be used if you don't specify a watermark image. |
| wm_font | Font face for the text watermark e.g. Tahoma or Courier |
| wm_fontsize | Size in points for the text watermark |
| wm_fontcolor | Color for the text watermark, use e.g. #FF0000 for a red text |
| wm_x | The horizontal position for the watermark |
| wm_y | The vertical position for the watermark |
| wm_sx | The horizontal scaling factor for the watermark Example: use 2 if you want to appear your watermark twice as wide |
| wm_sy | The vertical scaling factor for the watermark |
| wm_opacity | Opacity between 0 and 1. Default is 1, which is fully opague and shows the watermark as a stamp |
| wm_angle | Angle of rotation between 0 and 360 |
Page background
You can use your own images as the background for the PDFs that you create. Because a lot of users want this functionality to create the resemblance to company stationary, we give you the option to use three different images - one for the first page, one for the middle pages and one for the last page. Obviously you can just use only only for all pages as well if you want.You can also let us scale the background so that it automatically makes up the whole width and/or height (including margins) so you don't have to worry about positioning it correctly.
Backgrounds are by default put behind the page, including the margins. This also allows you to get your own PDF background color, by using a 1 pixel image with the color of your choice for example.
| Parameter | Description |
|---|---|
| bg | URL of the background image, used for the first page (and other pages if bg2 or bg3 are not specified) |
| bg2 | URL of the background image, used from the second page onwards |
| bg3 | URL of the background image, used for the last page |
| bg_x | The horizontal position for the background Default is 0, which is the absolute left of the page |
| bg_y | The vertical position for the background Default is 0, which is the absolute top of the page |
| bg_sx | The horizontal scaling factor for the background If you use 0 then we will scale to the full width of the page |
| bg_sy | The vertical scaling factor for the background If you use 0 then we will scale to the full height of the page |
| bg_opacity | Opacity between 0 and 1. Default is 1, which is fully opague |
| bg_angle | Angle of rotation between 0 and 360 |
PDF encryption and rights management
You can use the encryption settings (also known as PDF rights managements or PDF document security) from the table below. This allows you to control who will be able to open a PDF, print it and more. Just make sure that your version of Acrobat Reader (or other PDF reader) supports the level of encryption that you choose, so you can actually OPEN the resulting PDF!
| Parameter | Description |
|---|---|
| encryption_level | Level of encryption of the PDF, which accepts the following values:
|
| user_password | Password needed to open the PDF |
| owner_password | Password needed to adjust the rights management settings of the PDF |
| no_print | Prevent users from printing the PDF |
| no_copy | Prevent users from copying content from the PDF |
| no_modify | Prevent users from annotating (commenting) the PDF |
Accessing secure sites and/or member areas
We understand that your content may reside in a protected area on your site. If you still want to convert this to PDF, we have the following options for you.
- Log into your site from our members area or by using our login API - we will then use the stored cookies for all your conversions.
- Pass the page as raw HTML with the html parameter instead of using the url parameter. In that way we don't need to access your page. You can of course use https to access our API to ensure your data is secure. We have created a JavaScript example that demonstrates how you can do this quickly.
- Secure your content with basic HTTP authentication and specify the username and password parameters in the API call.
- Secure your content with a login form and pass the form fields and values to the API so we can login to your site.
- Use cookies on your site (in combination with other measures) to identify legitimate access to your page and pass a cookie jar with cookies. You can also pass a cookie jar in the old Netscape format, which is the format that tools like cURL and wget will generate.
- Contact us to discuss other options or ask us to use a specific access routine.
| Parameter | Description |
|---|---|
| username | Username for basic HTTP access authentication |
| password | Password for basic HTTP access authentication |
| form_url | URL of a login page that you want us to use and post the form_fields to |
| form_fields | Array with form fields and values that you want us to post to the login page, so we can login to your site |
| session_id | The contents of a JSESSIONID cookie, that we should use to access your URL |
| cookie_jar | The contents of a cookie jar file, that we should use to access your URL |
| ns_cookie_jar | The contents of a cookie jar file in the old Netscape format (still used by cURL and wget), that we should use to access your URL |
Accessing secure sites with the login API
If you want to login to your members area regularly, for example when your cookies expire, then it's easiest if you use our login API. The login API logs in to your members area and then stores the cookies in your settings so they will automatically be used in all conversions for your plan.
It works the same as logging in from our secure login page in the members area or as passing the login parameters to our API, but the advantage is that it saves time and you only need to log in whenever you really want to.
To use the login API you send a request similar to:
https://pdfmyurl.com/login_api?license=yourlicensekey&form_url=http://www.example.com/login.aspx&form_fields[user]=xxx&form_fields[password]=xxx
The request should at least have the following components:
- endpoint: this should be http://pdfmyurl.com/login_api or https://pdfmyurl.com/login_api for secure access
- license: this is mandatory and you will get yours when you sign up
- form_url:Your login page, typically something like http://www.example.com/blog/wp-login.php
- form_fields:An array with form fields and values that we will POST to the login page, for example form_fields[username]=user
- output: json or text output. This parameter is optional and by default we assume you want a JSON response.
The output that you will receive will be a either an error message or the values of the cookies that we have stored. Note that we will NOT store the login parameters in our database, but only the returned cookies. We do this to protect your privacy.
Example - WordPress login with the PDFmyURL API
With the form_url and form_fields parameters you will be able to let us log in to your site. Just make sure that you specify all the form fields that are actually required to be posted. As an example, here's what you would typically use for a login to a WordPress site.
| Parameter | Description |
|---|---|
| form_url | Your login page, typically something like http://www.example.com/blog/wp-login.php |
| form_fields[log] | The username of your WordPress user |
| form_fields[pwd] | The password of your WordPress user |
Please note that the login API is currently only available with a paid license.
Return codes
Our API returns HTTP response codes, which you can check to see if the conversion was succesfull or not. The following is the list of return codes we use.
| Code | Description |
|---|---|
| 200 OK | Your conversion was processed succesfully |
| 400 Bad Request | You didn't specify anything to convert |
| 401 Authorization required | You specified an invalid license key |
| 429 Too Many Requests | You have overrun a usage limit for your plan |
| 503 Service unavailable | You are sending multiple requests at the same time to the API from the same IP address |
Usage tracking
You can track your PDFmyURL usage via a separate HTTP request. This request by default will give you a JSON response indicating plan details and usage.
Just send a request similar to:
https://pdfmyurl.com/usage?license=yourlicensekey
The request should at least have the following components:
- endpoint: this should be http://pdfmyurl.com/usage or https://pdfmyurl.com/usage for secure access
- license: this is mandatory and you will get yours when you sign up
- output: json or text output. This parameter is optional and by default we assume you want a JSON response.
The output that you will receive will look something like this. Please be aware that we may add fields to the structure in the future!
array (
'plan' =>
array (
'start' => '2013-04-15',
'end' => '2014-07-15',
'description' => 'Business License - Advanced',
'limit' => '5000',
'limit period' => 'month',
'status' => 'blocked',
),
'usage' =>
array (
'today' => '65',
'current period' => '5002',
'all time' => '95014',
),
)
Note that our date fields are all in the format yyyy-mm-dd and the 'status' field in the 'plan' array will indicate if your plan is 'active' or 'blocked'.
Get a License!
- High quality PDFs
- Many conversion options
- Watermarking and stamping
- PDF Encryption
- Code examples included
- No installation required!