Koop Documentation

Koop is a JavaScript toolkit and Node.js web server designed to translate, query, and integrate geospatial APIs. It allows you to keep data in its native format while making it accessible in various formats via HTTP.

Koop uses a plugin architecture to facilitate custom deployments:

• Provider plugins: Connect to novel data formats and translate them into a common format (GeoJSON).
• Output plugins: Transform that common GeoJSON into other specifications, such as the GeoServices specification (supported by ArcGIS products), vector-tile, WMS, or plain GeoJSON.

The classification option allows for statistical grouping of data. It supports two types:

Class Breaks

Classifies numeric data based on breaks and a statistical method. Required fields: type: 'classes', field, method (equalInterval | naturalBreaks | quantile | std), and breakCount.

Example Input:

{
  type: 'classes',
  field: 'field1',
  method: 'equalInterval',
  breakCount: 5,
}

Unique Value

Classifies data based on unique field combinations. Required fields: type: 'unique' and fields (up to three fields).

Example Input:

{
  type: 'unique',
  fields: ['employeeID', 'customerID']
}

The Koop Geoservices Output plugin supports authentication and authorization workflows by interacting with your Koop Model.

Key integration points:

• authenticationSpecification(): If this function exists on your model, the plugin calls it during the rest/info handler to pass data to FeatureServer.
• authenticate: The plugin provides a rest/generateToken route which calls this function on your model to handle authentication.
• authorize: In version 2.0.0 and later, the plugin passes the Express request object as an argument to this.model.authorize and this.model.authenticate calls.

Starting from version 2.22.0, you can override specific layer properties by including them in the provider's metadata object. This is useful for fine-tuning how layers appear in GIS clients.

Properties you can override in the metadata object:

• id
• defaultVisibility
• minScale
• maxScale

The Koop project is managed as a monorepo. The core package, koop-core, is used to generate a default configuration of Koop. The following packages are included in the monorepo as default dependencies of koop-core:

• @koopjs/koop-core: The parent package and core engine.
• @koopjs/output-geoservices: The GeoServices output plugin.
• @koopjs/cache-memory: The default in-memory data cache.
• @koopjs/logger: The default logger.
• @koopjs/featureserver: Part of the GeoServices implementation.
• @koopjs/winnow: A dependency used within the core ecosystem.

Note that other plugins (additional providers or outputs) are maintained in separate repositories.

Koop operates on a two-step transformation pipeline:

1. Data Ingestion (Providers): A provider plugin connects to a specific data source (e.g., a database, a file, or an external API) and translates that data into a standardized GeoJSON format.
2. Data Delivery (Outputs): An output plugin takes that standardized GeoJSON and transforms it into the desired client-side specification (e.g., ArcGIS GeoServices, WMS, or Vector Tiles).

This decoupling allows you to mix and match any provider with any output plugin to create custom geospatial services.

Winnow allows you to define the coordinate systems for both input and output data.

• inputCrs: Defines the coordinate system of the incoming geospatial data. This can be passed as an option or defined directly on the GeoJSON collection via the crs path.
• outputCrs (alias for projection): Defines the target coordinate system for the output.
• sourceSR: Identifies the CRS of the source data (defaults to 'EPSG:4326'). If defined alongside a geometry filter, the filter is reprojected to the source CRS.

Winnow supports WKT (Well-Known Text) lookups for spatial reference IDs passed to these options, as well as inputSR and geometry-filter parameters like wkid or latestWkid (added in v2.2.0).

Since version 1.0.0, Koop is no longer a standalone server (koop-server is deprecated). Instead, Koop is a Node module that exposes an Express middleware app. To use Koop, you must integrate it into an existing application that boots up an HTTP server (such as Express) and use its hooks to register Koop providers.

This architecture allows for a cleaner structure and easier deployment to platforms like Heroku and AWS.

// Conceptual usage pattern for Koop 1.0.0+
const express = require('express');
const koop = require('koop');

const app = express();

// Koop is used as middleware
app.use(koop());

// Register providers using Koop hooks
// ...

app.listen(3000);

When the toEsri option is set to true, Winnow transforms the output into an Esri-compatible feature collection. This triggers several behaviors:

• Translates ISO Date Strings to Unix Timestamps.
• Adds OBJECTID fields if no ID field is set.
• Ensures OBJECTID is omitted from results if specifically excluded (e.g., via returnIdsOnly=true).
• Handles null geometries gracefully during the to-Esri geometry transform.