en

Dataset and Catalogue Service API

Accessing dataset using our Geospatial Services

  1. You can find Geospatial Services, also known as Dataset API, on the dataset detail page for the selected dataset:

    • OGC Web Feature Service (OGC WFS)
    • OGC Web Map Service (OGC WMS)
    • ArcGIS REST API (ARCGIS)

What are GeoSpatial Services?

GeoSpatial Services are application development or programming interfaces for users and developers to utilize the datasets provided on Common Spatial Data Infrastructure (CSDI) Portal in developing relevant application or programs for users in different aspects. The CSDI Portal currently supports OGC WFS, OGC WMS, and ArcGIS REST API.

What are OGC WFS, OGC WMS and ArcGIS REST API?

OGC WFS and OGC WMS both follow the standards set by the Open Geospatial Consortium (OGC), an international standards organization that promotes and develops open standards for geospatial data and services.

With OGC WFS, users can access vector data and perform various operations, such as querying, filtering, and data retrieval.

With OGC WMS, users can access map images and display them in their web browser or desktop GIS software.

ArcGIS REST API is similar to OGC WFS, which provides service using ESRI structure.

How do I access OGC WFS, OGC WMS and ArcGIS REST API on CSDI Portal?

To access the OGC WFS, OGC WMS and ArcGIS REST API, simply navigate to Dataset Detail Page of an dataset and click GeoSpatial Service under Other Resources and Services Section. Select and click the service link (OGC WFS/OGC WMS/ARCGIS) you wish to use and it will be copied automatically.

How do I customize my OGC WFS/OGC WMS/ArcGIS REST API request based on the copied URL?

Please select OGC WFS/OGC WMS/ArcGIS REST API for details:

OGC WFS URL Format 

https://[OGC WFS URL]?[SERVICE]&[VERSION]&[REQUEST]&[TYPENAME]&[OUTPUTFORMAT]&[SRSNAME]&[BBOX]&[COUNT]

OGC WFS Example URL 

https://portal.csdi.gov.hk/server/services/common/landsd_rcd_1648571595120_89752/MapServer/WFSServer?service=WFS&version=2.0.0&request=GetFeature&typename=GEO_PLACE_NAME&outputFormat=GeoJSON&srsname=EPSG:4326&bbox=22.262474243164064,114.1035038986206,22.32152575683594,114.25302095794677&count=100

OGC WFS Query Parameters

Parameter Sample Value Description
SERVICE WFS Service name. Value is “WFS”.
VERSION 2.0.0 Service version. Values are “1.0.0”, “1.1.0” & “2.0.0” (recommended).
REQUEST GetFeature Requested operation. Typical values are "GetFeature", “GetCapabilities”, etc.
TYPENAME GEO_PLACE_NAME Collection of feature instance(s) to be returned. TYPENAMES can be obtained via “GetCapabilities”.
OUTPUTFORMAT GeoJSON The returned data format. Common formats include “GeoJSON”, “GML32”, “CSV”, etc.
SRSNAME EPSG:4326 Spatial Reference System. Supported values are “EPSG:4326” and “EPSG:2326”.
BBOX# 22.262474243164064,
114.1035038986206,
22.32152575683594,
114.25302095794677 		Bounding Box. Values should be in the format of “minx,miny,maxx,maxy”.
COUNT# 100 Number of features to be returned. The maximum value is “10,000”.

# Optional Parameters

Sample Source Code and Preview

How do I work with the data returned by a OGC WFS/OGC WMS/ArcGIS REST API request?

You can work with the data returned by a OGC WFS/OGC WMS/ArcGIS REST API request using a compatible software tool, such as a GIS or web mapping application. You can also use a variety of analysis and visualization tools to explore and analyze the data further.

You can refer to the following page for instructions on how to add and visualize OGC WFS, OGC WMS data in QGIS.

Adding WFS and WMS to QGIS

Where can I find documentation and tutorials for using OGC WFS, OGC WMS and ArcGIS REST API?

You can use the information and sample source code on this page as a reference while using OGC WFS, OGC WMS and ArcGIS REST API. For further technical information on OGC WFS, OGC WMS and ArcGIS REST API, you may make reference to the following web links.

OGC Standard - Web Feature Service (WFS)
OGC Standard - Web Map Service (WMS)
ArcGIS REST API

You may also see following technical guides.

OGC e-Learning - Data Access Standards WFS
OGC e-Learning - Visualization Standards WMS
ESRI - Communicating with a WFS service in a web browser
ESRI - Communicating with a WMS service in a web browser
ESRI - Feature service

Finding the Dataset API Explorer

  1. Dataset API Explorer is a tool that allows users to explore and interact with an API that provides a simple and intuitive access to a CSDI dataset.

Using the Dataset API Explorer

  1. You can select the API that best suits your requirements. Currently, the Dataset API Explorer supports OGC WFS (recommended for use with vector dataset), OGC WMS (recommended for use with imagery or raster dataset), and DQS.
  2. Some datasets may include several layers. You can choose the layer from which to retrieve data.
  3. You can easily create the query string by entering values for each parameter.
  4. After configuring all mandatory parameters, click the “Execute” button to view the results in JSON format if you are using OGC WFS or DQS. If you are using OGC WMS, it will return a map image.

Accessing metadata using OGC Catalogue Service (CSW)

What is OGC Catalogue Service for the Web (CSW)?

The Catalogue Service for the Web (CSW) is a standard set by the Open Geospatial Consortium (OGC). OGC is an international standards organisation that promotes and develops open standards for geospatial data and services. CSW allows geospatial data portals to publish collections of metadata—descriptive information about geospatial data and services—while enabling users to search through that metadata. Our CSDI Portal already supports CSW, allowing users to retrieve and display data items from our catalog using CSW requests.

How do I utilize CSW from the CSDI Portal?

To get started with CSW from CSDI Portal, you can use the following URL endpoint:
https://portal.csdi.gov.hk/geoportal/csw

CSW supports the following four types of requests:

  1. GetCapabilites,
  2. DescribeRecord,
  3. GetRecords, and
  4. GetRecordById

To issue a CSW request, you need to add a parameter to the URL endpoint after a ‘?’ symbol. If multiple parameters are required, you can use the ‘&’ symbol as a separator.

1. GetCapabilities:

Using the GetCapabilities request, you can access the information (both mandatory and optional parameters) that you can consume with the CSW.

To access CSW GetCapabilities operation:

CSW GetCapabilities Example URL:
https://portal.csdi.gov.hk/geoportal/csw?service=CSW&request=GetCapabilities&version=2.0.2

Query Parameter:
Parameter Mandatory Sample Value Description
service Yes CSW Service name. Value is “CSW”.
request Yes GetCapabilities Requested operation. “GetCapabilities” allow users to retrieve service metadata.
version Yes 2.0.2 Service version. Value is “2.0.2”.
2. DescribeRecord:

This request retrieves elements from the information model in the catalog. For example, it defines which information items will be included when the ElementSetName is set to "full," "summary," or "brief." The ElementSetName is used in the GetRecords and GetRecordById requests to determine the level of detail in the response.

To access CSW DescribeRecord operation:

CSW DescribeRecord Example URL:
https://portal.csdi.gov.hk/geoportal/csw?service=CSW&version=2.0.2&request=DescribeRecord

Query Parameter:
Parameter Mandatory Sample Value Description
service Yes CSW Service name. Value is “CSW”.
version Yes 2.0.2 Service version. Value is “2.0.2”.
request Yes DescribeRecord Requested operation. “DescribeRecord” allows users to discover elements of the information model supported by the target catalogue service.
3. GetRecords:

This operation allows to search for records and get their metadata and identifier. The parameter and value VERSION=2.0.2 are mandatory. The parameter and value resultType=results should be added to obtain the records, metadata and identifier.

To access CSW GetRecords operation:

CSW GetRecords Example URL:
https://portal.csdi.gov.hk/geoportal/csw?service=CSW&version=2.0.2&request=GetRecords&typeNames=csw:Record&outputSchema=http://www.opengis.net/cat/csw/2.0.2&resultType=results&startPosition=1&maxRecords=10&elementSetName=full&q=building

Query Parameter:
Parameter Mandatory Sample Value Description
service Yes CSW Service name. Value is “CSW”.
version Yes 2.0.2 Service version. Value are “2.0.2” or “3.0.0”.
request Yes GetRecords Requested operation. “GetRecords” allows users to discover datasets.
typeNames Yes csw:Record Collection of feature instance(s) to be returned. Value is “csw:Record”.
outputSchema No http://www.opengis.net/cat/csw/2.0.2 Output schema to be generated. Value can be “http://www.opengis.net/cat/csw/3.0” or “http://www.opengis.net/cat/csw/2.0.2”.
resultType No Results Information to be returned. Value can be “hits”, “result” or “validate”.
startPosition No 1 Information to be returned. Value can be “hits”, “result” or “validate”.
maxRecords No 10 Maximum number of records to be returned. Value must be a positive integer.
elementSetName No Brief Level of details present in the result. Value can be “full”, “summary”, or “brief”.
q No Building Keyword to search.
4. GetRecordById:

This operation allows to search for a record with a specific identifier.

To access CSW GetRecordById operation:

CSW GetRecordById Example URL:
https://portal.csdi.gov.hk/geoportal/csw?service=CSW&version=2.0.2&request=GetRecordById&id=bd_rcd_1630980798477_25751

Query Parameter:
Parameter Mandatory Sample Value Description
service Yes CSW Service name. Value is “CSW”.
version Yes 2.0.2 Service version. Value are “2.0.2” or “3.0.0”.
request Yes GetRecordById Requested operation. “GetRecordById” allows the users retrieve the catalog records using identifier.
id Yes bd_rcd_1630980798477_25751 Dataset identifier.

How do I work with the data returned by CSW request?

You can work with the data returned by CSW requests for data integration, data analysis, datasets sharing, dataset searching and metadata harvesting. You can also use a variety of visualization and analysis tools to explore and analyze the data further, for example QGIS.

Where can I find documentation and tutorials for using CSW?

You can use the information and sample source code on this page as a reference while using CSW service. For further technical information on the CSW service, you may refer to the following documents.

OGC – Catalogue Service
https://www.ogc.org/publications/standard/cat/

MetaSearch – A CSW client for QGIS
https://docs.qgis.org/3.40/en/docs/user_manual/plugins/core_plugins/plugins_metasearch.html