Provincial GIS Server API

Version 1.0 (GeoServer / OGC Services)

---

1. Introduction

This document describes how to integrate Provincial GIS data hosted on a GIS Server instance into external web and desktop applications. GeoServer is an open‑source server that implements industry‑standard OGC (Open Geospatial Consortium) protocols: WMS (Web Map Service), WFS (Web Feature Service), WCS (Web Coverage Service), and WMTS (Web Map Tile Service). These protocols allow any OGC‑compliant client – from web mapping libraries to desktop GIS software – to access and display geospatial data.

By following this guide, developers will be able to:

• Discover available data layers.
• Retrieve styled maps (PNG, JPEG) for display.
• Download vector features (GeoJSON, GML, Shapefile) for analysis.
• Access raster coverages (GeoTIFF, etc.).
• Consume tiled maps for high‑performance web applications.

All endpoints are based on the provincial GeoServer instance at https://gis.ecotp.gov.za/geoserver/ecpg/wms.

2. Base URL and Service Endpoints

The base URL for all OGC services is:

https://gis.ecotp.gov.za/geoserver/ecpg/wms

Individual service endpoints are accessed by appending the service name and version:

Service	Typical Endpoint (with required parameters)
WMS	https://gis.ecotp.gov.za/geoserver/ecpg/wms?service=WMS&version=1.3.0&request=...
WFS	https://gis.ecotp.gov.za/geoserver/ecpg/wfs?service=WFS&version=2.0.0&request=...
WCS	https://gis.ecotp.gov.za/geoserver/ecpg/wcs?service=WCS&version=2.0.1&request=...
WMTS	https://gis.ecotp.gov.za/geoserver/ecpg/gwc/service/wmts?request=GetCapabilities
REST	https://gis.ecotp.gov.za/geoserver/ecpg/rest/... (admin)

Note: GeoServer also supports tiled WMS via GeoWebCache, which can be accessed through the same WMS endpoint with additional tiled=true parameter or through dedicated WMTS.

3. Authentication

Access to public data layers may be unrestricted. However, some layers (e.g., sensitive cadastral information) require authentication.

If authentication is required, use HTTP Basic Authentication with a username and password provided by the Provincial GIS department.

Example with curl:

curl -u username:password "https://gis.ecotp.gov.za/geoserver/ecpg/wfs?service=WFS&version=2.0.0&request=GetCapabilities"

Alternatively, an API key may be passed as a query parameter or header. Consult the specific layer metadata for requirements.

4. Discovering Available Data

Before accessing data, you need to know which layers are available and their properties. GeoServer provides GetCapabilities documents for each service.

WMS GetCapabilities

Request the WMS capabilities to get a list of all vector and raster layers that can be displayed as maps.

URL:

GET https://gis.ecotp.gov.za/geoserver/ecpg/wms?service=WMS&version=1.3.0&request=GetCapabilities

Response: XML document describing:

• Service metadata (title, abstract, keywords)
• Available layers with their names, titles, bounding boxes, coordinate reference systems, and styles.

Key element: <Layer> – each layer has a <Name> that you will use in subsequent requests (e.g., province:parcels).

WFS GetCapabilities

For vector feature access, request the WFS capabilities.

URL:

GET https://gis.ecotp.gov.za/geoserver/ecpg/wfs?service=WFS&version=2.0.0&request=GetCapabilities

Response: XML describing feature types (layers) and their attribute schemas. The <Name> (e.g., province:roads) is used in WFS requests.

WCS GetCapabilities

For raster coverages (elevation, satellite imagery, etc.):

URL:

GET https://gis.ecotp.gov.za/geoserver/ecpg/wcs?service=WCS&version=2.0.1&request=GetCapabilities

Response: XML with coverage offerings and their formats.

5. Accessing Map Images (WMS)

WMS is used to retrieve georeferenced map images (PNG, JPEG, etc.) for display in web or desktop applications.

GetMap Request

Mandatory parameters:

• service=WMS
• version=1.3.0
• request=GetMap
• layers – comma‑separated list of layer names (e.g., province:parcels,province:roads)
• styles – empty or style names (e.g., "" for default)
• bbox – bounding box in the coordinate system of the map (for WMS 1.3.0, order depends on CRS axis orientation; usually minx,miny,maxx,maxy for EPSG:4326)
• width – image width in pixels
• height – image height in pixels
• format – image format (e.g., image/png, image/jpeg)
• crs – coordinate reference system (e.g., EPSG:4326, EPSG:3857)

Example GetMap URL:

https://gis.ecotp.gov.za/geoserver/ecpg/wms?service=WMS&version=1.3.0&request=GetMap
&layers=province:parcels&styles=&bbox=-124,48,-122,49&width=800&height=600
&format=image/png&crs=EPSG:4326

Response: The requested image (PNG, JPEG, etc.).

WMS Layer in OpenLayers

import Map from 'ol/Map';
import View from 'ol/View';
import TileLayer from 'ol/layer/Tile';
import TileWMS from 'ol/source/TileWMS';

const parcels = new TileLayer({
  source: new TileWMS({
    url: 'https://gis.ecotp.gov.za/geoserver/ecpg/wms',
    params: {
      'LAYERS': 'province:parcels',
      'TILED': true
    },
    serverType: 'geoserver'
  })
});

const map = new Map({
  target: 'map',
  layers: [parcels],
  view: new View({
    projection: 'EPSG:3857',
    center: [-13600000, 6400000],
    zoom: 8
  })
});

Adding WMS to QGIS

1. Open QGIS.
2. Go to Layer → Add Layer → Add WMS/WMTS Layer.
3. Click New to create a new connection.
4. Set Name (e.g., "Provincial GIS") and URL to https://gis.ecotp.gov.za/geoserver/ecpg/wms?.
5. Click OK, then Connect.
6. Select desired layers from the list and click Add.

Adding WMS to ArcGIS Pro

1. Open ArcGIS Pro
2. On the Insert Tab in the project group → connections → Server.
3. Click New WMS Server to create a new connection.The Add WMS Server Connection dialog box appears
4. Type the Server URL: Server URL: https://gis.ecotp.gov.za/geoserver/ecpg/wms?
5. Click OK
6. Select desired layers from the list and click Add.

6. Accessing Vector Features (WFS)

WFS allows you to query and download actual geometry and attribute data in formats like GML, GeoJSON, Shapefile, etc.

GetFeature Request

Mandatory parameters:

• service=WFS
• version=2.0.0 (or 1.1.0)
• request=GetFeature
• typeNames – feature type name(s) (e.g., province:parcels)
• outputFormat – desired format (e.g., application/json for GeoJSON, shape-zip for zipped shapefile, gml3 for GML)

Optional parameters:

• bbox – spatial filter (in WGS84 or layer's CRS)
• filter – XML or CQL filter for attribute constraints
• propertyName – comma‑separated list of attributes to return
• maxFeatures – limit number of features
• srsName – output CRS (e.g., EPSG:4326)

Example GetFeature URL (GeoJSON):

https://gis.ecotp.gov.za/geoserver/ecpg/wfs?service=WFS&version=2.0.0&request=GetFeature
&typeNames=province:parcels&bbox=-124,48,-122,49&outputFormat=application/json
&maxFeatures=100

Response: GeoJSON FeatureCollection.

Filtering with CQL

GeoServer supports CQL (Common Query Language) for flexible filtering. Use the cql_filter parameter.

Example: Find parcels with area > 5000 and owner name containing "Smith"

&cql_filter=area > 5000 AND owner LIKE '%Smith%'

URL encoding is required.

Fetching Features with JavaScript (Fetch API)

const url = 'https://gis.ecotp.gov.za/geoserver/ecpg/wfs?service=WFS&version=2.0.0' +
            '&request=GetFeature&typeNames=province:parcels' +
            '&bbox=-124,48,-122,49&outputFormat=application/json&maxFeatures=50';

fetch(url)
  .then(response => response.json())
  .then(data => {
    console.log('Received', data.features.length, 'features');
    // process GeoJSON
  });

WFS Layer in QGIS

1. In QGIS, go to Layer → Add Layer → Add WFS Layer.
2. Click New and enter:
   • Name: Provincial WFS
   • URL: https://gis.ecotp.gov.za/geoserver/ecpg/wfs
3. Click OK, then Connect.
4. Select a feature type (e.g., province:parcels), choose desired format (e.g., GeoJSON), and click Add.
5. Optionally, apply a filter by clicking Build query to use CQL.

Adding WMF to ArcGIS Pro

1. Open ArcGIS Pro
2. On the Insert Tab in the project group → connections → Server.
3. Click New WFS Server to create a new connection.The Add WFS Server Connection dialog box appears
4. Type the Server URL: Server URL: https://gis.ecotp.gov.za/geoserver/ecpg/wfs?
5. Click OK
6. Select desired layers from the list and click Add.

7. Accessing Raster Data (WCS)

WCS provides access to raw raster data (coverages) such as digital elevation models, land cover grids, etc. Data can be downloaded in formats like GeoTIFF.

GetCoverage Request

Mandatory parameters:

• service=WCS
• version=2.0.1
• request=GetCoverage
• coverageId – identifier of the coverage (e.g., province:dem)
• format – desired format (e.g., image/tiff, application/x‑netcdf)

Optional parameters:

• subset – spatial and temporal subsets (e.g., subset=Lat(48,49), subset=Long(-124,-122))
• scaleFactor or width/height – scaling
• crs – output CRS

Example GetCoverage URL (GeoTIFF):

https://gis.ecotp.gov.za/geoserver/ecpg/wcs?service=WCS&version=2.0.1&request=GetCoverage
&coverageId=province:dem&format=image/tiff&subset=Lat(48,49)&subset=Long(-124,-122)

Response: Binary GeoTIFF file.

8. Tiled Services (WMTS)

For high‑performance web mapping, GeoServer includes GeoWebCache, which provides tiles in WMTS and other formats. WMTS offers static tiles (vector or raster) at predefined zoom levels.

WMTS GetTile

Mandatory parameters:

• service=WMTS
• request=GetTile
• version=1.0.0
• layer – layer name (e.g., province:parcels)
• style – style name (e.g., default)
• format – tile format (e.g., image/png, application/vnd.mapbox-vector-tile for vector tiles)
• tileMatrixSet – tiling scheme (e.g., EPSG:900913, EPSG:4326)
• tileMatrix – zoom level
• tileRow – row index
• tileCol – column index

Alternatively, use the simplified XYZ template often used by web maps:

https://gis.ecotp.gov.za/geoserver/ecpg/gwc/service/wmts?layer=province:parcels&style=&tilematrixset=EPSG:900913&Service=WMTS&Request=GetTile&Version=1.0.0&Format=image/png&TileMatrix={z}&TileCol={x}&TileRow={y}

Example: WMTS in Leaflet (with TileLayer)

L.tileLayer('https://gis.ecotp.gov.za/geoserver/ecpg/gwc/service/wmts?' +
            'layer=province:parcels&style=&tilematrixset=EPSG:900913' +
            '&Service=WMTS&Request=GetTile&Version=1.0.0&Format=image/png' +
            '&TileMatrix={z}&TileCol={x}&TileRow={y}', {
  maxZoom: 18,
  attribution: 'Provincial GIS'
}).addTo(map);

For vector tiles (MVT), set Format=application/vnd.mapbox-vector-tile and use a library like Mapbox GL JS or OpenLayers.

9. GeoServer REST API (Optional)

GeoServer provides a RESTful API for administrative tasks such as creating workspaces, uploading data, and managing styles. This API is not intended for general data access, but may be used by advanced integrators for automation.

Base URL: https://gis.ecotp.gov.za/geoserver/ecpg/rest/

Authentication is required (usually HTTP Basic). For full documentation, see the GeoServer REST API reference.

Example: Get list of workspaces:

curl -u username:password https://gis.ecotp.gov.za/geoserver/ecpg/rest/workspaces.json

10. Error Handling

GeoServer returns standard OGC exception reports in XML or JSON (depending on format requested). HTTP status codes indicate the nature of the error:

• 200 – Successful request (even if no data, e.g., empty WFS response).
• 400 – Bad request (invalid parameters).
• 401 – Unauthorized (missing/invalid credentials).
• 404 – Not found (layer, feature, or resource).
• 500 – Internal server error.

Example WFS Exception (XML):

<ows:ExceptionReport xmlns:ows="http://www.opengis.net/ows" version="2.0.0">
  <ows:Exception exceptionCode="InvalidParameterValue" locator="typeNames">
    <ows:ExceptionText>Unknown feature type 'province:nonexistent'</ows:ExceptionText>
  </ows:Exception>
</ows:ExceptionReport>

In JSON outputFormat, the exception may be returned as a JSON object with "ows:ExceptionReport".

11. Best Practices and Limitations

• Use tiles for display: For web maps, always use WMTS or tiled WMS to reduce server load and improve performance.
• Limit WFS requests: When downloading vector data, use maxFeatures and bounding boxes to avoid large transfers. For bulk data, consider using the REST API or file downloads.
• Coordinate systems: Most web applications use EPSG:3857 (Web Mercator) for display. The server supports reprojection on the fly, but pre‑projected tiles are faster.
• CQL filters: Use CQL for attribute filtering; it's concise and well‑supported.
• Authentication: If using authenticated layers, ensure credentials are handled securely (never hard‑code in client‑side code).
• Rate limiting: Although GeoServer does not enforce strict rate limits by default, the Provincial GIS department may impose limits. Check the X‑RateLimit-* headers if present.

12. Appendix

Supported Coordinate Reference Systems

Common EPSG codes available:

• EPSG:4326 – WGS 84 (latitude/longitude)
• EPSG:4326 – WGS 84 (latitude/longitude)

See layer metadata for native CRS.

Common WMS/WFS Parameters

Parameter	Description
version	Service version (WMS:1.3.0, WFS:2.0.0, WCS:2.0.1)
request	Operation (GetMap, GetFeature, GetCoverage, GetCapabilities)
layers (WMS) / typeNames (WFS)	Layer(s) to query
bbox	Bounding box (minx,miny,maxx,maxy) in CRS coordinates
crs (WMS) / srsName (WFS)	Output coordinate reference system
format / outputFormat	Response format (image/png, application/json, shape‑zip, etc.)
width / height	Image dimensions (WMS only)
cql_filter	CQL filter expression (WFS)
maxFeatures	Maximum number of features to return (WFS)

Glossary

• WMS – Web Map Service: serves georeferenced map images.
• WFS – Web Feature Service: serves vector features with geometry and attributes.
• WCS – Web Coverage Service: serves raster coverages.
• WMTS – Web Map Tile Service: serves pre‑rendered map tiles.
• CQL – Common Query Language: a text‑based language for filtering.
• GeoServer – Open source server for sharing geospatial data.
• GeoWebCache – A caching component integrated with GeoServer that accelerates tile serving.

Change Log

Version	Date	Changes
1.0	20256-02-18	Initial GeoServer‑focused release.

---

For further assistance, contact Langalethu.Majola@ecotp.gov.za or visit the Provincial GIS Developer Portal.