Meratyn

Manual/Reference

Hosted layers API

The hosted-layer API is a Meratyn-owned façade. Responses use stable Meratyn IDs and normalized models; GeoNode and GeoServer identifiers are never part of the public contract.

Resources

GET, POST        /api/layers
GET, POST        /api/layers/collections
GET, PUT, DELETE /api/layers/collections/:collectionId
POST             /api/layers/collections/:collectionId/layers
DELETE           /api/layers/collections/:collectionId/layers/:layerId
GET              /api/layers/provider
POST             /api/layers/provider/sync
POST             /api/layers/schema
GET, POST        /api/layers/remote-catalogues
DELETE           /api/layers/remote-catalogues/:catalogueId
POST             /api/layers/remote-catalogues/:catalogueId/:check|refresh|harvest
GET              /api/layers/remote-catalogues/:catalogueId/resources
GET, POST        /api/layers/principals
GET              /api/layers/principals/:principalId/members
PUT, DELETE      /api/layers/principals/:principalId/members/:userId
GET              /api/layers/metadata/schema
GET, PUT, DELETE /api/layers/:id
GET              /api/layers/:id/services
GET, POST        /api/layers/:id/gateway/:serviceId
GET              /api/layers/:id/representations
GET              /api/layers/:id/downloads
GET, HEAD        /api/layers/:id/downloads/:downloadId
GET              /api/layers/:id/usage
GET              /api/layers/:id/audit
GET              /api/layers/:id/lineage
POST             /api/layers/:id/access
GET, HEAD        /api/layers/:id/assets/:assetId/:filename
GET, PUT         /api/layers/:id/metadata
GET, PUT         /api/layers/:id/permissions
GET, PUT         /api/layers/:id/attributes
GET, POST        /api/layers/:id/styles
PUT, DELETE      /api/layers/:id/styles/:styleId
GET, PUT         /api/layers/:id/geolimits
GET, POST        /api/layers/:id/comments
DELETE           /api/layers/:id/comments/:commentId
GET, PUT, DELETE /api/layers/:id/rating
GET, PUT, DELETE /api/layers/:id/favorite
GET              /api/layers/:id/versions
POST             /api/layers/:id/replace
POST             /api/layers/:id/versions/:versionId/restore
GET, POST        /api/layers/:id/features
PATCH, DELETE    /api/layers/:id/features/:featureId
GET, POST        /api/layers/:id/related
DELETE           /api/layers/:id/related/:relatedId
GET, POST        /api/layers/:id/reconcile
GET, PUT         /api/layers/:id/workflow
GET, POST        /api/layers/:id/supplementary-assets
DELETE           /api/layers/:id/supplementary-assets/:assetId
GET, HEAD        /api/layers/:id/supplementary-assets/:assetId/download
GET              /api/layers/:id/metadata-links
POST             /api/layers/:id/metadata-file
GET              /api/layers/:id/dataset-schema
POST             /api/layers/:id/upsert
GET              /api/layers/:id/provider-jobs
POST             /api/layers/:id/recalculate-extent

POST /api/layers accepts multipart form data for local files and their sidecars. Endpoint or URL registration is not presented to users.

All mutations require authentication. Catalogue and item reads follow the layer’s discovery and grant policy. Service requests enforce View or Download as appropriate.

GET /api/layers accepts collection, owner, category, region, subtype, published, approved, featured, favorite, and geographic extent=minX,minY,maxX,maxY facets in addition to text, kind, status, and visibility. Public collection reads expose only public members. GET /api/layers/collections returns discoverable collections, while scope=mine returns collections the current user can manage. Both catalogue endpoints accept bounded limit and offset parameters and return pagination.nextOffset; clients should follow that continuation until it is null. A public collection accepts only public layers; private collections accept layers the owner can manage. Collection membership does not alter layer visibility or delete policy.

Organization and group records are Meratyn principals. Administrators create them and manage membership; layer managers grant principals independent view, download, edit, and manage permissions. Public visibility implies view and download for anonymous consumers. Unlisted layers are readable through their stable ID or a referencing project but are omitted from catalogue results.

POST /api/layers/:id/access exchanges an authenticated Meratyn token for a short-lived, layer-scoped access token. It returns { token, expiresAt, refreshAfter, services }. The returned direct-service URLs carry the ephemeral token; persisted projects must retain only the stable layer ID and service ID. Public direct assets need no session.

The asset gateway supports GET, HEAD, Range, If-Range, and ETag revalidation. Satisfiable ranges return 206; invalid ranges return 416. Private, organization, and group assets return 404 without owner, grant, or valid layer-session access.

Canonical map, feature, and raster-data services are always returned as Meratyn gateway URLs, including for public layers. The gateway resolves a stored resource and service ID server-side; callers cannot supply a provider host. It accepts only bounded, read-only, resource-scoped WMS/WFS/WCS operations and returns resource-scoped capability documents that advertise only the stable Meratyn layer ID. It rejects transactions, requests for another layer, unsupported parameters, oversized requests, and oversized responses.

WFS GetFeature and GetPropertyValue honor the standard srsName parameter and default to EPSG:4326 when it is omitted. WMS supports the standard GetFeatureInfo parameters, including INFO_FORMAT and FEATURE_COUNT, so a client can use its ordinary identify workflow. Map rendering requires View; feature, coverage, and provider file downloads require Download. Private descriptors returned by POST /access carry a short-lived layer token that the gateway validates on each request.

Provider download choices are advertised at /downloads and fetched by their advertised opaque ID at /downloads/:downloadId. Meratyn re-resolves that ID against the provider’s current advertised list, restricts the destination to configured trusted origins, and forwards only safe range and cache validators.

The social endpoints are Meratyn-owned so comments, a user’s rating, and favourites have one consistent contract even when the publication backend does not offer those writes. Aggregate ratings and comment visibility still follow the layer’s View policy. Feature routes accept GeoJSON features and translate create, update, and delete operations at the provider boundary; they require Edit permission.

Core model

A layer summary contains:

  • id, slug, title, description
  • kind: vector, raster, tiles, multidimensional, point-cloud, or 3d
  • format and detected media type
  • visibility: public, unlisted, or private
  • status: draft, uploading, processing, published, failed, or deleting
  • owner and optional organization
  • extent, CRS, size, timestamps, keywords, and thumbnail
  • provider capability summary

PUT /api/layers/:id accepts the editable overview fields, including crs. CRS values are normalized to an EPSG:<code> identifier or CRS:84 and are synchronized with the publishing provider’s declared SRS. This declares the source coordinate system; it does not transform stored coordinates.

Service descriptors contain a type, Meratyn-controlled URL, media type, optional MapLibre source hints, and access requirement. Clients should select in this order when applicable:

  1. native cloud format (PMTiles, COG, FlatGeobuf, GeoParquet, Zarr, COPC)
  2. vector/raster tiles
  3. WMS
  4. WFS for editable feature access, or WCS for raster data

Direct descriptors add:

  • representation: stable representation identifier
  • access.mode: public or session
  • direct, preferred, and rangeRequests
  • sizeBytes, mediaType, and format
  • optional sourceLayer and Zarr variable

The current direct single-object formats are PMTiles, named COG uploads (*.cog.tif, *.cog.tiff, or *.cog), FlatGeobuf, GeoParquet, Zarr objects, COPC/LAZ, 3D Tiles payloads, glTF, GLB, and Gaussian splats. Multi-object Zarr stores and 3D Tiles/glTF hierarchies can submit a relativePaths JSON array. Private project delivery signs the root URL with a project capability and preserves that capability for validated relative files requested by manifests. Traversal, absolute paths, duplicate paths, and undeclared sibling files are rejected.

Raw MBTiles uploads return 415; convert them to PMTiles before publication.

Clients should poll only while a layer is in uploading or processing, then stop after a terminal state. The bundled admin UI and Catalog use a three-second interval for this bounded live update.

Provider capabilities

The capability object describes what the Meratyn façade can do, not the feature list of a particular backend. Meratyn owns its stable catalogue, grants, retained replacement versions, comments, per-user ratings, favourites, related-layer records, audit history, and local presentation fallback. It uses provider operations for publication, rich metadata, map delivery, downloads, styles, attribute discovery, and feature transactions when available. The UI must never infer support from a provider name.

Metadata, access policy, table presentation, and style edits are retained by Meratyn before optional provider synchronization. A provider outage therefore does not discard an ordinary admin change. Reconciliation records pending or divergent synchronization internally and exposes only a sanitized, provider-neutral drift summary.

POST /api/layers/:id/reconcile?repair=true performs a real comparison and repairs provider metadata, permissions, ownership, workflow state, attributes, styles, CRS, and extent using the documented Meratyn ownership rules. A plain POST checks without repairing.

The provider catalogue is imported idempotently and synchronized every five minutes in the Node deployment (GEONODE_CATALOGUE_SYNC_INTERVAL_MS controls the interval). Administrators can also run synchronization explicitly. GeoNode user/group identities are shadow mappings with unusable passwords; Meratyn remains the login and membership authority.

Schema-first creation accepts a field schema, constraints, geometry type, CRS, and initial GeoJSON features. It validates required, unique, type, numeric range, and safe pattern constraints before publication. Bulk upsert reuses the stored schema for GeoJSON preflight, sends GeoNode’s native action=upsert contract, and exposes the asynchronous execution through provider-jobs. GeoNode validation reports remain supplementary resource assets.

GeoNode documents use its document resource manager. Supplementary assets, ISO XML metadata import, generated metadata links, publication approval, and WMS/GeoNode/ArcGIS harvesting are exposed through the same Meratyn façade. Remote harvesting configuration and moderation require a Meratyn administrator.

An unavailable provider operation returns a structured 501 response with a capability key and human-readable explanation. Authentication/authorization, validation, conflict, provider outage, and import failure remain distinct errors.

Upload safety

Deployments must enforce request size, archive expansion ratio, member count, path traversal, file signature and extension agreement, and per-account quota. Sources are staged under generated keys; user filenames are metadata, never filesystem paths. Production deployments should add malware scanning before an ingestion worker opens the file.

Multipart uploads are adequate for the local vertical slice. Production object storage should add resumable upload sessions and direct multipart transfer so large rasters do not pass through one Node process or remain in memory.

Usage and audit

Direct storage is reserved atomically against the existing per-user Meratyn quota before an object is written. Failed storage rolls the reservation back, deletion releases it, and the administrator storage recalculation includes hosted-layer assets.

GET /api/layers/:id/usage reports source, derived, version, and total bytes, the account quota, download count, and last access time. GET /api/layers/:id/audit records upload, publication, metadata, permission, attribute, style, access-session, download, update, and deletion events. Layer deletion retains the audit record with a cleared layer foreign key.