Downloading a Label
You have two options for downloading labels you've created with ShipEngine:
- Download via URL: Make an HTTP request to download the label in your desired file type from the URLs provided in the
label_download
object from the create label response. - Inline labels: If you only intend to download the label in a single format and you know ahead of time which format that is, you can optimize your workflow by eliminating the extra HTTP request to download the label. Instead, you can use the
label_format
,label_layout
, andlabel_download_type
fields to include the full label in the API response.
Option 1: Download via URL
By default, ShipEngine provides URLs to download labels in multiple formats. The URLs will remain valid for 90 days. If your workflow requires the ability to access these URLs after 90 days, we recommend storing the label images locally.
Public URLs
ShipEngine generates a unique authentication token for each label so it can be securely shared and downloaded by your users without exposing your private API key.
You can download the label in your web browser by appending ?download=0
to the URL, or you download it on the command line using curl:
Label Rotation
You can rotate the label 90, 180, or 270 degrees by appending ?rotation=:value
to the URL.
- Supported for ZPL and PDF formats.
- Valid
rotation
value forzpl
labels are0
(default) and180
. - Valid
rotation
values forpdf
labels are0
(default),90
,180
, and270
.
You can view the rotated image in your web browser using this URL or download it on the command line using curl:
Option 2: Inline Label
With this method, you'll use the label_format
, label_layout
, and label_download_type
properties to include the full label in the API response.
About the Inline Label Properties
Label Format:
- PDF: The Adobe PDF format. This is the default if
label_format
is unspecified. - PNG: A PNG (portable network graphics) image file.
- ZPL: Zebra Programming Language format, which is useful for printing with a Zebra Printer.
Label Layout:
- 4x6 : 4 inch by 6 inch label. This is the default if
label_layout
is unspecified. - letter: US Letter size (8.5 inches by 11 inches).
Label Download Type:
url
: You will receive URLs to download the label in separate HTTP requests. The URLs will remain valid for 90 days. This is the default iflabel_download_type
is unspecified.inline
: You will receive a single, Base64-encoded label as part of the response. No need for a second request to download the label.
Example Inline Request & Response
This example demonstrates how to use label_format
, label_layout
, and label_download_type
to request a 4x6
PNG label to be included in the API response.
Response
The label_download.href
field in the response will be a Data URI, which is a special kind of URL that includes the data inline.
The Data URI has four parts: scheme, media type, encoding type, data
Name | Examples | Description |
---|---|---|
Scheme | Always data: | This just identifies the URL as a Data URI as opposed to other schemes like http: or ftp: . |
Media Type | application/pdf image/png application/zpl | This is the label's MIME Type, which corresponds to the label_format that you specified when creating the label. |
Encoding Type | Always base64 | ShipEngine always encodes inline labels in Base64 format. |
Data | A very long Base64 string | This is the actual Base64-encoded label data. Most programming languages include a Base64 decoder as part of their standard library. If your language doesn't, then you may need to use a third-party Base64 decoder. |