Skip to content
🧭 Geospatial tools for Dart

Advanced topics

🔷 Feature data interfaces

A diagram describing the most important interfaces and classes needed when interacting with API services compliant with the OGC API Features standard:

Create feature service client instances

An OGC API Features service client can be created using the OGCAPIFeatures.http() constructor that is defined as:

OGCFeatureService http({
  required Uri endpoint,
  Client? client,
  Map<String, String>? headers,
  Map<String, String>? extraParams,
  TextReaderFormat<FeatureContent> format = GeoJSON.feature,
  Duration metaMaxAge = const Duration(minutes: 15),
});

This returns a client for accessing OGC API Features compliant sources via http(s) conforming to format.

Documentation about constructor parametrs:

  • The required endpoint should refer to a base url of a feature service.
  • When given an optional client is used for http requests, otherwise the default client of the package:http/http.dart package is used (a new instance of default client for each service request). When client is given, this allows a client to better maintain persistent connections to a service, but it’s also responsibility of a caller to close it appropriately. It’s also possible to set a standard RetryClient instance when retry-logic is needed.
  • When given headers are injected to http requests as http headers (however some can be overridden by the feature service implementation).
  • When given extraParams are injected to query part of http requests (however some can be overridden by the feature service implementation).
  • When format is not given, then GeoJSON with default settings is used as a default. Note that currently only GeoJSON is supported, but it’s possible to inject another format implementation (or with custom configuration) to the default one.
  • metaMaxAge specifies a max age to cache metadata objects retrieved from a service and that are cached internally (in-memory) by this client.

Using feature service clients

The OGC API Features service client created by OGCAPIFeatures.http() for some endpoint has the following signature:

/// A feature service compliant with the OGC API Features standard.
abstract class OGCFeatureService {
  /// Get meta data (or "landing page" information) about this service.
  Future<OGCServiceMeta> meta();


  /// Conformance classes this service is conforming to.
  Future<OGCFeatureConformance> conformance();


  /// Get metadata about feature collections provided by this service.
  Future<Iterable<OGCCollectionMeta>> collections();


  /// Get a feature source for a feature collection identified by [id].
  Future<OGCFeatureSource> collection(String id);
}

Using feature sources provided by service clients

The feature source returned by collection() provides following methods:

  /// Get metadata about the feature collection represented by this source.
  Future<OGCCollectionMeta> meta();


  /// Get optional metadata about queryable properties for the feature
  /// collection represented by this source.
  ///
  /// Returns null if no "queryables" metadata is available for this feature
  /// source.
  Future<OGCQueryableObject?> queryables();


  /// Fetches a single feature by [id] from this source.
  ///
  /// An identifier should be an integer number (int or BigInt) or a string.
  Future<OGCFeatureItem> itemById(Object id);


  /// Fetches a single feature by id (set in [query]) from this source.
  Future<OGCFeatureItem> item(ItemQuery query);


  /// Fetches all features items from this source.
  ///
  /// An optional [limit] sets maximum number of items returned. If given, it
  /// must be a positive integer.
  ///
  /// This call accesses only one set of feature items (number of returned items
  /// can be limited).
  Future<OGCFeatureItems> itemsAll({int? limit});


  /// Fetches all features as paged sets from this source.
  ///
  /// An optional [limit] sets maximum number of items returned. If given, it
  /// must be a positive integer.
  ///
  /// This call returns a first set of feature items (number of returned items
  /// can be limited), with a link to an optional next set of feature items.
  Future<Paged<OGCFeatureItems>> itemsAllPaged({int? limit});


  /// Fetches features matching [query] (and an optional [cql] query) from this
  /// source.
  ///
  /// If both [query] and [cql] are provided, then a service returns only
  /// features that match both [query] AND the [cql] query.
  ///
  /// This call accesses only one set of feature items (number of returned items
  /// can be limited).
  Future<OGCFeatureItems> items(
    BoundedItemsQuery query, {
    CQLQuery? cql,
  });


  /// Fetches features as paged sets matching [query] (and an optional [cql]
  /// query) from this source.
  ///
  /// If both [query] and [cql] are provided, then a service returns only
  /// features that match both [query] AND the [cql] query.
  ///
  /// This call returns a first set of feature items (number of returned items
  /// can be limited), with a link to an optional next set of feature items.
  Future<Paged<OGCFeatureItems>> itemsPaged(
    BoundedItemsQuery query, {
    CQLQuery? cql,
  });

Specifying queries

Queries for items and itemsPaged are normally specified by BoundedItemsQuery instances:

  /// An optional coordinate reference system used by [bbox].
  final CoordRefSys? bboxCrs;


  /// An optional [bbox] as a geospatial bounding filter (like `bbox`).
  final Box? bbox;


  /// An optional time frame as a temporal object (ie. instant or interval).
  final Temporal? timeFrame;


  /// An optional id defining a coordinate reference system for result data.
  final CoordRefSys? crs;


  /// Optional query parameters for queries as a map of named parameters.
  final Map<String, dynamic>? parameters;


  /// An optional [limit] setting maximum number of items returned.
  final int? limit;

Feature collection data returned from feature sources

Methods accessing multiple feature items return a future of `OGCFeatureItems“ which provides:

  /// The wrapped feature collection.
  final FeatureCollection<Feature> collection;


  /// Links related to this object.
  Links get links;


  /// An optional coordinate reference system from "Content-Crs" response
  /// header.
  final CoordRefSys? contentCrs;


  /// The time stamp
  DateTime? get timeStamp;


  /// An optional count of items matched.
  int? get numberMatched;


  /// An optional count of items returned.
  int? get numberReturned;

Feature objects are available from the collection property. See the geospatial features chapter in the geobase package for more information about Feature and FeatureCollection objects.

Information about queryable properties

The queryables metadata from a feature source is provide information about queryable properties that a service supports:

/// Represents `Queryables` document for an OGC API service parsed from JSON
/// Schema data.
class OGCQueryableObject {
  /// JSON Schema based data representing `Queryables` document for an OGC API
  /// service.
  ///
  /// This is data that is directly parsed from JSON Schema data an OGC API
  /// Service has published. Use this for more detailed inspection of
  /// Queryables metadata when other class members are not enough.
  final Map<String, dynamic> content;


  /// The URI of the resource without query parameters.
  final String id;


  /// The schema id of JSON Schema data in content.
  ///
  /// Should be either "https://json-schema.org/draft/2019-09/schema" or
  /// "https://json-schema.org/draft/2020-12/schema" according to the
  /// `OGC API - Features - Part 3: Filtering` standard.
  final String schemaId;


  /// The human readable title for this queryable object.
  final String title;


  /// An optional human readable description.
  final String? description;


  /// If true, any properties are valid in filter expressions even when not
  /// declared in a queryable schema.
  final bool additionalProperties;


  /// A map of queryable properties for this queryable object.
  ///
  /// The map key represents a property name (that is accessible also from
  /// the `name` property of `OGCQueryableProperty` object).
  ///
  /// NOTE: currently this contains only non-geospatial properties that SHOULD
  /// have at least "type" and "title" attributes.
  final Map<String, OGCQueryableProperty> properties;
}


/// A queryable non-geospatial property.
class OGCQueryableProperty {
  /// The property name.
  final String name;


  /// The human readable title for this property.
  final String title;


  /// An optional human readable description.
  final String? description;


  /// The type for this property.
  ///
  /// According to the `OGC API - Features - Part 3: Filtering` standard a type
  /// SHOULD be one of the following:
  /// * `string` (string or temporal properties)
  /// * `number` / `integer` (numeric properties)
  /// * `boolean` (boolean properties)
  /// * `array` (array properties)
  ///
  /// In practise different OGC API Features implementations seem also to use
  /// different specifiers for types.
  final String type;
}