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.
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.
The following parameters are used for authentication and must be present in every API call.
|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.|
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|
|Convert a local HTML file|
|Convert raw HTML code|
The following optional parameters control properties of the generated PDF file.
|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.|
Header and Footer
|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.|
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.
|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.|
Specifies the initial page layout when the PDF is opened in a viewer:
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:
|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.|
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
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 'email@example.com' \ > -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
google_com.pdf will contain an error message instead of
PDF. For convenience, Pdfcrowd provides a shell wrapper
curl that checks for errors and generally makes the
interaction with the API from the command line friendlier.
|Number of remaining credits|
The response contains the result in plain text.
$ curl -F "username=$username" -F "key=$apikey" \ > "http://pdfcrowd.com/api/user/$username/tokens/" $ 12399
The API returns the standard HTTP response status codes. These are the most important ones:
|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.|
Pdfcrowd provides a
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
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
stdout. Otherwise, non-zero exit status is returned and the
error message is written to
stderr. Run the script
-help to get the list of available options.
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.
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.
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.
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.
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.
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.