Layers & Spatial Exports

Terragnos Core provides powerful spatial export capabilities including GeoJSON feeds, vector tiles (MVT), and OGC API Features endpoints. This guide covers creating layer definitions, exporting spatial data, and integrating with GIS tools.

What are Layers?

Layers are reusable spatial export configurations that define:

• Filters – Which objects to include (by type, attributes, spatial bounds)
• Fields – Which attributes to include in the export
• Caching – TTL for cached responses
• Format – GeoJSON, MVT, or OGC API Features

Creating Layer Definitions

Via API

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Traffic Signals",
    "slug": "traffic-signals",
    "definition": {
      "filters": {
        "typeId": "traffic-signal"
      },
      "fields": ["id", "typeId", "attributes", "geometry"]
    },
    "cacheTtlSeconds": 3600
  }' \
  https://core.example.com/v1/layers/definitions

Via Admin Console

1. Navigate to Layers in the Admin Console
2. Click Create New Layer
3. Configure filters, fields, and caching
4. Save the layer definition

GeoJSON Export

Basic Export

GET /v1/layers/objects

Returns a GeoJSON FeatureCollection:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "object-id",
      "geometry": {
        "type": "Point",
        "coordinates": [12.34, 56.78]
      },
      "properties": {
        "typeId": "traffic-signal",
        "attributes": {
          "signalType": "standard"
        }
      }
    }
  ]
}

Using Layer Definitions

GET /v1/layers/objects?layer=traffic-signals

Filtering

# By type
GET /v1/layers/objects?typeId=traffic-signal

# By bounding box
GET /v1/layers/objects?bbox=12.0,56.0,13.0,57.0

# Combined
GET /v1/layers/objects?layer=traffic-signals&bbox=12.0,56.0,13.0,57.0

Field Selection

# Select specific fields
GET /v1/layers/objects?fields=id,typeId,attributes.signalType

Available fields:

• id – Object ID
• typeId – Object type ID
• publicId – Public identifier
• attributes – All attributes (or specific paths)
• geometry – Spatial geometry
• workflowState – Current workflow state
• createdAt – Creation timestamp
• updatedAt – Last update timestamp

Streaming Export (NDJSON)

For large datasets, use the streaming endpoint:

GET /v1/layers/objects/stream?layer=traffic-signals

Returns newline-delimited JSON (NDJSON), one feature per line:

{"type":"Feature","id":"obj-1","geometry":{...},"properties":{...}}
{"type":"Feature","id":"obj-2","geometry":{...},"properties":{...}}

This is more memory-efficient for large exports.

Vector Tiles (MVT)

Terragnos Core supports Mapbox Vector Tiles (MVT) for efficient map rendering:

GET /v1/layers/tiles/{layer}/{z}/{x}/{y}

Parameters:

• layer – Layer slug
• z – Zoom level (0-18)
• x – Tile X coordinate
• y – Tile Y coordinate

Example:

GET /v1/layers/tiles/traffic-signals/12/2048/1365

Using with Map Libraries

Leaflet:

L.vectorGrid.protobuf('https://core.example.com/v1/layers/tiles/traffic-signals/{z}/{x}/{y}', {
  vectorTileLayerStyles: {
    'traffic-signals': {
      fillColor: '#ff0000',
      fillOpacity: 0.6,
      stroke: true,
      color: '#000000',
      weight: 1
    }
  }
}).addTo(map);

Mapbox GL:

map.addSource('traffic-signals', {
  type: 'vector',
  tiles: ['https://core.example.com/v1/layers/tiles/traffic-signals/{z}/{x}/{y}']
});

map.addLayer({
  id: 'traffic-signals',
  type: 'circle',
  source: 'traffic-signals',
  paint: {
    'circle-color': '#ff0000',
    'circle-radius': 5
  }
});

OGC API Features

Terragnos Core provides an OGC API Features compliant endpoint:

GET /v1/layers/ogc/features?layer=traffic-signals

Response format:

{
  "type": "FeatureCollection",
  "features": [...],
  "links": [
    {
      "rel": "next",
      "href": "/v1/layers/ogc/features?layer=traffic-signals&offset=100"
    }
  ]
}

Caching

Layer responses are cached for performance:

• Cache TTL – Configurable per layer (default: 3600 seconds)
• ETag support – Conditional requests return 304 Not Modified
• Cache-Control headers – Standard HTTP caching headers

Cache Invalidation

Caches are automatically invalidated when:

• Objects in the layer are updated
• Layer definition is modified
• Cache TTL expires

Time-Travel Queries

All layer endpoints support time-travel queries:

GET /v1/layers/objects?layer=traffic-signals&asOf=2024-01-15T10:30:00Z

Returns the layer state at the specified point in time.

Best Practices

1. Use layer definitions – Create reusable layer definitions instead of inline filters
2. Optimize fields – Only request fields you need
3. Use bounding boxes – Limit spatial queries with bbox parameters
4. Leverage caching – Set appropriate cache TTLs for your use case
5. Use streaming for large exports – Use /stream endpoint for large datasets
6. Use vector tiles for maps – MVT is more efficient than GeoJSON for map rendering
7. Monitor cache hit rates – Track cache performance