8 Service APIs
This section provides a reference for APIs that should be implemented by this Building Block.
This section provides a reference for the APIs implemented by the GIS Building Block. The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionality that should be provided by any implementation of this Building Block.
The GIS BB APIs conform with the OGC web API principles and guidelines and should be deployed as a set of microservices to provide clients consistent access to the key digital functionalities and geographic data in different representations. Microservices are defined to receive requests with relevant inputs and return processed results from key digital functionalities of this Building Block. Microservices are small, independent, and loosely coupled services that perform specific functions within the larger GIS BB key digital functionalities. Each microservice is kept simple and intuitive by focusing on one particular task, and together they form a cohesive and scalable GIS architecture. Each microservice can be developed, deployed, and maintained independently, making it easier to manage and scale the system as needed.
This section provides a reference for APIs that this Building Block should implement. The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks. The Building Block may implement additional APIs, but the listed APIs define a minimal set of functionality that any implementation of this Building Block should provide.
The GovStack non-functional requirements document provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here.
8.1 Map Display
Retrieve the type of the data viewer. This endpoint provides information about whether the client data viewer is desktop, mobile, web browser, or unknown.
Specifies the type of supported browser for the data viewer.
desktopPossible values: Successful retrieval of the data viewer type
desktopPossible values: The data viewer type information could not be found
GET /v1/gisBb/mapDisplay/type HTTP/1.1
Host: host
Accept: */*
desktopRetrieve GIS map display details. This endpoint provides access to GIS data through a data viewer, allowing users to view and query geographic or spatial information presented as graphic representations (points, polygons, lines, or raster grids) through thematic GIS layers or attribute tables. The response will include the symbology (pre-defined styles) for each map layer, displayed as a legend alongside a table of contents listing all layers provided by the service.
Successful retrieval of GIS map display details
Map display details not found
GET /v1/gisBb/mapDisplay/details HTTP/1.1
Host: host
Accept: */*
{
"title": "Map Display Title",
"description": "A summary description of the map display purpose and contents.",
"attribution": "GIS Data Viewer Attribution",
"accessControl": true,
"endPoint": "/r1/eGovStack/COM/11222456/SchedulerBB/creg/event/new",
"crs": "EPSG:4326",
"centerX": 12.3456,
"centerY": 34.5678,
"boundsMinX": 12.3456,
"boundsMinY": 34.5678,
"boundsMaxX": 12.789,
"boundsMaxY": 34.9012
}Add or update spatial bookmarks. This endpoint allows users to capture the spatial extent of a given location as a spatial bookmark in a GIS data viewer. Users can name the bookmark and zoom to the exact extent whenever needed by selecting the bookmark's name. Users can also add, rename, and remove spatial bookmarks as necessary.
Bookmark A1truetruetrue12.345634.567812.78934.9012Successful bookmark creation or update
Invalid request parameters or missing required fields
POST /v1/gisBb/mapDisplay/bookmarks HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 133
{
"name": "Bookmark A",
"create": 1,
"remove": true,
"rename": true,
"zoomTo": true,
"minX": 12.3456,
"minY": 34.5678,
"maxX": 12.789,
"maxY": 34.9012
}{
"name": "Bookmark A",
"create": 1,
"remove": true,
"rename": true,
"zoomTo": true,
"minX": 12.3456,
"minY": 34.5678,
"maxX": 12.789,
"maxY": 34.9012
}Set minimum and maximum scale limits for each layer. This endpoint allows users to specify whether a layer is identifiable and/or selectable on the data viewer. These settings are saved as a cache by the data viewer app and are reserved for future data viewer displays. The settings are reset to default when the cache is cleared.
The name of the GIS layer
The minimum scale to show the layer's feature on the map display
The maximum scale to show the layer's feature on the map display
Successful setting of layer scale limits
No content
Invalid request parameters or missing required fields
PUT /v1/gisBb/mapDisplay/scale?layerTitle=text HTTP/1.1
Host: host
Accept: */*
No content
Enable basic navigation capabilities on the GIS data viewer. This endpoint allows users to perform basic navigation actions such as zooming in and out of a map, and panning to explore the displayed GIS data.
Specifies if zooming is supported
The available zoom levels for the map
Specifies if panning is supported
Successful enabling of basic navigation capabilities
No content
Invalid request parameters or missing required fields
PUT /v1/gisBb/mapDisplay/navigation?zoom=true&zoomLevel=1&pan=true HTTP/1.1
Host: host
Accept: */*
No content
Add, view, delete, and mark map notes on the GIS data viewer. This endpoint allows GIS users to add and share brief notes on the GIS data viewer. Other users can view and comment on these notes. Notes can only be deleted by the creator of the note. Notes are saved and served as a web feature service.
John DoeThis is a map note.2023-08-01T12:34:56Ztruetruetruetrue12.345634.5678Successful note creation or update
Invalid request parameters or missing required fields
POST /v1/gisBb/mapDisplay/notes HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 165
{
"creator": "John Doe",
"content": "This is a map note.",
"timeStamp": "2023-08-01T12:34:56Z",
"add": true,
"delete": true,
"view": true,
"visible": true,
"x": 12.3456,
"y": 34.5678
}{
"creator": "John Doe",
"content": "This is a map note.",
"timeStamp": "2023-08-01T12:34:56Z",
"add": true,
"delete": true,
"view": true,
"visible": true,
"x": 12.3456,
"y": 34.5678
}Perform measuring actions on the GIS data viewer. This endpoint allows users to measure distances and areas on the displayed map.
truetrueSuccessful measuring action
No content
Invalid request parameters or missing required fields
POST /v1/gisBb/mapDisplay/measuring HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 29
{
"distance": true,
"area": true
}No content
Retrieve the style applied to the data viewer. This endpoint provides information about the style used to portray the geographic features of each layer on the data viewer.
Successful retrieval of data viewer style
GET /v1/gisBb/mapDisplay/style HTTP/1.1
Host: host
Accept: */*
Successful retrieval of data viewer style
{
"name": "DefaultStyle",
"description": "Default style for GIS layers",
"type": "CodedStyle"
}8.2 GIS Query
Retrieve GIS layer metadata and feature type definitions.
Successful response
Bad Request
Unauthorized
GET /v1/gisBB/query/layerMetadata HTTP/1.1
Host: host
Accept: */*
[
{
"name": "Sample Layer",
"abstract": "A sample GIS layer",
"author": "John Doe",
"geometry": "point",
"keywords": "sample, layer",
"snippet": "This is a sample layer.",
"spatialExtent": [
[
0,
0
],
[
1,
1
]
],
"lastUpdated": "2023-08-08T12:00:00Z"
}
]Retrieve non-spatial table metadata.
Successful response
Bad Request
Unauthorized
GET /v1/gisBB/query/nonSpatialTableMetadata HTTP/1.1
Host: host
Accept: */*
[
{
"name": "Sample Table",
"abstract": "A sample non-spatial table",
"author": "Jane Smith",
"keywords": "sample, table",
"lastUpdated": "2023-08-08T12:00:00Z"
}
]Execute GIS feature or attribute query operations interactively or through predefined expressions.
Successful response
Bad Request
Unauthorized
Internal Server Error
POST /v1/gisBB/query/gisQuery HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 96
{
"type": "text",
"queryFormat": "text",
"queryString": "text",
"timeStamp": "2025-11-06T17:15:41.291Z"
}[
{
"queryType": "Attribute Query",
"queryStatus": "Success",
"timeStamp": "2023-08-08T12:00:00Z"
}
]Execute a spatial query based on location.
Successful response
Bad Request
Unauthorized
Internal Server Error
POST /v1/gisBB/query/locationalQuery HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 85
{
"layerType": "text",
"spatialRelation": "text",
"longitude": 1,
"latitude": 1,
"distance": 1
}[
{
"queryType": "Locational Query",
"queryStatus": "Success",
"timeStamp": "2023-08-08T12:00:00Z"
}
]Execute an attribute-based query.
Successful response
Bad Request
Unauthorized
Internal Server Error
POST /v1/gisBB/query/attributeQuery HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 57
{
"attributeName": "text",
"operator": "text",
"value": "text"
}[
{
"queryType": "Attribute Query",
"queryStatus": "Success",
"timeStamp": "2023-08-08T12:00:00Z"
}
]Execute a metadata discovery query.
Successful response
Bad Request
Unauthorized
Internal Server Error
POST /v1/gisBB/query/discoveryQuery HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 24
{
"attributeName": "text"
}[
{
"queryType": "Metadata Discovery Query",
"queryStatus": "Success",
"timeStamp": "2023-08-08T12:00:00Z"
}
]Retrieve the results of a previously executed query.
Successful response
Bad Request
Unauthorized
Internal Server Error
GET /v1/gisBB/query/queryResult HTTP/1.1
Host: host
Accept: */*
[
{
"queryType": "Attribute Query",
"queryStatus": "Success",
"timeStamp": "2023-08-08T12:00:00Z"
}
]8.3 GIS Data Management
Create a new GIS data store.
Created
No content
Bad Request
POST /v1/gisBB/dataManagement/dataStore HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 131
{
"name": "text",
"description": "text",
"provider": "text",
"connectionString": "text",
"accessRestrictions": true,
"updateFrequency": "text"
}No content
Retrieve details of a specific GIS data store.
ID of the GIS data store to retrieve
Successful response
No content
Bad Request
Not Found
GET /v1/gisBB/dataManagement/dataStore/{dataStoreId} HTTP/1.1
Host: host
Accept: */*
No content
Update details of a specific GIS data store.
ID of the GIS data store to update
Updated
No content
Bad Request
Not Found
PATCH /v1/gisBB/dataManagement/dataStore/{dataStoreId} HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 131
{
"name": "text",
"description": "text",
"provider": "text",
"connectionString": "text",
"accessRestrictions": true,
"updateFrequency": "text"
}No content
Publish metadata descriptions of a GIS database schema and its contents.
Created
No content
Bad Request
POST /v1/gisBB/dataManagement/dataStoreMetadata HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 111
{
"name": "text",
"source": "text",
"description": "text",
"keywords": "text",
"lastUpdated": "2025-11-06T17:15:41.291Z"
}No content
Create user control for authentication and access permissions.
Created
No content
Bad Request
POST /v1/gisBB/dataManagement/userControl HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 106
{
"username": "text",
"password": "text",
"editorPermissions": "text",
"editorTracking": true,
"ownerControl": true
}No content
Record editor tracking information for feature editing.
Created
No content
Bad Request
POST /v1/gisBB/dataManagement/editorTracking HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 58
{
"editType": "text",
"timeStamp": "2025-11-06T17:15:41.291Z"
}No content
Replicate a remote GIS database schema.
Created
No content
Bad Request
POST /v1/gisBB/dataManagement/replicate HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 72
{
"sourceDataStore": "text",
"targetDataStore": "text",
"replicaType": "text"
}No content
Extract and transfer GIS data layers or features from a remote GIS database.
Created
No content
Bad Request
POST /v1/gisBB/dataManagement/extractTransfer HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 51
{
"sourceDataStore": "text",
"targetDataStore": "text"
}No content
Create, edit, modify, or delete geographic features on the extracted GIS data layers.
Created
No content
Bad Request
POST /v1/gisBB/dataManagement/editFeature HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 58
{
"layerType": "text",
"featureID": "text",
"operation": "text"
}No content
8.4 Geocoding and Reverse Geocoding
Geocode an address to obtain geographic coordinates.
Successful response
No content
Bad Request
POST /v1/gisBB/geocodingReverseGeocoding/geocode HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 45
{
"address": "text",
"longitude": 1,
"latitude": 1
}No content
Reverse geocode geographic coordinates to obtain an address.
Successful response
No content
Bad Request
POST /v1/gisBB/geocodingReverseGeocoding/reverseGeocode HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 28
{
"longitude": 1,
"latitude": 1
}No content
Perform batch geocoding or reverse geocoding using a table file with multiple addresses or coordinates.
Created
No content
Bad Request
POST /v1/gisBB/geocodingReverseGeocoding/batchGeocode HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 94
{
"batchType": "text",
"batchName": "text",
"status": "text",
"timeStamp": "2025-11-06T17:15:41.291Z"
}No content
Retrieve the geocoding result for a specific ID.
ID of the geocoding result to retrieve
Successful response
No content
Not Found
GET /v1/gisBB/geocodingReverseGeocoding/geocodeResult/{resultId} HTTP/1.1
Host: host
Accept: */*
No content
Retrieve the reverse geocoding result for a specific ID.
ID of the reverse geocoding result to retrieve
Successful response
No content
Not Found
GET /v1/gisBB/geocodingReverseGeocoding/reverseGeocodeResult/{resultId} HTTP/1.1
Host: host
Accept: */*
No content
8.5 Spatial Awareness and Analysis
Retrieve detailed information that describes the processes that can be run on the service.
Successful response with available processes
No content
Bad Request
GET /v1/gisBB/spatialAwarenessAnalysis/processes HTTP/1.1
Host: host
Accept: */*
No content
Execute a geoprocessing task to perform basic spatial analysis operations.
Successful response with geoprocessing result
No content
Bad Request
POST /v1/gisBB/spatialAwarenessAnalysis/executeTask HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 137
{
"processingName": "text",
"description": "text",
"parameters": [
{
"parameterName": "text",
"value": "text",
"code": "text",
"defaultValue": "text"
}
]
}No content
Get the status of an asynchronously executed geoprocessing task.
ID of the geoprocessing task
Successful response with task status
No content
Task not found
GET /v1/gisBB/spatialAwarenessAnalysis/taskStatus/{taskId} HTTP/1.1
Host: host
Accept: */*
No content
Get the result of a finished geoprocessing task.
ID of the geoprocessing task
Successful response with task result
No content
Task not found
GET /v1/gisBB/spatialAwarenessAnalysis/taskResult/{taskId} HTTP/1.1
Host: host
Accept: */*
No content
Terminate an asynchronously executed geoprocessing task.
ID of the geoprocessing task
Task termination request received
No content
Task not found
POST /v1/gisBB/spatialAwarenessAnalysis/terminateTask/{taskId} HTTP/1.1
Host: host
Accept: */*
No content
8.6 Reporting
Add a dynamic GIS layer to a map layout or report.
Successful response after adding dynamic GIS layer
No content
Bad Request
POST /v1/gisBB/reporting/dynamicLayers HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 109
{
"title": "text",
"abstract": "text",
"author": "text",
"keywords": "text",
"lastUpdated": "2025-11-06T17:15:41.291Z"
}No content
Remove a dynamic GIS layer from a map layout or report.
ID of the dynamic GIS layer to be removed
Successful response after removing dynamic GIS layer
No content
Layer not found
DELETE /v1/gisBB/reporting/dynamicLayers/{layerId} HTTP/1.1
Host: host
Accept: */*
No content
Add a label to a map layout or report.
Successful response after adding label
No content
Bad Request
POST /v1/gisBB/reporting/labels HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 86
{
"labelText": "text",
"positionX": 1,
"positionY": 1,
"font": "text",
"size": 1,
"color": "text"
}No content
Remove a label from a map layout or report.
ID of the label to be removed
Successful response after removing label
No content
Label not found
DELETE /v1/gisBB/reporting/labels/{labelId} HTTP/1.1
Host: host
Accept: */*
No content
Add a chart to a map layout or report.
Successful response after adding chart
No content
Bad Request
POST /v1/gisBB/reporting/charts HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 44
{
"title": "text",
"type": "text",
"data": "text"
}No content
Remove a chart from a map layout or report.
ID of the chart to be removed
Successful response after removing chart
No content
Chart not found
DELETE /v1/gisBB/reporting/charts/{chartId} HTTP/1.1
Host: host
Accept: */*
No content
Add a legend to a map layout or report.
Successful response after adding legend
No content
Bad Request
POST /v1/gisBB/reporting/legends HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 86
{
"labelText": "text",
"positionX": 1,
"positionY": 1,
"font": "text",
"size": 1,
"color": "text"
}No content
Remove a legend from a map layout or report.
ID of the legend to be removed
Successful response after removing legend
No content
Legend not found
DELETE /v1/gisBB/reporting/legends/{legendId} HTTP/1.1
Host: host
Accept: */*
No content
Add a scale bar to a map layout or report.
Successful response after adding scale bar
No content
Bad Request
POST /v1/gisBB/reporting/scaleBars HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 123
{
"title": "text",
"style": "text",
"length": 1,
"units": "text",
"positionX": 1,
"positionY": 1,
"font": "text",
"size": 1,
"color": "text"
}No content
Remove a scale bar from a map layout or report.
ID of the scale bar to be removed
Successful response after removing scale bar
No content
Scale Bar not found
DELETE /v1/gisBB/reporting/scaleBars/{scaleBarId} HTTP/1.1
Host: host
Accept: */*
No content
Add a north arrow to a map layout or report.
Successful response after adding north arrow
No content
Bad Request
POST /v1/gisBB/reporting/northArrows HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 123
{
"title": "text",
"style": "text",
"length": 1,
"units": "text",
"positionX": 1,
"positionY": 1,
"font": "text",
"size": 1,
"color": "text"
}No content
Remove a north arrow from a map layout or report.
ID of the north arrow to be removed
Successful response after removing north arrow
No content
North Arrow not found
DELETE /v1/gisBB/reporting/northArrows/{northArrowId} HTTP/1.1
Host: host
Accept: */*
No content
8.7 Geofencing
Successful response after creating geofence
No content
POST /v1/gisBB/geofencing/geofences HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 53
{
"name": "text",
"shape": "text",
"size": 1,
"status": true
}Successful response after creating geofence
No content
Successful response after updating geofence
No content
Geofence not found
PUT /v1/gisBB/geofencing/geofences/{geofenceId} HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 53
{
"name": "text",
"shape": "text",
"size": 1,
"status": true
}No content
Successful response after adding geofence element
No content
Geofence not found
POST /v1/gisBB/geofencing/geofences/{geofenceId}/elements HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 46
{
"elementType": "text",
"trackingMethod": "text"
}No content
Successful response after removing geofence element
No content
Geofence or element not found
DELETE /v1/gisBB/geofencing/geofences/{geofenceId}/elements/{elementId} HTTP/1.1
Host: host
Accept: */*
No content
Successful response after creating action rule
No content
Geofence not found
POST /v1/gisBB/geofencing/geofences/{geofenceId}/rules HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 37
{
"actionType": "text",
"action": "text"
}No content
Successful response after creating element action rule
No content
Geofence or element not found
POST /v1/gisBB/geofencing/geofences/{geofenceId}/elements/{elementId}/actions HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 69
{
"notificationType": "text",
"recipient": "text",
"recipientType": "text"
}No content
8.8 Routing
Successful response after creating a route
No content
POST /v1/gisBB/routing/routes HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 100
{
"startNode": {},
"endNode": {},
"passThrough": true,
"restrictions": "text",
"additionalParameters": "text"
}Successful response after creating a route
No content
Last updated
Was this helpful?