Legacy Pdfcrowd API v1
This is the documentation for the legacy Pdfcrowd API v1. We strongly recommend the new improved Pdfcrowd API v2 for new integrations.
API v1 Client Libraries Documentation & Downloads
REST API v1 Documentation
An API call is made by sending an HTTP request to the API endpoint with parameters passed as POST data. The API endpoints support both http and https schemes.
Authentication
The following parameters are used for authentication and must be present in every API call.
Parameter | Description |
---|---|
username | Your username at Pdfcrowd |
key | API key. Can be found on your account page. Note that the key is regenerated when you change your password. |
PDF Creation
A PDF document can be created in one of the following ways. The created PDF is returned in the response body.
Convert a web page | |
---|---|
Method | POST |
API Endpoint | http://pdfcrowd.com/api/pdf/convert/uri/ |
Content Type | application/x-www-form-urlencoded |
Post Data |
Mandatory
|
Convert a local HTML file | |
---|---|
Method | POST |
API Endpoint | http://pdfcrowd.com/api/pdf/convert/html/ |
Content Type | multipart/form-data |
Post Data |
Mandatory
|
Convert raw HTML code | |
---|---|
Method | POST |
Content Type | application/x-www-form-urlencoded |
API Endpoint | http://pdfcrowd.com/api/pdf/convert/html/ |
Post Data |
Mandatory
|
Common Parameters
The following optional parameters control properties of the generated PDF file.
Page Setup
Parameter | Description |
---|---|
width | PDF page width in units. |
height | PDF page height in units. -1 for a single page PDF. |
margin_top | Top PDF page margin in units. |
margin_right | Rigth PDF page margin in units. |
margin_bottom | Bottom PDF page margin in units. |
margin_left | Left PDF page margin in units. |
hmargin | Deprecated. Use margin_left and margin_right instead. |
vmargin | Deprecated. Use margin_top and margin_bottom instead. |
Some parameters can be specified in inches (in), millimeters (mm), centimeters (cm), or points (pt). If no units are specified, points are assumed.
Examples: 210mm
, 8.5in
Header and Footer
Parameter | Description |
---|---|
footer_html | Places the specified HTML code
inside the page
footer. The following variables are expanded:
|
footer_url | Loads HTML code from the specified URL and places it inside the page footer. See footer_html for the list of variables that are expanded. |
header_html | Places the specified HTML code inside the page header. See footer_html for the list of variables that are expanded. |
header_url | Loads HTML code from the specified URL and places it inside the page header. See footer_html for the list of variables that are expanded. |
header_footer_page_exclude_list | A comma
seperated list of physical page numbers on which the header a
footer are not printed. Negative numbers count backwards from
the last page: -1 is the last page, -2 is the last but one
page, and so on. Example: "1,-1" will not print the header and footer on the first and the last page. |
page_numbering_offset | An offset between
physical and logical page numbers. The default value is 0. Example: if set to "1" then the page numbering will start with 1 on the second page. |
HTML options
PDF Options
Parameter | Description |
---|---|
encrypted | Encrypts the PDF. This prevents search engines from indexing the document. |
author | Sets the PDF author field. |
user_pwd | Protects the PDF with an user password. When a PDF has an user password, it must be supplied in order to view the document and to perform operations allowed by the access permissions. At most 32 characters. |
owner_pwd | Protects the PDF with an owner password. Supplying an owner password grants unlimited access to the PDF including changing the passwords and access permissions. At most 32 characters. |
no_print | Do not allow to print the generated PDF. |
no_modify | Do not allow to modify the PDF. |
no_copy | Do not allow to extract text and graphics from the PDF. |
page_layout |
Specifies the initial page layout when the PDF is opened in a viewer:
|
initial_pdf_zoom_type |
Specifies the initial page zoom type when the PDF is opened in a viewer:
|
initial_pdf_zoom | Specifies the initial page zoom when the PDF is opened in a viewer. Defaults to 100%. |
page_mode | Specifies the appearance of the PDF when opened:
|
max_pages | Prints at most the specified number of pages. |
pdf_name | The file name of the created PDF (max 180 chars). If not specified then the name is auto-generated. |
pdf_scaling_factor | The scaling factor used to convert between HTML and PDF. The default value is 1.333 (4/3) which makes the PDF content up to 1/3 larger than HTML. |
page_background_color | The page background color in RRGGBB hexadecimal format. |
transparent_background | Do not print the body background. Requires the following CSS rule to be declared:body {background-color:rgba(255,255,255,0.0);}
|
Watermark
Parameter | Description |
---|---|
watermark_url | A public absolute URL of the watermark image (must start either with http:// or https://). The supported formats are PNG and JPEG. |
watermark_offset_x | The horizontal watermark offset in units. The default value is 0. |
watermark_offset_y | The vertical watermark offset in units. The default value is 0. |
watermark_rotation | The watermark rotation in degrees. |
watermark_in_background | When set then the watermark is be placed in the background. By default, the watermark is placed in the foreground. |
Miscellaneous
Examples of API calls
The following command converts www.google.com
to PDF:
$ curl -F "username=$username" -F "key=$apikey" \ > -F 'src=http://www.google.com' \ > http://pdfcrowd.com/api/pdf/convert/uri/ > google_com.pdf
The following command converts the output of some html_producer
application to PDF and protects it with an user password:
$ html_producer | curl -F "username=$username" -F "key=$apikey" \ > -F 'src=<-' \ > -F 'user_pwd=secret' \ > http://pdfcrowd.com/api/pdf/convert/html/ > google_com.pdf
The following command converts a local file index.html
to PDF
and disables printing:
$ curl -F "username=$username" -F "key=$apikey" \ > -F 'src=@index.html' \ > -F 'no_print=1' \ > http://pdfcrowd.com/api/pdf/convert/html/ > google_com.pdf
Note, that the examples above ignore errors. If the API call
fails google_com.pdf
will contain an error message instead of
PDF. For convenience, Pdfcrowd provides a shell wrapper
around curl
that checks for errors and generally makes the
interaction with the API from the command line friendlier.
User Status
Number of remaining credits | |
---|---|
Method | POST |
API Endpoint | http://pdfcrowd.com/api/user/<username>/tokens/ |
Content Type | application/x-www-form-urlencoded |
Post Data | Mandatory |
The response contains the result in plain text.
$ curl -F "username=$username" -F "key=$apikey" \ > "http://pdfcrowd.com/api/user/$username/tokens/" $ 12399
Return Codes
The API returns the standard HTTP response status codes. These are the most important ones:
Code | Description |
---|---|
200 OK | The API call succeeded. |
400 Bad Request | The user sent an invalid request. The body of the response contains an explanation in plain text. |
413 Request Entity Too Large | See Limitations below. |
502 Bad Gateway | See Limitations below. |
503 Service Unavailable | See Limitations below. |
510 | A non-standard status code indicating that the server couldn't process the request. The body of the response contains an explanation in plain text. |
Shell
Pdfcrowd provides a
shell
script which wraps curl
and provides more convenient access
to the API from shell.
The script reads options from ~/.pdfcrowd
and then from the
command line. You can store your default options to ~/.pdfcrowd
,
one option per line:
$ cat > ~/.pdfcrowd <<! > -username $username > -key $apikey > -width 210mm > -height 297mm > !
Now, you can run:
$ pdfcrowd.sh http://www.google.com > google_com.pdf $ pdfcrowd.sh /path/to/local/file > html.pdf $ html_producer | pdfcrowd.sh - > file.pdf $ echo "remaining credits: $(pdfcrowd.sh @)"
On success, exit status 0 is returned and the result is written
to stdout
. Otherwise, non-zero exit status is returned and the
error message is written to stderr
. Run the script
with -help
to get the list of available options.
Data Security
We understand that your data may be sensitive and confidential and that it is absolutely unacceptable to disclose it or keep unnecessary copies.
We want to be transparent about how we process your data, so here we describe an API conversion request lifecycle:
- Your request hits our HTTP server. Depending on the method you use:
- Any data uploaded with convertHtml or convertFile is temporarily saved to a directory (dirA/) on our server.
- Any other data is downloaded directly by the user agent during the conversion. The user agent has caching disabled.
- Our backend process creates a PDF from your data and saves it temporarily to a directory (dirB/) on our server.
- The HTTP server streams the created PDF from dirB/ back to you.
- Both dirA/ and dirB/ are scanned every 10 minutes by a script which deletes the old files.
API Limitations
The following limits are applied to ensure fair distribution of capacity.
If you find the limits too restrictive we can provision a private server optimized for your specific needs with the limits lifted. If you would like to discuss this option please contact us.
Rate Limiting
The API returns an HTTP 503 Service unavailable status code in the following cases:
- The client sends more than 30 requests per minute from a single IP. Note, that a query on the number of credits counts against the limit.
- The client sends more than one simultaneous request from a single IP
at a time.
Ideally, you should serialize your API calls. However, we understand that you can't always ensure this in some environments, such as for instance with Google App Engine Task Queue. In such cases it is perfectly acceptable to check for this error and possibly send the failed request again.
Time Limit
If a request takes more than 40 seconds to complete it is cancelled and either of these messages may be returned:
- 510 - 413 Timed out. Can't load the specified URL.
- 502 - Sorry, we couldn't process your request.
A typical cause of this error is too many images on an HTML page which take too long to download. Another cause might be a long running JavaScript.
Size Limits
If the size of the uploaded data exceeds 20MB then an HTTP 413 Request entity too large error is returned. You can zip your HTML to avoid this error.
If the size of the downloaded data exceeds 100MB then the an HTTP 502 error code is returned.
Miscellaneous
We return an HTTP 502 error code also when:
- The converted page loads more than 2,000 sub-resources (images, external stylesheets, etc.)
- There is more than 8 HTTP redirects when attempting to load a page sub-resource.