Uploading Files From URL
With Uploadcare, you can upload files from URLs and check their upload statuses
via GET
requests,
GET /from_url/
Such requests return a JSON dictionary with a token that can be further used to
check upload statuses for your files. Note, those tokens are
not file UUIDs and cannot be used to directly address files. The actual file
UUIDs are returned by the /status/
endpoint.
Request parameters
pub_key, string
Defines a target project your uploads will go to, by its public key.
If pub_key
is missing, method returns an error,
[HTTP 400] pub_key is required.
source_url
Defines your source file URL, which should be a public HTTP or HTTPS link.
If source_url
is missing, method returns an error,
[HTTP 400] source_url is required.
store
Sets the file storing behavior. Once stored, files are not deleted after a 24-hour period. Accepted values are:
0
or not set — files do not get stored upon uploading.1
— files get stored upon uploading. Requires the “automatic file storing” setting to be enabled.auto
— file storing works in line with your project settings.
filename
(Optional) Sets the name for a file uploaded from URL. If not defined, the filename is obtained from either response headers or a source URL.
Recurrent Uploads
You can upload some files via /from_url/
more than once. To handle such
iterative cases, we implemented Recurrent Uploads, a mechanism saving URLs that
have already been used with /from_url/
. When you start getting data from such
a URL, you are immediately returned an existing UUID along with related data
from your project without having to wait for an actual download. That saves your
time and traffic.
Recurrent Uploads operate within a scope of your Uploadcare project identified by its public key. Below, we call URLs that are encountered more than once “URL duplicates.”
To activate the Recurrent Uploads feature, use the following two parameters with
/from_url/
to alter its behavior.
Checking for URL duplicates, check_URL_duplicates
Runs the duplicate check and provides the immediate-download behavior.
0
or not set, run no duplicate checks, execute the download anyway.1
, check if asource_url
was used before with thesave_URL_duplicates
parameter set to1
. If the URL was saved previously, no download happens.
Note, once you enable the parameter, save_URL_duplicates
gets triggered with
the same value.
Saving new URLs for further recurrent uploads, save_URL_duplicates
Provides the save/update URL behavior. The parameter can be used if you believe
a source_url
will be used more than once. Using the parameter also updates an
existing reference with a new source_url
content.
If you don’t explicitly define save_URL_duplicates
, it is by default set to
the value of check_URL_duplicates
.
0
, saves no URL duplicates.1
, save thesource_url
or update an existing item.
Return values
/from_url/
response structure depends on the type
field of response JSON.
If type
is token
response JSON will look like this:
{
"type": "token",
"token": "945ebb27-1fd6-46c6-a859-b9893712d650"
}
If type
is file_info
response JSON will look like this:
{
"type": "file_info",
"size": 381192,
"total": 381192,
"done": 381192,
"uuid": "3d61c352-b22f-4487-9c8f-33384f5898ae",
"file_id": "3d61c352-b22f-4487-9c8f-33384f5898ae",
"filename": "LEDbulb.jpg",
"original_filename": "LED bulb.jpg",
"is_image": true,
"is_stored": true,
"image_info": {
"height": 2352,
"width": 2935,
"geo_location": null,
"datetime_original": null,
"format": "JPEG"
},
"video_info": {},
"is_ready": true,
"mime_type": "image/jpeg"
}
Example
Here is a basic example of how you upload a file from URL with Uploadcare,
Request:
curl "https://upload.uploadcare.com/from_url/\
?pub_key=demopublickey&store=1\
&source_url=http%3A%2F%2Fabs.twimg.com%2Fb%2Ffront_page%2Fv1%2FEU_4.jpg"
Response:
{
"token": "945ebb27-1fd6-46c6-a859-b9893712d650"
}
Note, once you get a file token, use the /status/
method to
recieve an actual file UUID.
Errors
If incorrect source_url
is provided, e.g. not a URL,
[HTTP 400] Failed to parse URL.
If source_url
URL scheme info, like http://
, is missing,
[HTTP 400] No URL scheme supplied.
Currently, we only support uploading from http://
or https://
resources,
otherwise you get an error,
[HTTP 400] Invalid URL scheme.
If source_url
does not exist, e.g. resource is gone,
[HTTP 400] Host does not exist.
If your provided source_url
is in our blacklist,
[HTTP 400] Source is blacklisted.
If source_url
contains a malformed host,
[HTTP 400] URL host is malformed.
If provided source_url
refers to a private IP, e.g. 192.168.0.1
,
[HTTP 400] Only public IPs are allowed.
Checking upload status and working with file tokens
This method handles file tokens you get when using the /from_url/
method.
GET /from_url/status/
Request parameters
token, string
Sets a token returned by the /from_url/
method. If the token is missing,
/status/
returns an error,
[HTTP 400] token is required.
If everything is ok, /status/
returns a JSON dictionary holding an upload
status and additional info. Here is a list of possible upload statuses,
- progress, upload is in progress. You also get the additional
total
anddone
fields holding file size in bytes.total
can benull
, e.g. when an origin server does not provide the needed info. - error,
string
, if your uploading from URL returns an error, the respective field contains its short description. - success, everything went smoothly. You also get all the file info fields.
Examples
The following example deals with the error
upload status and shows a short
description for it,
Request:
curl "https://upload.uploadcare.com/from_url/status/\
?token=3ef5d533-68fb-4039-8cd2-41a4d045db0a"
Response:
{
"status": "error",
"error": "FileTooBig: 1150844928 > 104857600"
}
Otherwise, when everything is ok, you get the success
uploading status and a
bunch of other field related to file info,
Request:
curl "https://upload.uploadcare.com/from_url/status/\
?token=945ebb27-1fd6-46c6-a859-b9893712d650"
Response:
{
"status": "success",
"is_stored": true,
"done": 145212,
"file_id": "575ed4e8-f4e8-4c14-a58b-1527b6d9ee46",
"total": 145212,
"size": 145212,
"uuid": "575ed4e8-f4e8-4c14-a58b-1527b6d9ee46",
"is_image": true,
"filename": "EU_4.jpg",
"is_ready": true,
"original_filename": "EU_4.jpg",
"mime_type": "image/jpeg",
"image_info": {
"orientation": null,
"format": "JPEG",
"height": 640,
"width": 960,
"geo_location": null,
"datetime_original": null
}
}