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

authentification 

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&amp;map_config=26&amp;width_cm=29.7&amp;height_cm=21&amp;latitude_min=12.3456&amp;latitude_max=23.4567&amp;longitude_min=34.5678&amp;longitude_max=45.6789</url>

            <filename>1</filename>

        </request>

        <request>

            <url>/?print=1&amp;map_config=26&amp;width_cm=29.7&amp;height_cm=21&amp;latitude_min=12.4567&amp;latitude_max=23.5678&amp;longitude_min=34.6789&amp;longitude_max=45.7890</url>

            <filename>2</filename>

        </request>

        <request>

            <url>/?print=1&amp;map_config=26&amp;width_cm=29.7&amp;height_cm=21&amp;latitude_min=13.3456&amp;latitude_max=24.4567&amp;longitude_min=35.5678&amp;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&amp;map_config=26&amp;width_cm=29.7&amp;height_cm=21&amp;latitude_min=12.3456&amp;latitude_max=23.4567&amp;longitude_min=34.5678&amp;longitude_max=45.6789</url>

            <filename size="123456">1.jpeg</filename>

        </request>

        <request status="ok">

            <url>https://maps1.locr.com/?print=1&amp;map_config=26&amp;width_cm=29.7&amp;height_cm=21&amp;latitude_min=12.4567&amp;latitude_max=23.5678&amp;longitude_min=34.6789&amp;longitude_max=45.7890</url>

            <filename size="234567">2.jpeg</filename>

        </request>

        <request status="ok">

            <url>https://maps1.locr.com/?print=1&amp;map_config=26&amp;width_cm=29.7&amp;height_cm=21&amp;latitude_min=13.3456&amp;latitude_max=24.4567&amp;longitude_min=35.5678&amp;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