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:

The OGC API Features 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);
}

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,
  });

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;

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.

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;
}