Indexing OGC API Features

You can index the items of a collection of an OGC API Features service. To do this, you must create a mapping of the properties of an item to fields in the Solr schema. This page explains the necessary steps by means of a sample configuration that ships with smart.finder (see Data basis).

Requirements

The service must deliver the items as GeoJSON and link the pages of a collection with a link that has rel="next". This conforms to the OGC API - Features specification. The items are requested with the parameter limit. The next links are followed until no further page follows.

Note the following limitations:

  • Only geometries in the coordinate reference system WGS 84 (longitude/latitude) are supported, according to CRS84 . This is the default coordinate reference system of GeoJSON.

  • Nested JSON objects in the properties of an item are not indexed. Arrays are written as multiple values to the index field.

Data basis

smart.finder ships with a sample configuration for indexing OGC API Features. You can find it in the file /smartfinder-search/WEB-INF/classes/spring-ogc-features-config.xml.

The sample configuration helps you in two ways:

  • For understanding: It shows a complete, working case of how the collections of an OGC API Features service are mapped to the Solr schema. All following sections of this page refer to this example.

  • As a template: You can use the configuration as a blueprint for your own services. To do so, adopt its structure and adapt the service URL, the collections, and the property mapping to your service.

The example uses the publicly available service "Geotope NRW" (https://www.ogc-api.nrw.de/inspire-am-geotope) and indexes both of its collections:

Collection ID Title Geometry

AM_Geotope_Polygone

Geotope - Polygone

MultiPolygon

AM_Geotope_Punkte

Geotope - Punkte

Point

The items of both collections have the same properties. The names contain dots, for example zone_type.title. These are plain names that the service delivers as they are, not nested objects. Use these names unchanged in the configuration.

The sample configuration maps the following properties:

  • inspireId.localId

  • geographical_name

  • zone_type.title

The ID of an item is unique only within a collection. Therefore, the example uses inspireId.localId as the identifier. You can map the ID of an item to a field by using the name id.

Linking the OGC API collection and the Solr schema

The link between the properties of the items and the Solr schema is set up in the file /smartfinder-search/WEB-INF/classes/spring-ogc-features-config.xml.

The following listing shows an excerpt from that file:

spring-ogc-features-config.xml
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:util="http://www.springframework.org/schema/util"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
                            http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-3.0.xsd">
    <!-- Base configuration that is used by all collections of the service -->
    <bean class="de.conterra.smartfinder.api.feature.ogcapi.OgcCollectionConfiguration" name="ogcBaseConfiguration">
        <property name="serviceUrl" value="https://www.ogc-api.nrw.de/inspire-am-geotope"/>
        <property name="limit" value="100"/>
        <property name="fieldsConfig">
            [...]
        </property>
        <property name="titleFields">
            [...]
        </property>
        <property name="constantFieldValues">
            [...]
        </property>
    </bean>
    <util:list id="ogcCollectionConfigurations">
        <!-- Configuration for indexing the collection AM_Geotope_Polygone -->
        <bean class="de.conterra.smartfinder.api.feature.ogcapi.OgcCollectionConfiguration">
            <!-- The parent configuration that should be used -->
            <constructor-arg name="parentConfiguration" ref="ogcBaseConfiguration"/>
            <!-- ID of the collection that should be indexed -->
            <property name="collectionId" value="AM_Geotope_Polygone"/>
            <!-- Name of the collection that will appear in the UI (faceted search) -->
            <property name="descriptiveName" value="Geotope NRW - Flächen"/>
        </bean>
        <!-- Configuration for indexing the collection AM_Geotope_Punkte -->
        <bean class="de.conterra.smartfinder.api.feature.ogcapi.OgcCollectionConfiguration">
            <constructor-arg name="parentConfiguration" ref="ogcBaseConfiguration"/>
            <property name="collectionId" value="AM_Geotope_Punkte"/>
            <property name="descriptiveName" value="Geotope NRW - Punkte"/>
            <!-- Overrides the inherited limit -->
            <property name="limit" value="50"/>
            [...]
        </bean>
    </util:list>
</beans>

The central part of the configuration is defining ogcCollectionConfiguration objects, i.e. a bean of type de.conterra.smartfinder.api.feature.ogcapi.OgcCollectionConfiguration. An ogcCollectionConfiguration describes how a specific collection should be indexed. You must specify it as a bean element inside the <util:list id="ogcCollectionConfigurations">..</util:list> element. Only the configurations in this list are taken into account when indexing.

The example uses the inheritance of settings that is described at Inheritance of settings: The base configuration ogcBaseConfiguration contains everything that the collections of the service have in common. Each collection refers to this base configuration with parentConfiguration and defines only what is specific to it. The collection AM_Geotope_Punkte overrides the inherited value limit.

The following listing shows the complete base configuration of the example:

<bean class="de.conterra.smartfinder.api.feature.ogcapi.OgcCollectionConfiguration" name="ogcBaseConfiguration">
    <property name="serviceUrl" value="https://www.ogc-api.nrw.de/inspire-am-geotope"/>
    <property name="limit" value="100"/>
    <property name="indexGeometry" value="true"/>
    <property name="fieldsConfig">
        <bean class="de.conterra.smartfinder.api.feature.FieldsIndexingConfig">
            <property name="fieldToSchemaMappings">
                <list>
                    <bean class="de.conterra.smartfinder.api.feature.FieldToSchemaMapping">
                        <property name="featureFieldName" value="inspireId.localId"/>
                        <property name="indexFieldName" value="identifier"/>
                    </bean>
                    <bean class="de.conterra.smartfinder.api.feature.FieldToSchemaMapping">
                        <property name="featureFieldName" value="geographical_name"/>
                        <property name="indexFieldName" value="poi_name"/>
                    </bean>
                    <bean class="de.conterra.smartfinder.api.feature.FieldToSchemaMapping">
                        <property name="featureFieldName" value="zone_type.title"/>
                        <property name="indexFieldName" value="zone_type"/>
                        <property name="indexFieldType" value="string"/>
                    </bean>
                </list>
            </property>
        </bean>
    </property>
    <property name="titleFields">
        <list>
            <bean class="de.conterra.smartfinder.api.feature.TitleField">
                <property name="name" value="geographical_name"/>
            </bean>
        </list>
    </property>
    <property name="constantFieldValues">
        <list>
            <bean class="de.conterra.smartfinder.api.feature.ConstantFieldValue">
                <property name="indexFieldName" value="dataSource"/>
                <property name="value" value="Geotope NRW"/>
            </bean>
            <bean class="de.conterra.smartfinder.api.feature.ConstantFieldValue">
                <property name="indexFieldName" value="keywords"/>
                <property name="values">
                    <list>
                        <value>Geotop</value>
                        <value>INSPIRE</value>
                    </list>
                </property>
            </bean>
        </list>
    </property>
</bean>

Parameters of an ogcCollectionConfiguration

The parameters fieldsConfig, titleFields, descriptiveName, indexGeometry, and constantFieldValues are the same for ArcGIS Server layers and OGC API Features. They are described at Common parameters. For OGC API Features, featureFieldName is the name of a property of the item.

Parameters annotated with required must be set either in the ogcCollectionConfiguration object or in a referenced parent ogcCollectionConfiguration.

The following list describes the parameters that apply only to OGC API Features.

serviceUrl (required)

Base URL of the OGC API Features service, that is, the URL of its landing page. Specify the URL without a trailing slash.

Together with the collectionId, this parameter determines the URL of the items that is the source of the indexing job, see Indexing the collection.

Example:

<property name="serviceUrl" value="https://www.ogc-api.nrw.de/inspire-am-geotope"/>
collectionId (required)

ID of the collection to be indexed. You find the IDs of all collections of a service at <serviceUrl>/collections.

Example:

<property name="collectionId" value="AM_Geotope_Punkte"/>
limit

Maximum number of requested items per request against the service. The value is passed as the parameter limit.

If this value is not set, the globally configured value of the property indexing.ogc.items.limit is used.

Default: 100

If the service delivers fewer items per page than requested, the next links are still followed. Decrease the value if the service returns errors for large pages or takes too long to respond.

Example:

<property name="limit" value="100"/>

The global settings for the indexing of OGC API Features, for example the number of retries after a failed request, are described in the update notes of version 3.2.

Indexing the collection

To index the collection, you must create an indexing job for a resource of the type URL in the Job Manager.

The URL of this job points to the items of the collection that you defined in the configuration. Based on that configuration, the URL is: <serviceUrl>/collections/<collectionId>/items.

For the collection AM_Geotope_Punkte of the example, the URL is: https://www.ogc-api.nrw.de/inspire-am-geotope/collections/AM_Geotope_Punkte/items

Note the following:

  • The URL must end with /items. The indexing service for OGC API Features is selected based on this ending. A URL that points to the collection itself, for example …​/collections/AM_Geotope_Punkte, is not indexed as OGC API Features.

  • The beginning of the URL must match the serviceUrl of the configuration exactly. This includes the protocol (http or https), the host, and uppercase and lowercase letters.

  • A trailing slash and parameters such as ?limit=10 are ignored when the configuration is looked up.

  • If there is no matching and valid OgcCollectionConfiguration for the URL, the job aborts with an error message.

After the job starts, the properties of the items are indexed according to the configuration.

Result of the indexing

After indexing, each item of the collection is a document in the index. The field layer contains the descriptiveName of the configuration. The field title contains the title that is assembled from the titleFields. Unless you disable indexGeometry, the field spatial contains the geometry of the item as WKT.