Docs / API Reference / Vector Layers

Vector Layer Management

Manage, query, and transform spatial vector data through our RESTful API. Supports GeoJSON, Shapefile, WKT, and PostGIS formats.

Base URL

All requests to the vector layer endpoint must use the base URL: https://api.geoserver.dev/v3/layers

Create a New Layer

Initialize a new vector layer by uploading a dataset or connecting to an external database. The API returns a unique layer ID and projection details.

POST /layers

curl -X POST https://api.geoserver.dev/v3/layers \n  -H "Authorization: Bearer YOUR_API_KEY" \n  -H "Content-Type: application/json" \n  -d '{
    "name": "urban_green_spaces",
    "source": "https://cdn.example.com/data/parks.geojson",
    "projection": "EPSG:4326",
    "metadata": {
      "owner": "city_planning_dept",
      "updated": "2025-01-15"
    }
  }'

Request Parameters

Parameter	Type	Required	Description
`name`	string	Required	Unique identifier for the layer. Must be lowercase alphanumeric with underscores.
`source`	string	Required	URL to GeoJSON, WFS endpoint, or S3 bucket path.
`projection`	string	Optional	EPSG code for coordinate reference system. Defaults to `EPSG:3857`.
`metadata`	object	Optional	Key-value pairs for custom tagging and organizational tracking.

Query Layer Features

Execute spatial and attribute queries against an existing layer. Supports bounding box filters, radius searches, and attribute conditionals.

GET /layers/{id}/features

GET /v3/layers/urban_green_spaces/features \n  ?bbox=-74.05,40.68,-73.93,40.82 \n  &filter=area_gt:5000 \n  &limit=50 \n  &output=json

Response Schema

Returns a standard GeoJSON FeatureCollection. The response includes spatial indexes, attribute metadata, and pagination tokens.

JSON Response (200 OK)

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "park_001",
      "geometry": { "type": "Polygon", "coordinates": [...] },
      "properties": {
        "name": "Central Park",
        "area_sqm": 3400000,
        "established": 1857
      }
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6MTAwLCJ0cyI6IjIwMjUtMDEtMTUifQ",
    "has_more": true
  }
}

Spatial Transformations

Apply on-the-fly coordinate transformations, clipping, or simplification. Useful for map rendering optimization and cross-protocol compatibility.

Note on Projections

All transformation operations preserve topological integrity. Use preserve_topology=true for cadastre or legal boundary datasets.

POST /layers/{id}/transform

{
  "operation": "reproject",
  "target_crs": "EPSG:32618",
  "simplify_tolerance": 0.5,
  "preserve_topology": true
}

Pagination & Cursor Handling

Large datasets are served via cursor-based pagination. Always use the next_cursor token to fetch subsequent pages. Offset-based pagination is deprecated in v3.4+.

JavaScript Example

async function fetchAllFeatures(layerId) {
  let cursor = null;
  const allFeatures = [];

  do {
    const url = `https://api.geoserver.dev/v3/layers/${layerId}/features`;
    const response = await fetch(url, {
      headers: { "Authorization": `Bearer ${API_KEY}` }
    });
    const data = await response.json();

    allFeatures.push(...data.features);
    cursor = data.pagination.next_cursor;
  } while (cursor);

  return allFeatures;
}