Civillo Documentation

# Layers

# GET

# Get all layers

GET /{organizationNickname}/projects/{projectId}/layers

Get a list of all layers for a given project.

Header Parameters

Name Description
Authorization String Civillo API Credentials
*required

Query Parameters

Name Description
includeRevisions String If set, will include revisions for each layer. Options are "latest" and "all".

Sample output

[
    {
        "id": 123,
        "layerId": 123,
        "name": "A test layer",
        "fromFileName": "AFileName.12da",
        "onByDefault": false,
        "global": false,
        "description": null,
        "downloadRules": 0,
        "creationDate": "2022-06-08T00:00:00Z",
        "lastEditDate": "2022-06-08T00:00:00Z",
        "revisions": [
            {
                "comment": "This is a revision of the layer.",
                "createdDate": "2023-08-23T22:53:16.6478590Z",
                "id": "2023-08-23T22:53:16.6478590Z",
                "source": {
                    "url": "https://path/to/the/source/file",
                    "fileLastModified": 1680673841108,
                    "filename": "test.dwg",
                    "srid": 3857
                },
                "uploader": {
                    "organization": "myorg",
                    "title": "Engineer",
                    "email": "jdoe@myorg.com",
                    "id": "f719dcfb-41a4-4fa8-8c4d-616341306c39",
                    "name": "John Doe"
                }
            }
        ],
        "startDate": null,
        "endDate": null,
        "uploader": {
            "organization": "myorg",
            "title": "Engineer",
            "email": "jdoe@myorg.com",
            "id": "f719dcfb-41a4-4fa8-8c4d-616341306c39",
            "name": "John Doe"
        },
    }
]

Important

When getting layers, organization or project admins will be able to view all project layers. Non-admin users will be restricted to viewing layers they are able to see on the relevant project map page


# Get one layer

GET /{organizationNickname}/projects/{projectId}/layer/{layerId}

Get metadata related to a specific layer.

Header Parameters

Name Description
Authorization String Civillo API Credentials
*required

Sample "Layer" object response

{
    "creationDate": "2023-01-31T17:50:18.4256190Z",
    "description": "Roadworks As Built",
    "downloadRules": 0,
    "fromFileName": "Roadworks-2023-01-31.dwg",
    "id": 1,
    "layerId": 1,
    "global": false,
    "lastEditDate": "2023-01-31T18:12:37.149374Z",
    "name": "Roadworks As Built",
    "onByDefault": false,
    "startDate": null,
    "endDate": null,
    "revisions": [
        {
            "comment": null,
            "createdDate": "2023-01-31T17:50:18.4256190Z",
            "id": "91efc10e-2f04-48b2-97ee-da17976a22d0",
            "source": {
                "url": "https://docs.civillo.com/samples/91efc10e-2f04-48b2-97ee-da17976a22d0",
                "fileLastModified": 1671588013793,
                "filename": "Roadworks-2023-01-31.dwg",
                "srid": 28355
            },
            "uploader": {
                "id": "db6f15a6-ea86-499b-b112-f69e3146e01d",
                "name": "Gary Smith",
                "organization": "Civillo",
                "title": "Data Processor"
            }
        }
    ],
    "uploader": {
        "id": "db6f15a6-ea86-499b-b112-f69e3146e01d",
        "name": "Gary Smith",
        "organization": "Civillo",
        "title": "Data Processor"
    }
}

# The "Layer" object attributes

creationDate string
The layer creation date in UTC formatted as ISO 8601.

description string
Description of the layer which can be helped to describe what the layer is as an addition to the layer name.

downloadRules integer
An integer value representing the current rules around downloading current source and previous revision files.

  • 0 Downloads allowed Current Source file and all previous revision files can be downloaded.
  • 1 Latest source only Only the current source file can be downloaded, but not previous revisions. This helps avoid users downloading and referencing redundant or superseded data.
  • 2 No downloads allowed Neither the current source nor previous revisions can be downloaded.

fromFileName string
The filename of the file that was uploaded to create the layer or latest revision.

id integer
The unique identifier for the layer.

global boolean
The global value of the layer. Determines whether all users of the project can access the layer. Transcends all individual and group based permissions.

lastEditDate string
The last edit date in UTC formatted as ISO 8601. This is updated when the layer is revised or when properties related to the rendering (eg, styling) of the layer are updated.

name string
The name of the layer.

onByDefault boolean
Determines whether the layer will be toggled on, on page load, in default map view.

startDate string
The valid from date in UTC formatted as ISO 8601. The layer will not appear in the layer list or in services reports if this date is in the future.

endDate string
The valid to date in UTC formatted as ISO 8601. The layer will not appear in the layer list or in services reports if this date is in the past.

revisions array
An array of all revision entries for this specific layer. If the layer was never revised, it will only contain one entry.

revisions.comment string
If available, this will contain the comment that was entered when a layer revision was made.

revisions.createdDate string
The revision creation date in UTC formatted as ISO 8601.

revisions.source object
Metadata related to the source file used to create a revision. If this layer is an imagery layer, this value may be null if the user declared that the layer was uploaded without permission for download by others.

revisions.source.url string
The URL to download the revision source file if available.

Important

This is a temporary URL to the revision source file and is will only be available for 30 minutes from when the request was made.

revisions.source.fileLastModified long
This is a value automatically supplied by the user that uploaded the revision, at upload time. It shows the last modified date of the file as the number of milliseconds since the Unix epoch (January 1, 1970 at midnight). This is read from the file before it is uploaded.

revisions.source.filename string
The filename of the file that was uploaded to create the revision.

revisions.source.srid integer
The source file spatial reference id or EPSG code that was selected when the revision was made. If -1 or 0, please refer below for handling information.

  • -1 Auto-detect Import process attempted to auto detect the source file spatial reference. If unsable to auto detect, the project default spatial reference is used.
  • 0 Follow project SRS Used the project default spatial reference.

revisions.source.uploader object
Metadata about the user that uploaded the revision.

revisions.source.uploader.id object
The unique identifier of the user who uploaded the revision.

revisions.source.uploader.name object
The full name of the user who uploaded the revision.

revisions.source.uploader.organization object
The organization of the user who uploaded the revision.

revisions.source.uploader.title object
The job title of the user who uploaded the revision.

revisions.uploader object
Metadata about the user that created the layer or uploaded the most recent revision.

revisions.uploader.id object
The unique identifier of the user that created the layer or uploaded the most recent revision.

revisions.uploader.name object
The full name of the user that created the layer or uploaded the most recent revision.

revisions.uploader.organization object
The organization of the user that created the layer or uploaded the most recent revision.

revisions.uploader.title object
The job title of the user that created the layer or uploaded the most recent revision.

# Get processing layers

GET /{organizationNickname}/projects/{projectId}/layers/processing

Get information regarding current and past job processes.

Header Parameters

Name Description
Authorization String Civillo API Credentials
*required

Query Parameters

Name Description
jobId Integer The id of the job process. If specified, only a single job will be returned as the response and all other filters will be ignored.
pageSize Integer Defines the max number of results per page to include in the response Default 10.
page Integer Defines which results page to return results from Default 1. pageCount can be read from the response. This should be used to determine how many subsequent requests will need to be made to read the entire result set.
creatorId Uuid Filter - The ID of the creating user to filter jobs by
creatorName String Filter - The full name of the creating user to filter jobs by. Case insensitive.
endDate String <ISO 8601> Filter - Include only jobs created before this date.
startDate String <ISO 8601> Filter - Include only jobs created after this date.
statuses Array <String> Filter - Include only jobs in specific job states. Available options are initializing, processing, error, completed. Multiple statuses may be included and the results are inclusive (Logical OR). This means you can request both initializing and completed and get the results for both. Please note that when using error status, only jobs with a definite error (and not perceived error) will be included. Jobs with "perceived" errors eg freezes or unresponsiveness will be included as part of the processing status as they may still be processing.

Sample output - jobId specified

{

    "cancelAllowed": false,
    "complete": false,
    "created": "2023-08-23T22:53:16.6478590Z",
    "id": 123,
    "progress": 75,
    "error": null,
    "status": "Unpacking geometries.",
    "updated": "2023-08-23T22:53:16.6478590Z",
    "uploader": "string"

}

Sample output

[
    {
        "count": 10,
        "jobs": 
        [
            {
                "cancelAllowed": false,
                "complete": false,
                "created": "2023-08-23T22:53:16.6478590Z",
                "id": 123,
                "progress": 75,
                "error": "An error occurred in the process.",
                "status": "Unpacking geometries.",
                "updated": "2023-08-23T22:53:16.6478590Z",
                "uploader": "string"
            }
        ],
        "page": 1,
        "total": 105,
        "pageCount": 11
    }
]

# POST

# Create or revise a layer

POST /{organizationNickname}/projects/{projectId}/layers

Create or update a project layer

Header Parameters

Name Description
Authorization String Civillo API Credentials
*required

Body Parameters

Body parameters must be in valid json format. The following values apply when both creating (mode 0) and revising (mode 1) a layer:

Name Description
mode Integer 0 (create) or 1 (revise)
*required
fileNames String Array Array of the file names to be uploaded. If uploading a .zip containing a shapefile, please include all shapefile related filenames inside the .zip here, otherwise, set forceShapefile to true.
*required
fileLastModifieds long Array The last modified timestamps of each file as Unix epoch times
*required
srid Integer The source spatial reference system Id
*default -1 (auto-detect spatial reference system)
description String Description of the layer
*note: An existing description cannot be removed when revising a layer, only updated. Use a PUT request to update existing layer properties
units String Either m, mm or auto
shpColorMode String Either fixed or attribute
shpColorFixed String Either Hex color value to color each geometry
shpColorAttribute String Attribute field within a dbf file that contains hex color values for each geometry
forceShapefile String If true, allows a shapefile to be uploaded as a .zip without specifying the individual shapefile filenames inside the .zip
*default false
csvIDField String A column within a CSV file that contains an ID value
csvXField String A column within a CSV file that contains an X/Easting value
csvYField String A column within a CSV file that contains an Y/Northing value
csvZField String A column within a CSV file that contains an Z/Height value
colorFieldName String Attribute field within a dbf file that contains hex color values for each geometry
csvColor String Hex color value to color each geometry
dataRightsSelectedItem Integer Download rights to imagery. 1 for viewing rights only. 2 for full rights for sharing and downloading.
ifcSublayerGroupBy Enum When uploading IFC data, identify how Civillo sublayers are grouped.
Name = Group by IFC Name attribute.
Type = Group by IFC Type attribute (if available).
IfcType = Group by IFC IfcType attribute (e.g. IfcType).
*default Name
convert3dFaces Boolean When uploading CAD data, identify if DXF AcDbFace entities should be converted to PolyfaceMesh objects
*default false
convert3dFacesToTerrain Boolean When uploading CAD data, identify if DXF AcDbFace entities should be converted to a Terrain layer
*default false

When creating a layer (mode 0) the following parameters apply (in addition to the above):

Name Description
title String The name of the layer
*required
permitSelf String Automatically assign view permissions to the current user (helps to quickly view a file)
*default true
makeGlobal Boolean Is the layer viewable by everyone with project access (overrides user or group permissions)
*default false
makeOnByDefault Boolean Is the layer visible in Civillio when the map loads
*default false
allowInPermits Boolean If true, this layer will be available for adding to permit categories and attaching to permits.
Overridden by makeGlobal. Requires access to the permit feature.
*default false

When revising a layer (mode 1) the following parameters apply (in addition to the above):

Name Description
replaceLayerId Integer The id of the layer to revise.
*required
revisionComment String A comment about the revision. Can also be set when creating a layer as layer creation is considered the "first" revision.

Sample minimum body parameters (create layer)

{
    "mode": 0,
    "fileNames": ["testLayer.dwg"],
    "title": "testLayer",
    "fileLastModifieds": [1672491600]
}

Sample minimum body parameters (revise layer)

{
    "mode": 1,
    "fileNames": ["updatedTestLayer.dwg"],
    "replaceLayerId": 12,
    "fileLastModifieds": [1672495200]
}

Sample output

{
    "job": 123,
    "token": "ABCDEFGHIJKLMNOP12345678910",
    "processPath": "https://path/to/the/upload-processor",
    "application": "scratch"
}


Completing the layer upload process

Creating or updating a layer in Civillo is a two step process. Posting to the above endpoint will grant you a token which is used to authorize you to send your layer's source files to the upload processor. In order to complete the layer creation process, you will need to send a POST request to the processPath (URL) from the response you received, along with application, job (jobID) and token. The layer source file/s must be included as multipart/form-data body content.

POST {processPath}?token={token}&application={application}&jobID={jobID}&filetype={filetype}

Header Parameters

Name Description
Content-Type String multipart/form-data; boundary={user-agent defined} (opens new window)

Body Parameters

Name Description
file Array <File> Files to be uploaded
*required

Query Parameters

Name Description
application String Organization nickname
*required
jobID Integer Identifies the processor job
*required
token String Authorization token provided by creation request.
*required

Important

When uploading files, please ensure the file names match the fileNames parameter in the previous step, otherwise the request will fail


Responses

200

400

401

Invalid token

404

Job matching jobId could not be found.

409

This job has already been processed or
This job has already been started previously. Please initialize a new job.


# Cancel/Stop a processing layer

POST /{organizationNickname}/projects/{projectId}/layers/cancel-process

Cancel or stop a processing layer. This is useful when a process seems stuck.

Header Parameters

Name Description
Authorization String Civillo API Credentials
*required

Query Parameters

Name Description
jobID Integer Identifies the processor job to cancel
*required

# PUT

# Update a layer's properties

PUT /{organizationNickname}/projects/{projectId}/layers/{layerId}

Header Parameters

Name Description
Authorization String Civillo API Credentials
*required

Body Parameters

Body parameters must be in valid json format

Name Description
name String The updated name.
description String The updated description.
defaultToOn Boolean If true, will be turned on in the map view by default
global Boolean If true, layer will be available to all project users
includeInServicesReports Boolean If true, layer be turned on when rendering a service report
superseded Boolean If true, layer data is considered superseded and will be excluded from "Services/Dial before you dig" reports.
opacity Float Value between 0 and 1. Override the opacity value of all sublayers
strokeWidth Integer Value between 1 and 10. Override the stroke width value of all sublayers
validFrom Date Format yyyy-MM-dd
validUntil Date Format yyyy-MM-dd
downloadRules Enum 0 = Downloads allowed. 1 = Latest source only. 2 = No downloads allowed.
onlineImagerySettings String ???
Last Updated: 18/07/2024

← Overview →