File Management Service
The Location Hub® Viewer File Management Service provides the ability to manage KML polygon layers in the Location Hub Viewer application. The service allows you to upload and delete KML files, as well as get a list of layers available within Location Hub Viewer.
Accessing the Service
To access the Location Hub Viewer File Management service you must first be authorized for use with the Location Hub Viewer product in order to have a valid user name and password. Please contact info@dmtispatial.com for more information on how to register for the Location Hub Viewer File Management Service.
Once you have a valid user name and password, please refer to the Basic Authentication section for information on how to access the service.
REST Service
REST Operations
The following File Management service requests are available through REST only:
- GetSearchableLayers: Returns the list of all layers available to the authenticated user within Location Hub Viewer application.
- GetLayerStatus?layer={layer}: Get the current status of the specified layer.
- layer (string): The name of the layer to be queried. One of the following status codes may be returned:
- Nonexistent: The service cannot find the layer specified
- Ready: The layer specified has a spatial index created and is available for use in the Point in Polygon Service
- Creating: The layer specified exists in Location Hub Viewer but the system is currently building the spatial index for the layer
- Possible: The layer specified exists in Location Hub Viewer but the spatial index for the layer has not been created. This file cannot be used in the Point in Polygon Service
- UploadFile?layer={layer}&ft={ft}: Upload a file as a layer in one chunk. The HTTP POST body contains the file stream. Use this method if the file size is less than 4MB. There is no need to call the UploadFinish method after using this method.
- layer (string): The name of the polygon layer (KML File Name) to be uploaded.
- ft (string): The file type of the polygon layer to be uploaded. Only “kml” is currently supported. HTTP Status Code 501 Not Implemented will be returned if the file type is not “kml”.
- UploadChunk?layer={layer}&ft={ft}&chunk={index}: Upload a file as a layer in multiple chunks. The HTTP POST body contains the file stream. Use this method to upload files that are larger than 4MB. The size of each chunk should not exceed 4MB.
- layer (string): The name of the polygon layer (KML File Name) to be uploaded in chunks.
- ft (string): The file type of the polygon layer to be uploaded in chunks. Only “kml” is currently supported. HTTP Status Code 501 Not Implemented will be returned if the file type is not “kml”.
- chunk (integer): The index (or sequenced id) of the current file chunk to be uploaded.
- UploadFinish?layer={layer}&ft={ft}&size={size}: Complete the file upload process. This method must be used after uploading a file in multiple chunks. This method will also perform any post processing that is required for the uploaded layer, such as creating the spatial index.
- layer (string): The name of the polygon layer (KML File Name) that was uploaded in chunks.
- ft (string): The file type of the polygon layer that was uploaded in chunks. Only “kml” is currently supported. HTTP Status Code 501 Not Implemented will be returned if the file type is not “kml”.
- size (integer): The total size in bytes of the file that was uploaded in chunks. This is to verify that the service received the complete file. HTTP Status Code GetSearchableLayers
Conflict will be returned if the file size does not match.
- DeleteLayer?layer={layer}: Delete the specified layer form the Location Hub Viewer application and all files that were created from the specified file.
- layer (string): The name of the layer to be deleted from Location Hub Viewer. HTTP Status Code 404 Not Found will be returned if the layer is not found.
HTTP Status Codes Returned:
Below are the Status Codes returned from the File Management Service:
- 200 OK
- This code will be returned when the service request is successful, such as the file has been successfully uploaded and stitched back together.
- 400 Bad Request
- This error code will be returned when the parameters provided to the services are not properly formatted.
- 401 Unauthorized
- This error code will be returned when the service was unable to authenticate the user. Make sure that the proper user name and password was provided through the HTTP Authorization header.
- 404 Not Found
- This error code will be returned when the service cannot find the layer or file name specified.
- 409 Conflict
- This error code will be returned when the value of the size parameter does not match the total size of the file received by the server when uploading the file in chunks.
- 501 Not implemented
- This code will be returned when the file type provided is not supported. At the moment, only “kml” is supported.
Examples:
GetSearchableLayers
<!-- HTTP GET REST Request (GetSearchableLayers) -->
<!-- https://lhviewer.dmtispatial.com/services/v1/GetSearchableLayers -->
GET https://lhviewer.dmtispatial.com/services/v1/GetSearchableLayers HTTP/1.1
Accept-Encoding: gzip,deflate
Authorization: Basic ************************
Host: lhviewer.dmtispatial.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
<!-- HTTP Response with JSON (GetSearchableLayers) -->
HTTP/1.1 200 OK
Cache-Control: private
Content-Length: 392
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/8.5
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Wed, 16 Sep 2015 20:33:32 GMT
[
"LDU_Ontario.kml",
"FSA_Ontario.kml",
"SalesTerritories.kml",
"Insurance_Policies_Clean.csv",
"Insurance_Policies.csv"
]
GetLayerStatus
<!-- HTTP GET REST Request (GetSearchableLayers) -->
<!-- https://lhviewer.dmtispatial.com/services/v1/GetLayerStatus?layer=FSA_Ontario.kml -->
GET https://lhviewer.dmtispatial.com/services/v1/GetLayerStatus?layer=FSA_Ontario.kml HTTP/1.1
Accept-Encoding: gzip,deflate
Authorization: Basic ************************
Host: lhviewer.dmtispatial.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
<!-- HTTP REST Response with JSON (GetLayerStatus) -->
HTTP/1.1 200 OK
Cache-Control: private
Content-Length: 7
Content-Type: application/json
Server: Microsoft-IIS/8.5
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Wed, 16 Sep 2015 21:08:59 GMT
"Ready"
DeleteLayer
<!-- HTTP GET REST Request (DeleteLayer) -->
<!-- https://lhviewer.dmtispatial.com/services/v1/DeleteLayer?layer=FSA_Ontario.kml -->
GET https://lhviewer.dmtispatial.com/services/v1/DeleteLayer?layer=FSA_Ontario.kml HTTP/1.1
Accept-Encoding: gzip,deflate
Authorization: Basic ************************
Host: lhviewer.dmtispatial.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
<!-- HTTP REST Response with JSON (DeleteLayer) -->
HTTP/1.1 200 OK
Cache-Control: private
Server: Microsoft-IIS/8.5
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Wed, 16 Sep 2015 21:30:32 GMT
Content-Length: 0
Uploading a File
The example below shows you how to upload a large file using javascript:
// Assume the following HMTL elements are on a page
<div class="block" title="Upload a polygon KML file">
<label style="float: left;">Upload file: </label>
<form id="upload" enctype="multipart/form-data" method="post">
<input style="float: left; margin-left: 5px;" type="file" id="file" size="50" />
<input type="submit" id="uploadbtn" value="Upload" />
</form>
</div>
// javascript code to handle uploading file after clicking the Upload button
$("#upload").on('submit', function (event) {
var filepath = $("#file").val(); //from the File Input div element above
var index = filepath.lastIndexOf("\");
var authentication = getAuthorization(); //get the Base64 encoded authentication string
if (index < 0) {
index = filepath.lastIndexOf("/");
}
if (index >= 0) {
var filename = filepath.substring(index + 1);
var filetype = "KML";
index = filename.lastIndexOf(".");
if (index >= 0) {
filetype = filename.substring(index + 1);
}
var chunksize = 4 * 1024 * 1024;
var filesize = file.size;
var counter = 0;
if (filesize < chunksize) {
// upload file in one chunk
Uploadchunk(filename, filetype, filesize, file, -1);
} else {
// upload file in multiple chunks
var start = 0;
var end = chunksize;
var chunkindex = 0;
while (start < filesize) {
var chunk = file.slice(start, end);
Uploadchunk(filename, filetype, filesize, chunk, chunkindex++);
start = end;
end = start + chunk.size;
}
}
function Uploadchunk(filename, filetype, filesize, chunk, index) {
var url = index > -1 ?
"/services/v1/UploadChunk?layer=" + filename + "&ft=" + filetype + "&chunk=" + index
: "/services/v1/UploadFile?layer=" + filename + "&ft=" + filetype;
$.ajax({
type: 'post',
url: url,
data: chunk,
beforeSend: function (jqXHR, settings) {
jqXHR.setRequestHeader("Authorization", authentication );
},
success: function () {
if (index > -1) {
counter++;
if (counter == Math.floor(filesize / chunksize) + 1) {
var url = "/services/v1/UploadFinish?layer=" + filename + "&ft=" + filetype + "&size=" + filesize;
$.ajax({
type: 'get',
url: url,
beforeSend: function (jqXHR, settings) {
jqXHR.setRequestHeader("Authorization", authentication );
},
success: function () {
// File upload complete
}
});
}
} else {
// File upload complete
}
},
error: function (err) {
; //handle errors
},
processData: false,
contentType: file.type
});
}
}
});
