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: desktopPossible values: 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.
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.9012POST /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
PUT /v1/gisBb/mapDisplay/scale 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
PUT /v1/gisBb/mapDisplay/navigation 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.5678POST /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.
truetruePOST /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.
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.
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.
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.
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-06-23T02:41:20.033Z"
}[
{
"queryType": "Attribute Query",
"queryStatus": "Success",
"timeStamp": "2023-08-08T12:00:00Z"
}
]Execute a spatial query based on location.
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.
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.
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.
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.
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
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
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.
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-06-23T02:41:20.033Z"
}No content
Create user control for authentication and access permissions.
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.
POST /v1/gisBB/dataManagement/editorTracking HTTP/1.1
Host: host
Content-Type: application/json
Accept: */*
Content-Length: 58
{
"editType": "text",
"timeStamp": "2025-06-23T02:41:20.033Z"
}No content
Replicate a remote GIS database schema.
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.
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.
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.
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.
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.
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-06-23T02:41:20.033Z"
}No content
Retrieve the geocoding result for a specific ID.
ID of the geocoding result to retrieve
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
GET /v1/gisBB/geocodingReverseGeocoding/reverseGeocodeResult/{resultId} HTTP/1.1
Host: host
Accept: */*
No content
8.5 Spatial Awareness and Analysis
Execute a geoprocessing task to perform basic spatial analysis operations.
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
GET /v1/gisBB/spatialAwarenessAnalysis/taskStatus/{taskId} HTTP/1.1
Host: host
Accept: */*
No content
Terminate an asynchronously executed geoprocessing task.
ID of the geoprocessing task
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.
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-06-23T02:41:20.033Z"
}No content
Remove a dynamic GIS layer from a map layout or report.
ID of the dynamic GIS layer to be removed
DELETE /v1/gisBB/reporting/dynamicLayers/{layerId} HTTP/1.1
Host: host
Accept: */*
No content
Add a label to a map layout or report.
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
Add a chart to a map layout or report.
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
Add a legend to a map layout or report.
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
Add a scale bar to a map layout or report.
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
DELETE /v1/gisBB/reporting/scaleBars/{scaleBarId} HTTP/1.1
Host: host
Accept: */*
No content
Add a north arrow to a map layout or report.
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
DELETE /v1/gisBB/reporting/northArrows/{northArrowId} HTTP/1.1
Host: host
Accept: */*
No content
8.7 Geofencing
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
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
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
DELETE /v1/gisBB/geofencing/geofences/{geofenceId}/elements/{elementId} HTTP/1.1
Host: host
Accept: */*
No content
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
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
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?