Skip to content

OGC Features API

Overview

In this exercise we'll be configuring MapServer to serve out data using the MapServer's OGC Features API. See the OGC Features Overview page for more details.

Configuring your Mapfile

As with other OGC services most configuration is done using METADATA blocks. The prefix for the OGC Features API metadata settings is oga_.

To enable the OGC Features API enable it in the WEB METADATA, using either ows_enable_request or oga_enable_request. We also need to set the oga_onlineresource value to the root of the service:

WEB
    METADATA
        ...
        ows_enable_request "*" # this enables all OGC requests
        oga_onlineresource "/ogcfeatures/ogcapi"
    END
END

At the LAYER level gml_featureid needs to refer to field name containing a unique value for each feature.

METADATA
    ...
    gml_include_items "all"
    gml_featureid "osm_id"
END

The MapServer CONFIG File

In MapServer version 8.0 a new global CONFIG file was added.

This allows us to set which URL path is handled by which Mapfile.

The file is located at workshop\exercises\mapfiles\mapserver.conf (in the same folder as the Mapfiles), and is read by the Docker container.

Tip

mapserver.conf can be edited, but any changes will only come into effect when Apache is restarted. As this is running in Docker, we restart the Docker mapserver container:

docker restart mapserver

The key part of the CONFIG file are the MAPS section where a URL paths are paired with Mapfiles:

  MAPS
    OGCFEATURES "/etc/mapserver/ogcfeatures.map"
  END

The other relevant setting is the environment variable OGCAPI_HTML_TEMPLATE_DIRECTORY in the ENV section. This points to a folder containing templates used to create the HTML interface when browsing the OGC Features API: 

ENV
    OGCAPI_HTML_TEMPLATE_DIRECTORY "/usr/local/share/mapserver/ogcapi/templates/html-bootstrap4/"
END

Browsing the OGC Features API Collections

The OGC Features API can be viewed as HTML pages, which are rendered using templates provided by MapServer. They can also be accessed as JSON.

The services use hierarchical URLs for example:

Adding OGC Features to OpenLayers

As the OGC Features API returns GeoJSON, adding a vector layer to OpenLayers is straightforward. We simply pass in the URL pointing to the collection items:

new VectorLayer({
    style: {
        'fill-color': 'rgba(255, 255, 0, 0.7)',
        'stroke-width': 1.3,
    },
    source: new Vector({
        url: mapserverUrl + 'ogcfeatures/ogcapi/collections/pois_polygon/items?f=json&limit=500',
        format: new GeoJSON(),
    }),
}),

Code

Example

Javascript 
import '../css/style.css';
import Vector from 'ol/source/Vector.js';
import Map from 'ol/Map.js';
import GeoJSON from 'ol/format/GeoJSON.js';
import OSM from 'ol/source/OSM.js';
import View from 'ol/View.js';
import { Vector as VectorLayer, Tile as TileLayer } from 'ol/layer.js';

const mapserverUrl = import.meta.env.VITE_MAPSERVER_OGC_BASE_URL;

const layers = [
    new TileLayer({
        source: new OSM(),
    }),
    new VectorLayer({
        style: {
            'fill-color': 'rgba(255, 255, 0, 0.7)',
            'stroke-width': 1.3,
        },
        source: new Vector({
            url: mapserverUrl + 'ogcfeatures/ogcapi/collections/pois_polygon/items?f=json&limit=500',
            format: new GeoJSON(),
        }),
    }),
];
const map = new Map({
    layers: layers,
    target: 'map',
    view: new View({
        center: [2975862.75916499, 8046369.8646329],
        zoom: 13,
    }),
});
Mapfile 
MAP
  NAME "OGC Features"
  EXTENT 26.668678 58.339241 26.796582 58.409410
  UNITS DD
  SIZE 800 600

  PROJECTION
    "init=epsg:4326"
  END

  WEB
    METADATA
      "ows_title" "OSM Features"
      "ows_enable_request" "*" # this enables all OGC requests
      "ows_srs" "EPSG:4326 EPSG:3857"
      "oga_onlineresource" "/ogcfeatures/ogcapi"
      # "oga_html_template_directory"
      # "oga_enable_request" "*"
    END
  END

  LAYER
    NAME "pois"
    STATUS OFF
    TYPE POINT
    TEMPLATE "void"

    METADATA
      "ows_title" "Point POIs"
      "gml_include_items" "all"
      "gml_featureid" "osm_id"
    END
    CONNECTIONTYPE OGR
    CONNECTION "data/osm/pois.fgb"
  END

  LAYER
    NAME "pois_polygon"
    STATUS OFF
    TYPE POLYGON
    TEMPLATE "void"

    METADATA
      "ows_title" "Polygon POIs"
      "gml_include_items" "all"
      "gml_featureid" "osm_id"
    END
    CONNECTIONTYPE OGR
    CONNECTION "data/osm/pois_a.fgb"
  END

END

Exercises

  1. Modify the workshop\exercises\mapfiles\railways.map to enable the OGC Features API. You will need to add a new entry to the MAPS section in workshop\exercises\mapfiles\mapserver.conf and restart the Docker container to be able to browse the OGC Features API interface. 

    MAPS
    ...
    RAILWAYS "/etc/mapserver/railways.map"
END

    You also need to add the following to WEB METADATA so MapServer can correctly construct the URLs: "oga_onlineresource" "/railways/ogcapi"

    Tip

    You need to add TEMPLATE "void" to each of the layers you want to make available through the OGC Features API. TEMPLATE is a left-over from when HTML templates were used to return features, and allows the layer to be queried.

    Once setup correctly you should be able to browse the OGC Features API at http://localhost:5000/railways/ogcapi/.

Possible Errors

  • {
    "code": "ConfigError",
    "description": "InjaError error. [inja.exception.file_error] failed accessing file at '/etc/mapserver/landing.html' (landing.html). (/etc/mapserver/)."
}

    oga_html_template_directory can be set either at the Mapfile level or in the CONFIG file. Mapfile takes precedence.