SmarterWX Developer API
General notes
SmarterWX offers application developers the ability to write custom applications that integrate with the SmarterWX Developer API. Below you’ll find tips on how to get started with the API.
The SmarterWX Developer API provides support for these high-level functional areas: -
- Managing Users
- Publishing Projects and Exclusion Zones
- Querying and Retrieving Data
NB SmarterWX also provides an implementation of the GeoServices REST API for integrating data from SmarterWX into web mapping applications. Discussion of the GeoServices REST API is described elsewhere.
Authentication
Applications developed against the SmarterWX API authenticate use the OAuth 2 Client Credentials Grant flow. The application key and application secret can be found in the SmarterWX website. Only an Organisation Administrator will be able to view the key and secret.
The OAuth2 client credentials flow returns an access token. This token should be submitted as a Bearer Authorization header on all requests.
Refer to the documentation for the /v1/oauth2/token endpoint on how to request an access token.
Returning Collections
The GET calls on resource end-points will result in a collection of resources being returned. For example, ‘GET /community/users’ will return a collection of users. This section describes how to filter the collection, select fields to return and manage paging of large collections.
Filtering the Collection
Specify a set of query filters to return only matching items from the collection.
?firstName=Gar%- Return only the resources withfirstNamestarting withGar.?role=ORGPUBLISHER,ORGUSER- Return only the resources with a role of either ORGPUBLISHER or ORGUSER.?organisation=12- Return only the resources with an organisation id of 12.
Multiple query filters can be included in the query string.
Details of the available filters is given within the definition for each resource.
Sorting the Collection
Specify the order of resources returned in the collection.
* ?sort=lastName,firstName - Describes the sort order for resources returned in the collection. A comma separated list can be used to sort by more than one attribute (the first item has the highest sort precedence).
* ?sort=-created_at - Prefix an attribute name with a hyphen to reverse the sort order.
Details of the available sort fields is given within the definition for each resource.
Result Paging
Operations that return a collection may be limited to maximum number of records. In this case the following headers will be set on the HTTP response: -
X-Result-Total-Count- The total number of records available.X-Result-Page-Limit- The maximum number of records that could be returned in this response.X-Result-Start-Offset- The record index of the first record returned in this response.
The API call may include query parameters to select the maximum number of records and the first record to return.
?limit=10- Return at most 10 records (some operations will have a maximum limit above which you cannot go).?offset=10- The record index of the first record to return (zero-based).
Selecting Fields and Related Resources to Return
To reduce the data size returned for collection queries, the API request must include details of the fields and related resources to be returned with each resource in the collection.
?fields=firstName,lastName,email- Indicates which fields on the resource should be returned. Use the special case of?fields=*to return all available fields.includes=Organisation- Indicates which related resources of the resource should be returned. Use the special case of?includes=*to return all available related resources.
Details of the available fields and related resources is given within the definition of each resource.
Error Codes
- 200 - OK
- 201 - OK. New resource created.
- 400 - Error. Problem with request data or attempting an operation on a resource that is not in the correct state.
- 403 - Forbidden. Either you are not authenticated or you are not authorised for this operation.
- 404 - The resource is not found.
- 5xx - An error occurred on the server. Your request could not be completed at this time.
API detail
Authentication
All requests to the SmarterWX Developer API must include a Bearer Authorization header containing an access token. To request an access token the SmarterWX Developer API uses the OAuth2 “Client Credentials” grant flow.
Application access tokens are used to make requests to the SmarterWX Developer API on behalf of an application rather than a user.
Request a token by using the /oauth2/token endpoint passing in the Client ID and Client Secret found in the Organisation Profile on the SmarterWX website.
Note: Some user data that would normally be recorded when requests when made by a user through the SmarterWX website will not be recorded when using an application access token.
GET /oauth2/token
Application access tokens provide access to SmarterWX on behalf of your organisation. Keep the tokens, client id and client secret secure. Use the SmarterWX Organisation Profile to invalidate your secret and create a new one if required.
The token returned by this call should be passed to all other API calls as a Bearer Authorization header. You should check the expiry of the token and request a new token if necessary.
curl -X GET "https://api.smarterwx.com.au/v1/oauth2/token?grant_type=client_credentials&client_id=848a8254db291caa23f8&client_secret=66aceace519f038754e9374cf7570ddf"GET /v1/oauth2/token?grant_type=client_credentials&client_id=848a8254db291caa23f8&client_secret=66aceace519f038754e9374cf7570ddf HTTP/1.1
Host: api.smarterwx.com.au| Status | 200 |
|---|---|
| |
Publishing Data
Publishing data follows a workflow including multiple sequential API requests. These requests create a WORKSPACE resource to represent the overall publishing unit, and an UPLOAD resource representing each of the projects and exclusion zones.
There are multiple ways to publish data through the SmarterWX Developer API.
- Uploading spatial data files.
- Calling the API to create the projects and exclusion zones.
- Triggering a Live Connect Sync operation (where the configuration has previously been configured through the SmarterWX web site).
- Cloning and modifying the contents of the existing published workspace.
The following diagram shows the sequence of API calls required to publish a new workspace using spatial data fies.
Files uploaded through the SmarterWX Developer API must always first be uploaded to an AWS S3 location and then the reference to this location passed to the relevant API call. (For example, in the above diagram the application requests a location from /system/uploads, uploads the file to the given S3 location, and finally passes the upload key to the /workspaces/{wsid}/projects API call.)
More details on working with the publishing API is provided in each of the /workspaces REST calls detailed below.
Within a workspace, the projects and exclusion zones are refered to as Staged Projects and Staged Exclusion Zones, meaning that they are loaded and part of the workspace but are not yet live. Staged resources can be edited, deleted and added to through the /workspaces/{id}/projects and /workspaces/{id}/exclusionzones resources.
GET /workspaces
Returns a collection of workspace resources based on the query parameters provided. See general discussion on working with collections in the SmarterWX Developer API overview.
curl -X GET -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/workspaces?offset=0&limit=20&fields=*&sort=-created_at&name=LC%&status=draft&owner=19"GET /v1/workspaces?offset=0&limit=20&fields=*&sort=-created_at&name=LC%&status=draft&owner=19 HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|---|
| |
POST /workspaces
Creates a new “empty workspace”. Use this placeholder to then add projects or upload data files. See the publishing workflow described in the Publishing Data section for more information.
The name given to your workspace must be unique. An error will be returned for a duplicate name within your organisation.
curl -X POST -H "X-Requested-With: XmlHttpRequest" -H "Content-Type: application/json" -d '{
"name":"My New Workspace"
}' "https://api.smarterwx.com.au/v1/workspaces"POST /v1/workspaces HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest
Content-Type: application/json
{
"name":"My New Workspace"
}GET /workspaces/:wsid
Returns the specified workspace resource.
curl -X GET -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/workspaces/{id}"GET /v1/workspaces/%7Bid%7D HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 403 |
|---|---|
| |
DELETE /workspaces/{id}
Delete a workspace resource based on the provided workspace id.
A workspace cannot be deleted if it is the current live workspace for your organisation. Before deleting a live workspace it will first need to be unpublished.
curl -X DELETE -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/workspaces/{id}"DELETE /v1/workspaces/%7Bid%7D HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|
PUT /workspaces/{id}
Updates a workspace resource based on the provided id.
There are two types of workspace update - an update to the attributes (name and rules) and an update to the published state of the workspace. Only one of these can occur on any update operation. For example, the workspace name cannot be changed in the same operation as the workspace is published to live.
Use the special isPublished attribute (true or false) to cause the workspace to be published (true) or unpublished (false). Note tht unpublishing removes all of your live data - this will include removing all opportunities and conflicts that exist between your organisation and any other organisation. The response object when publishing or unpublishing a workspace will be a SystemJob resource. Poll this job to monitor the status of the publishing operation.
curl -X PUT -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" -H "X-Requested-With: XmlHttpRequest" -H "Content-Type: application/json" "https://api.smarterwx.com.au/v1/workspaces/{id}"PUT /v1/workspaces/%7Bid%7D HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest
Content-Type: application/json| Status | 200 |
|---|
| Status | 200 |
|---|---|
| |
GET /workspaces/{id}/projects
Retrieve collection of staged project resources for a workspace.
When a workspace is created and project data is uploaded or added to the workspace these projects are classified as Staged Projects. This means that it belongs to the workspace but is not necessarily published. When a workspace is published, the staged projects are copied to the live dataset. (Live projects can be retrieved using the /projects end point.)
curl -X GET -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/workspaces/{id}/projects?sort=id&offset=0&limit=20&fields=*&returnGeometry=false&returnCentroid=true&f=arcgis&text=abc&extent={ xmin: 0, xmax: 0, ymin: 0, ymax: 0 }&format=SHP&includes=PrimaryContact&primaryContact=19&status=CONFIRMED,CONSTRUCTION&worksClassification=WATER,ROAD&persistentId=ABC.001-A&startBefore=2018-06-30&startAfter=2017-12-18&endBefore=2018-12-31&endAfter=2018-01-01"GET /v1/workspaces/%7Bid%7D/projects?sort=id&offset=0&limit=20&fields=*&returnGeometry=false&returnCentroid=true&f=arcgis&text=abc&extent={ xmin: 0, xmax: 0, ymin: 0, ymax: 0 }&format=SHP&includes=PrimaryContact&primaryContact=19&status=CONFIRMED,CONSTRUCTION&worksClassification=WATER,ROAD&persistentId=ABC.001-A&startBefore=2018-06-30&startAfter=2017-12-18&endBefore=2018-12-31&endAfter=2018-01-01 HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|---|
| |
GET /workspaces/{id}/projects/{id}
Retrieves an individual staged project resource from a workspace.
curl -X GET -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/workspaces/{id}/projects/{id}?returnGeometry=true&f=arcgis"GET /v1/workspaces/%7Bid%7D/projects/%7Bid%7D?returnGeometry=true&f=arcgis HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|---|
| |
POST /workspaces/{id}/projects
Add staged projects to a workspace.
Staged projects can be added in one of four ways. Each will match a different use case and business workflow. These are described below. At the completion of this step you will have an editable set of staged projects ready to be published.
Strict validation rules apply to projects. For example, the geometry of the project must be within your organisation’s area of operation, and the start date must be before the end date. Errors and warnings are returned when adding projects. An error indicates the project could not be added; warnings are for information but will allow the project to be added. An example of a warning is a mismatch between a project status and dates (e.g. if status is under CONSTRUCTION but start date is still in the future).
- Create an empty staged projects collection for editing. To create an empty set, submit a body of
{ "processingType": "EMPTY" }. - Create a copy of the current live projects for editing. To create a copy of the current live projects in your workspace, submit a body of
{ "processingType": "CARRYFORWARD" }. - Add projects from a spatial data file. First request a
/system/uploadslocation and upload the file, then submit a body of{ "processingType": "REPLACE" }or{ "processingType": "APPEND" }including the key for the file location. See example for more fields. - Add projects individually. Use the
/workspace/{id}/projectsendpoint to add an individual project. You must have created a staged projects collection using one of the above three methods before attempting to add projects individually. See examples.
Note - for methods 1, 2 and 3 above, the returned resource will be a SystemJob tracking the progress of the operation. Poll the /system/jobs endpoint to get an update on the job status.
curl -X POST -H "X-Requested-With: XmlHttpRequest" -H "Content-Type: application/json" -d '{
"processingType": "REPLACE",
"format": "SHP",
"originalname": "Friendly Filename.shp.zip",
"contentType": "application/zip",
"S3FileKey": "123145asdasdf45sad/sadf3254asfd"
}' "https://api.smarterwx.com.au/v1/workspaces/{id}/projects"POST /v1/workspaces/%7Bid%7D/projects HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest
Content-Type: application/json
{
"processingType": "REPLACE",
"format": "SHP",
"originalname": "Friendly Filename.shp.zip",
"contentType": "application/zip",
"S3FileKey": "123145asdasdf45sad/sadf3254asfd"
}| Status | 200 |
|---|---|
| |
| Status | 200 |
|---|---|
| |
| Status | 200 |
|---|---|
| |
| Status | 200 |
|---|---|
| |
DELETE /workspaces/{id}/projects/{id}
Delete staged project from workspace.
curl -X DELETE -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/workspaces/{id}/projects/{id}"DELETE /v1/workspaces/%7Bid%7D/projects/%7Bid%7D HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|
PUT /workspaces/{id}/projects/{id}
Updates the attributes for a staged project.
curl -X PUT -H "Content-Type: application/json" -d '{
"notes": "Rosemont Street from Hillcrest St to The Boulevarde - Road Resurfacing",
"locality": "PUNCHBOWL",
"startDate": "2017-07-01T00:00:00.000Z",
"endDate": "2018-06-30T00:00:00.000Z",
"status": "CONFIRMED",
"worksClassification": "ROAD RESURFACING",
"primary_contact_id": 4,
"CustomFieldValues": [],
"shape": {
"rings": [
[
[
151.0618648185771,
-33.92703866896214
],
[
151.06177717814532,
-33.92707632486698
],
[
151.0615040327883,
-33.926601338395926
],
[
151.06109628086764,
-33.925454039603714
],
[
151.06115421295596,
-33.925554389553206
],
[
151.06121248662296,
-33.925655376050905
],
[
151.06198146409653,
-33.92698848686364
],
[
151.0618648185771,
-33.92703866896214
]
]
],
"spatialReference": {
"wkid": 4326
}
}
}' "https://api.smarterwx.com.au/v1/workspaces/{id}/projects/{id}"PUT /v1/workspaces/%7Bid%7D/projects/%7Bid%7D HTTP/1.1
Host: api.smarterwx.com.au
Content-Type: application/json
{
"notes": "Rosemont Street from Hillcrest St to The Boulevarde - Road Resurfacing",
"locality": "PUNCHBOWL",
"startDate": "2017-07-01T00:00:00.000Z",
"endDate": "2018-06-30T00:00:00.000Z",
"status": "CONFIRMED",
"worksClassification": "ROAD RESURFACING",
"primary_contact_id": 4,
"CustomFieldValues": [],
"shape": {
"rings": [
[
[
151.0618648185771,
-33.92703866896214
],
[
151.06177717814532,
-33.92707632486698
],
[
151.0615040327883,
-33.926601338395926
],
[
151.06109628086764,
-33.925454039603714
],
[
151.06115421295596,
-33.925554389553206
],
[
151.06121248662296,
-33.925655376050905
],
[
151.06198146409653,
-33.92698848686364
],
[
151.0618648185771,
-33.92703866896214
]
]
],
"spatialReference": {
"wkid": 4326
}
}
}| Status | 200 |
|---|---|
| |
GET /workspaces/{id}/exclusionzones
Retrieve collection of staged exclusion zone resources for a workspace. When a workspace is created and exclusion zone data is uploaded or added to the workspace these exclusion zones are classified as Staged Exclusion Zones. This means that it belongs to the workspace but is not necessarily published. When a workspace is published, the staged exclusion zones are copied to the live dataset. (Live exclusion zones can be retrieved using the /exclusionzones end point.)
curl -X GET -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/workspaces/{id}/exclusionzones?sort=id&limit=20&offset=0&returnGeometry=true&returnCentroid=false&f=arcgis&format=SHP&fields=*&extent={ xmin: 0, xmax: 0, ymin: 0, ymax: 0 }&text=abc&primaryContact=19&persistentId=ABC.EX.0091-a&startBefore=2018-09-30&startAfter=2017-12-31&endBefore=2018-12-31&endAfter=2017-12-31"GET /v1/workspaces/%7Bid%7D/exclusionzones?sort=id&limit=20&offset=0&returnGeometry=true&returnCentroid=false&f=arcgis&format=SHP&fields=*&extent={ xmin: 0, xmax: 0, ymin: 0, ymax: 0 }&text=abc&primaryContact=19&persistentId=ABC.EX.0091-a&startBefore=2018-09-30&startAfter=2017-12-31&endBefore=2018-12-31&endAfter=2017-12-31 HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|---|
| |
GET /workspaces/{id}/exclusionzones/{id}
Retrieves an individual staged exclusion zone resource from a workspace.
curl -X GET -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/workspaces/{id}/exclusionzones/{id}?returnGeometry=true&f=arcgis"GET /v1/workspaces/%7Bid%7D/exclusionzones/%7Bid%7D?returnGeometry=true&f=arcgis HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|---|
| |
POST /workspaces/{id}/exclusionzones
Add staged exclusion zones to a workspace.
Staged exclusion zones can be added in one of four ways. Each will match a different use case and business workflow. These are described below. At the completion of this step you will have an editable set of staged exclusion zones ready to be published.
Strict validation rules apply to exclusion zones. For example, the geometry of the exclusion zones must be within your organisation’s area of operation, and the start date must be before the end date. Errors and warnings are returned when adding exclusion zones. An error indicates the exclusion zone could not be added; warnings are for information but will allow the exclusion zone to be added.
- Create an empty staged exclusion zones collection for editing. To create an empty set, submit a body of
{ "processingType": "EMPTY" }. - Create a copy of the current live exclusion zones for editing. To create a copy of the current live exclusion zones in your workspace, submit a body of
{ "processingType": "CARRYFORWARD" }. - Add exclusion zones from a spatial data file. First request a
/system/uploadslocation and upload the file, then submit a body of{ "processingType": "REPLACE" }or{ "processingType": "APPEND" }including the key for the file location. See example for more fields. - Add exclusion zones individually. Use the
/workspace/{id}/exclusionzonesendpoint to add an individual exclusion zone. You must have created a staged exclusion zones collection using one of the prior three methods before attempting to add exclusion zones individually. See examples.
Note - for methods 1, 2 and 3 above, the returned resource will be a SystemJob tracking the progress of the operation. Poll the /system/jobs endpoint to get an update on the job status.
curl -X POST -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" -H "X-Requested-With: XmlHttpRequest" -H "Content-Type: application/json" "https://api.smarterwx.com.au/v1/workspaces/{id}/exclusionzones"POST /v1/workspaces/%7Bid%7D/exclusionzones HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest
Content-Type: application/json| Status | 200 |
|---|---|
| |
| Status | 200 |
|---|---|
| |
| Status | 200 |
|---|---|
| |
| Status | 200 |
|---|---|
| |
DELETE /workspaces/{id}/exclusionzones/{id}
curl -X DELETE -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/workspaces/{id}/exclusionzones/{id}"DELETE /v1/workspaces/%7Bid%7D/exclusionzones/%7Bid%7D HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|
PUT /workspaces/{id}/exclusionzones/{id}
Update attributes for a staged exclusion zone resource in a workspace.
curl -X PUT -H "X-Requested-With: XmlHttpRequest" -H "Content-Type: application/json" -d '{
"notes": "City to Bay Fun Run 2018",
"locality": "ADELAIDE",
"startDate": "2018-09-15T00:00:00.000Z",
"endDate": "2018-09-17T00:00:00.000Z",
"primary_contact_id": 12,
"shape": {
"rings": [[[138.52060661481764, -34.98008307479301], [138.52058451465243, -34.980130468749955], [138.52055452036413, -34.9801733050329], [138.52060661481764, -34.98008307479301]]],
"spatialReference": {
"wkid": 4326
}
}
}
' "https://api.smarterwx.com.au/v1/workspaces/{id}/exclusionzones/{id}"PUT /v1/workspaces/%7Bid%7D/exclusionzones/%7Bid%7D HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest
Content-Type: application/json
{
"notes": "City to Bay Fun Run 2018",
"locality": "ADELAIDE",
"startDate": "2018-09-15T00:00:00.000Z",
"endDate": "2018-09-17T00:00:00.000Z",
"primary_contact_id": 12,
"shape": {
"rings": [[[138.52060661481764, -34.98008307479301], [138.52058451465243, -34.980130468749955], [138.52055452036413, -34.9801733050329], [138.52060661481764, -34.98008307479301]]],
"spatialReference": {
"wkid": 4326
}
}
}
| Status | 200 |
|---|---|
| |
GET /workspaces/syncconfigs
Returns a Live Connect sync configuration resource.
curl -X GET -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/workspaces/syncconfigs?offset=0&limit=20&fields=*&sort=-created_at&includes=Owner&status=draft&owner=19"GET /v1/workspaces/syncconfigs?offset=0&limit=20&fields=*&sort=-created_at&includes=Owner&status=draft&owner=19 HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|---|
| |
PUT /workspaces/syncconfigs/{id}
Initiates an immediate Live Connect sync operation for the given sync config. The selected Live Connect configuration must have been setup through the SmarterWX website and have a status of live.
Pass a JSON body with the value of shouldSyncNow set to true.
curl -X PUT -H "X-Requested-With: XmlHttpRequest" -H "Content-Type: application/json" -d '{
"shouldSyncNow": true
}' "https://api.smarterwx.com.au/v1/workspaces/syncconfigs/{id}"PUT /v1/workspaces/syncconfigs/%7Bid%7D HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest
Content-Type: application/json
{
"shouldSyncNow": true
}| Status | 200 |
|---|---|
| |
Query and Retrieve
The four main resource types in SmarterWX can be discovered using search operations. The SmarterWX Developer API is read-only for these features. To create new projects or exclusion zones for publishing refer to the Workspace Publishing section of the API.
- Project - Represents a capital works project.
- Exclusion Zone - Represents an area where works cannot be performed during a fixed period (typically things like sporting events or community celebrations).
- Opportunity - Where two projects may provide an opportunity to collaborate or re-schedule to reduce costs or disruption.
- Exclusion Zone Conflict - Represents a clash betwen a planned Project and an Exclusion Zone.
GET /search
curl -X GET -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/search"GET /v1/search HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequestGET /projects
Returns a collection of project resources based on the query parameters provided. See general discussion on working with collections in the SmarterWX Developer API overview.
curl -X GET -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/projects?fields=startDate,endDate&sort=-endDate&includes=CustomFieldValues&offset=0&limit=20&primaryContact=19&status=CURRENT&worksClassification=Water&persistentId=SW.001a&startBefore=2018-06-30&startAfter=2018-01-19&endBefore=2019-03-31&endAfter=2018-11-17&updatedBefore=2018-01-01&updatedAfter=2017-10-23&organisaton=3&returnGeometry=true&returnCentroid=true&f=arcgis"GET /v1/projects?fields=startDate,endDate&sort=-endDate&includes=CustomFieldValues&offset=0&limit=20&primaryContact=19&status=CURRENT&worksClassification=Water&persistentId=SW.001a&startBefore=2018-06-30&startAfter=2018-01-19&endBefore=2019-03-31&endAfter=2018-11-17&updatedBefore=2018-01-01&updatedAfter=2017-10-23&organisaton=3&returnGeometry=true&returnCentroid=true&f=arcgis HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|---|
| |
GET /projects/{id}
Retrieve a single project resource based on id. The id can be found through the /search or /projects collections.
curl -X GET -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/projects/{id}"GET /v1/projects/%7Bid%7D HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|---|
| |
GET /exclusionzones
Returns a collection of exclusion zone resources based on the query parameters provided. See general discussion on working with collections in the SmarterWX Developer API overview.
curl -X GET -H "X-Requested-With: XmlHttpRequest" "/exclusionzones?fields=startDate,endDate&sort=startDate&includes=PrimaryContact&offset=0&limit=20&returnGeometry=true&returnCentroid=true&f=arcgis&primaryContact=19&persistentId=SW-EX-A451&startBefore=2018-06-30&startAfter=2017-09-01&endBefore=2019-12-31&endAfter=2019-01-01&updatedBefore=2018-01-01&updatedAfter=2017-11-30"GET /exclusionzones?fields=startDate,endDate&sort=startDate&includes=PrimaryContact&offset=0&limit=20&returnGeometry=true&returnCentroid=true&f=arcgis&primaryContact=19&persistentId=SW-EX-A451&startBefore=2018-06-30&startAfter=2017-09-01&endBefore=2019-12-31&endAfter=2019-01-01&updatedBefore=2018-01-01&updatedAfter=2017-11-30 HTTP/1.1
Host:
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|---|
| |
GET /exclusionzones/{id}
Retrieve a single exclusion zone resource based on id. The id can be found through the /search or /exclusionzones collections.
curl -X GET -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/exclusionzones/{id}"GET /v1/exclusionzones/%7Bid%7D HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|---|
| |
GET /opportunities
Returns a collection of opportunity resources based on the query parameters provided. See general discussion on working with collections in the SmarterWX Developer API overview.
curl -X GET -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/opportunities?returnGeometry=true&returnCentroid=true&returnChildGeometry=false&f=arcgis&fields=notes,status,updated_at,created_at,linked_project_id&sort=created_at&offset=0&limit=20&status=CURRENT&createdBefore=2018-01-31&createdAfter=2017-12-16&endAfter=2018-03-31&startBefore=2017-12-16"GET /v1/opportunities?returnGeometry=true&returnCentroid=true&returnChildGeometry=false&f=arcgis&fields=notes,status,updated_at,created_at,linked_project_id&sort=created_at&offset=0&limit=20&status=CURRENT&createdBefore=2018-01-31&createdAfter=2017-12-16&endAfter=2018-03-31&startBefore=2017-12-16 HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|---|
| |
GET /opportunities/{id}
Retrieve a single opportunity resource based on id. The id can be found through the /search or /opportunities collections.
curl -X GET -H "X-Requested-With: XmlHttpRequest" "/opportunities/{id}"GET /opportunities/%7Bid%7D HTTP/1.1
Host:
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|---|
| |
GET /ezconflicts
Returns a collection of exclusion zone conflict resources based on the query parameters provided. See general discussion on working with collections in the SmarterWX Developer API overview.
curl -X GET -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/ezconflicts?returnGeometry=true&returnCentroid=true&returnChildGeometry=false&f=arcgis&fields=notes,status,myentity&sort=status,-created_at&offset=0&limit=20&owner=19&myentity=ExclusionZone&status=CURRENT&createdBefore=2017-12-01&createdAfter=2018-01-31"GET /v1/ezconflicts?returnGeometry=true&returnCentroid=true&returnChildGeometry=false&f=arcgis&fields=notes,status,myentity&sort=status,-created_at&offset=0&limit=20&owner=19&myentity=ExclusionZone&status=CURRENT&createdBefore=2017-12-01&createdAfter=2018-01-31 HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|---|
| |
GET /ezconflicts/{id}
Retrieve a single exclusion zone conflict resource based on id. The id can be found through the /search or /ezconflicts collections.
curl -X GET -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/ezconflicts/{id}"GET /v1/ezconflicts/%7Bid%7D HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|---|
| |
User Management
Each organisation has a number of users. The SmarterWX Developer API allows you to manage the users within your organisation, adding, updating and deleting users.
A user can belong to one of three roles:-
- ORGUSER - Basic User. The lowest level of user. Can search and view projects, exclusion zones, opportunities etc, converse with project owners, and set areas of interest and watches.
- ORGPUBLISHER - Organisation publisher. Can upload and edit project data and maintain live connect configurations , and perform all operations that a USER can perform.
- ORGADMIN - Organisation administrator. The highest level of user. Can maintain users, update organisation information, run reports and perform all operations that a PUBLISHER can perform.
Note: An application login through the SmarterWX Developer API has permissions equivalent to an ORGADMIN user.
Projects and exclusion zones belong to a user if they are the project owner. It is not possible to delete or disable a user without first reassigning any owned projects or exclusion zones. An error will be returned in this case.
The maximum number of users allowed is dependent on the organisation’s license type. Any attempt to create more than the maximum number of users will result in a 400 error.
GET /community/users
Returns a list of all user belonging to your organisation. Each user has an id which should be used when performing update and delete operations on the user.
curl -X GET -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/community/users?fields=lastName,firstName&sort=-lastLoggedInAt&includes=Organisation&offset=0&limit=20&firstName=Gar%&lastName=John%&role=ORGUSER,ORGPUBLISHER&isDisabled=true&isVerified=false&email=gjohn%&organisation=12"GET /v1/community/users?fields=lastName,firstName&sort=-lastLoggedInAt&includes=Organisation&offset=0&limit=20&firstName=Gar%&lastName=John%&role=ORGUSER,ORGPUBLISHER&isDisabled=true&isVerified=false&email=gjohn%&organisation=12 HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|---|
| X-Result-Total-Count | 2 |
| X-Result-Start-Offset | 0 |
| X-Result-Page-Limit | 20 |
| |
POST /community/users
Creates a new user in your organisation.
There is a maximum number of users available for any organisation based on your license. Any attempt to add users beyond this limit will result in an error. The user’s email address must be unique across all SmarterWX users in all organisations.
curl -X POST -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" -H "Content-Type: application/json" -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/community/users"POST /v1/community/users HTTP/1.1
Host: api.smarterwx.com.au
Content-Type: application/json
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|---|
| |
GET /community/users/{id}
Retrieve a single user resource based on user id. The user id can be found through the GET /community/users call to search for user collection.
curl -X GET -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/community/users/{id}"GET /v1/community/users/%7Bid%7D HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|---|
| |
PUT /community/users/{id}
Update a user resource. The user and id can be found using the GET /community/users request to return user collection.
A number of restrictions apply to user updates. The following list may not be exhaustive - any errors will be returned from the API call including explanatory text.
- The
rolecannot be changed for the Organisation’s Primary Contact. Must be ORGADMIN. - The email address cannot be changed.
- The Organisation’s Primary Contact cannot be disabled. You must select an alternate primary contact through the SmarterWX web site.
- A user cannot be disabled if they are the owner of any projects or exclusion zones. In this case, the special attribute of
reassignToUsercan be included in the request to change the owner of all objects to the specified user id. (Reassign to user must be an enabled user within your organisation). - The
isBouncedattributes indicates that emails being sent to this user have been returned as bouncing. An update request may only set this value to false.
Available values for the emailPreferences keys are: immediate, daily-digest, weekly-digest, none.
curl -X PUT -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/community/users/{id}"PUT /v1/community/users/%7Bid%7D HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|---|
| |
DELETE /community/users/{id}
Delete a user. The user and id can be found using the GET /community/users request to return user collection.
A number of restrictions apply to user deletion. The following list may not be exhaustive - any errors will be returned from the API call including explanatory text.
- The Organisation’s Primary Contact cannot be deleted. You must select an alternate primary contact through the SmarterWX web site.
- A user cannot be deleted if they are the owner of any projects or exclusion zones. In this case, the special attribute of reassignToUser can be included in the request to change the owner of all objects to the specified user id. (Reassign to user must be an enabled user within your organisation).
curl -X DELETE -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/community/users/{id}"DELETE /v1/community/users/%7Bid%7D HTTP/1.1
Host: api.smarterwx.com.au
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|
POST /community/users/{id}/avatar
Adds a custom image to user for use as their avatar. The image must be sent as Base-64 Image String. The uploaded image will replace any existing or default image for this user.
The maximum image size is 200KB. Any attempt to upload an image larger than this will fail.
curl -X POST -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" -H "Content-Type: application/json" -H "X-Requested-With: XmlHttpRequest" "https://api.smarterwx.com.au/v1/community/users/{id}/avatar"POST /v1/community/users/%7Bid%7D/avatar HTTP/1.1
Host: api.smarterwx.com.au
Content-Type: application/json
X-Requested-With: XmlHttpRequest| Status | 200 |
|---|---|
| |
DELETE /community/users/{id}/avatar
Remove the custom avatar image from the user. The default “initials” avatar will replace the existing custom image.
curl -X DELETE -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" "https://api.smarterwx.com.au/v1/community/users/{id}/avatar"DELETE /v1/community/users/%7Bid%7D/avatar HTTP/1.1
Host: api.smarterwx.com.au| Status | 200 |
|---|
Utility Resources
The system endpoints are used to make requests related to system operations separate from the key resources in SmarterWX. These are typically used to request information necessary to populate or track requests.
GET /system/jobs/{id}
The System Job resource represents a job submitted through the SmarterWX Developer API. It provides information about the status of the job and any messages relating to the job’s processing.
Certain calls to the SmarterWX Developer API that result in a potentially long-running activity (such as publishing data) will return a System Job ID. Use the id with this resource to query the status of the job.
curl -X GET "https://api.smarterwx.com.au/v1/system/jobs/{id}"GET /v1/system/jobs/%7Bid%7D HTTP/1.1
Host: api.smarterwx.com.au| Status | 200 |
|---|---|
| |
GET /system/uploads
As a security measure, the SmarterWX Developer API does not allow files to be uploaded directly to the API Server. Instead you must request an upload placeholder from this endpoint and upload the file to the specified location. Once uploaded you can use the key of the upload placeholder to attach your uploaded file to the relevant resource through the API. See the section on uploading data to workspaces for details on how this is used within the publishing workflow.
The information returned from this call is used to upload to a location within AWS S3. For details on how to use the location information, please refer to this article from AWS.
curl -X GET "https://api.smarterwx.com.au/v1/system/uploads"GET /v1/system/uploads HTTP/1.1
Host: api.smarterwx.com.au| Status | 200 |
|---|---|
| |