Url Queue
Introduction
You can use the URL-Queue API-extension to combine multiple URL's within one data set and to upload them with only one call.
All requested maps will be rendered fully parallelized and returned within one ZIP-file. Due to parallelized map generation performance is significantly
increased compared to one by one map requests.
Requirements
There are two requirements to use the URL-Queue mechanism:
1. A user name and a password is required. Login information can be requested from your partner or from locr directly.
To connect with the locr maps service, an authentication is required.
See also
2. The used server has to be defined, e.g. : https://maps1.locr.com
File definition of the URL-Queue (XML-structure)
Use the following file structure for upload:
<?xml version="1.0" encoding="utf-8"?>
<batch>
<requests>
<request>
<url>/?print=1&map_config=26&width_cm=29.7&height_cm=21&latitude_min=12.3456&latitude_max=23.4567&longitude_min=34.5678&longitude_max=45.6789</url>
<filename>1</filename>
</request>
<request>
<url>/?print=1&map_config=26&width_cm=29.7&height_cm=21&latitude_min=12.4567&latitude_max=23.5678&longitude_min=34.6789&longitude_max=45.7890</url>
<filename>2</filename>
</request>
<request>
<url>/?print=1&map_config=26&width_cm=29.7&height_cm=21&latitude_min=13.3456&latitude_max=24.4567&longitude_min=35.5678&longitude_max=46.6789</url>
<filename>3</filename>
</request>
</requests>
</batch>
The XML file may not contain more than 10.000 requests ! Additional requests will be ignored!
For each map the correct URL needs to be supplied!
The individual map file name may be defined. If the map file name is not defined, a default HASH-value will be used!
Upload the XML file for the URL-Queue (init)
To start a new URL-Queue, the XML file needs to be uploaded first.
Send a POST-request with enctype "multipart/form-data" to the following URL:
https://maps1.locr.com/api/url_queue.php?action=init
To issue the rendering request for up to 10.000 maps, use the following parameters:
file= "filename.xml" oder "filename.zip"
HTTP-formular example:
<form action="" method="post" target="import">
<input name="action" type="text" value="init"/>
<input name="file" type="file"/>
</form>
Optional parameters:
HTTP-formular example:
<form action="https://maps1.locr.com/api/url_queue.php" method="post" target="import">
<input name="action" type="text" value="init"/>
<input name="file" type="file"/>
<input name="email_notifcation" type="text" value="test@email.com"/>
<input name="alternative_url" value="http://maps1.locr.com/?print=1&config=26&width_cm=29.7&height_cm=21&....."/>
<input name="ftp_host" value="ftp.host.com"/>
<input name="ftp_username" value="username"/>
<input name="ftp_password" value="password"/>
</form>
email_notification :
A notification mail will be sent after the rendering process has been finished.
alternative_url:
Define an alternative map URL, for the records, where a map can not be generated for any reason.
FTP-trigger file
An XML file with status information will be uploaded to the defined FTP server once the rendering process has been finished.
ftp_host:
ftp_username:
ftp_password:
Definition of user name and password for FTP login
Example:
https://maps1.locr.com/api/url_queue.php?action=init&urlfile.xml
https://maps1.locr.com/api/url_queue.php?action=init&urlfile.zip
Return values on successful data import
If the upload and data import was successful, an XML file will be returned containing the number of records and a batch Id, that will be further used.
Example:
<?xml version="1.0" encoding="utf-8"?>
<batch id="1" status="initialized">
<requests status_not_processed="10">
</batch>
Return values in case of an error
I case of an error, an XML will be supllied with the following structure:
Sample request: https://maps1.locr.com/api/url_queue.php?action=stat&id=1
<?xml version="1.0" encoding="utf-8"?>
<error type="invalid_parameter_value">
<details>invalid parameter value "stat" for "action"</details>
</error>
Status request for a URL-Queue (status)
The previously defined Id is important, as it is required for further requests for this URL-Queue.
Use the following request to check the status:
https://maps1.locr.com/api/url_queue.php?action=status&id=1
If the generation process was successful, the following XML will be returned:
<?xml version="1.0" encoding="utf-8"?>
<batch id="1" status="completed">
<archive href="https://maps1.locr.com/api/url_queue.php?action=download_archive&id=1" size="1234567"/>
<requests count="3">
<request status="ok">
<url>https://maps1.locr.com/?print=1&map_config=26&width_cm=29.7&height_cm=21&latitude_min=12.3456&latitude_max=23.4567&longitude_min=34.5678&longitude_max=45.6789</url>
<filename size="123456">1.jpeg</filename>
</request>
<request status="ok">
<url>https://maps1.locr.com/?print=1&map_config=26&width_cm=29.7&height_cm=21&latitude_min=12.4567&latitude_max=23.5678&longitude_min=34.6789&longitude_max=45.7890</url>
<filename size="234567">2.jpeg</filename>
</request>
<request status="ok">
<url>https://maps1.locr.com/?print=1&map_config=26&width_cm=29.7&height_cm=21&latitude_min=13.3456&latitude_max=24.4567&longitude_min=35.5678&longitude_max=46.6789</url>
<filename size="345678">3.jpeg</filename>
</request>
</requests>
</batch>
The attribute batch-status may have the following values:
initialized
running
cancelling
cancelled
completed
The attribute request-status may have the following values:
ok
error
alternative
Cancellation of a URL-Queue (cancel)
https://maps1.locr.com/api/url_queue.php?action=cancel&id=1
Delete a URL-Queue (delete)
https://maps1.locr.com/api/url_queue.php?action=delete&id=1
Advice: A URL-Queue will be deleted from the server after 30 days automatically !
Download of all rendered maps in the URL-Queue (download_archive)
With the following request, a ZIP file of all generated maps can be downloaded.
https://maps1.locr.com/api/url_queue.php?action=download_archive&id=1