API Reference

The GeoServer REST API allows you to programmatically manage geospatial data, render maps, query features, and integrate spatial analytics into your applications. All endpoints use HTTPS and return JSON responses.

Base URL: https://api.geoserver.io/v2
All requests should be made against this base path. Versioning follows semantic versioning. Breaks will trigger major version increments.

Authentication

Authenticating requests is done via Bearer tokens in the Authorization header. Generate your API key from the dashboard under Settings > API Keys.

HTTP Header

Authorization: Bearer gsv_live_4eC39HqLyjWDarjtT1zdp7dc

Expired or invalid tokens will return a 401 Unauthorized response. Tokens are scoped by environment (sandbox/production) and cannot be cross-used.

Layers

Manage vector and raster layers. Supports GeoJSON, Shapefile, PostGIS, and WMS sources.

GET /layers

List all available layers in your workspace. Supports filtering by type, projection, and bounding box.

Query Parameters

Name	Type	Required	Description
type	string	No	Filter by `vector` or `raster`
bbox	string	No	Format: `minLon,minLat,maxLon,maxLat`
limit	integer	No	Max results (default: 50, max: 200)

Example Response

JSON 200 OK

{
  "data": [
    {
      "id": "lyr_8f3k29s1d",
      "name": "global_terrain_v3",
      "type": "raster",
      "crs": "EPSG:4326",
      "source": "s3://geo-data/terrain/",
      "created_at": "2024-11-15T08:23:00Z"
    }
  ],
  "pagination": { "next": "/layers?offset=50" }
}

POST /layers

Create a new geospatial layer. Uploads are handled asynchronously for large datasets.

Request Body

Name	Type	Required	Description
name	string	Yes	Unique identifier for the layer
type	string	Yes	`vector`, `raster`, or `wms_proxy`
source_url	string	Yes	S3, PostGIS connection string, or HTTP URL
crs	string	No	EPSG code (default: EPSG:4326)

Maps

Composite multiple layers into renderable map resources. Supports dynamic styling and caching.

POST /maps

Create a map definition. Returns a map ID used for tile generation and WMS requests.

JSON Request

{
  "name": "urban_planning_v2",
  "layers": ["lyr_8f3k29s1d", "lyr_m9x2k11qp"],
  "style": {
    "base": "light-gray",
    "opacity": 0.85
  }
}

Features

Query and manipulate individual geographic features. Supports spatial predicates (intersects, within, touches).

GET /layers/{layer_id}/features

Retrieve features matching spatial or attribute filters. Returns GeoJSON FeatureCollection.

Name	Type	Required	Description
filter	string	No	WKT geometry or CQL expression
properties	array	No	Comma-separated list of attributes to return
format	string	No	`geojson` or `json`

Error Codes

GeoServer uses standard HTTP status codes. All error responses follow a consistent JSON structure.

Code	Name	Description
400	Bad Request	Malformed JSON, missing required parameters, or invalid spatial bounds.
401	Unauthorized	Missing or invalid API key. Check your token scope.
403	Forbidden	Token lacks permission for the requested resource or workspace.
404	Not Found	Resource does not exist or has been archived.
429	Too Many Requests	Rate limit exceeded. Retry after the `X-RateLimit-Reset` timestamp.
500	Server Error	Internal processing failure. Contact support with the `X-Request-Id`.

JSON Error Format

{
  "error": {
    "code": 400,
    "message": "Invalid WKT geometry string",
    "request_id": "req_8f3k29s1d"
  }
}