GeoServer API Reference

Authentication

All API requests require an API key passed via the Authorization header. Keep your keys secure and never expose them in client-side code.

# Example Authorization Header
Authorization: Bearer gsv_live_sk_a1b2c3d4e5f6...

Key Types

Live keys: Production traffic
Test keys: Sandbox environment
Read-only: Query & render only

Rate Limits

Standard: 1,000 requests / hour
Enterprise: 10,000+ requests / hour
Throttle header: X-RateLimit-Remaining

API Endpoints

Core resources for managing spatial data and map rendering.

GET /layers List all available layers

Returns a paginated list of vector and raster layers accessible to your account.

Parameter	Type	Description
`type` optional	string	Filter by `vector`, `raster`, or `mesh`
`limit` optional	integer	Items per page (default: 20, max: 100)
`cursor` optional	string	Pagination token from previous response

GET https://api.geoserver.io/v1/layers?type=vector&limit=10
Authorization: Bearer YOUR_API_KEY

{
  "data": [
    {
      "id": "lyr_8x9k2m",
      "name": "us_highways",
      "type": "vector",
      "crs": "EPSG:4326",
      "features": 124850,
      "updated_at": "2025-09-12T08:30:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6MTAwfQ==",
    "has_more": true
  }
}

POST /queries Execute spatial query

Run WKT-based spatial filters, attribute queries, or geometry operations against a target layer.

Parameter	Type	Description
`layer_id` required	string	Target layer identifier
`filter` required	object	Query object (wkt, attributes, bbox)
`format` optional	string	Output: `geojson`, `kml`, `csv` (default: geojson)

{
  "layer_id": "lyr_8x9k2m",
  "filter": {
    "wkt": "POLYGON((...))",
    "operator": "intersects",
    "attributes": { "speed_limit": { "$gt": 55 } }
  }
}

{
  "status": "success",
  "count": 42,
  "data": /* GeoJSON FeatureCollection */
}

POST /render Generate map image

Render dynamic map tiles or full-image exports with custom styling, projections, and overlays.

{
  "bbox": [-122.5, 37.7, -122.3, 37.8],
  "size": "800x600",
  "layers": ["lyr_8x9k2m", "lyr_ocean_2024"],
  "format": "png",
  "style": "dark_vector_v2"
}

// Returns binary image stream with headers:
Content-Type: image/png
X-Render-Time: 142ms
// ... [binary data]

Error Handling

GeoServer uses standard HTTP status codes. All errors return a consistent JSON structure.

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid WKT geometry provided in filter.",
    "details": [
      { "field": "filter.wkt", "reason": "unclosed coordinate sequence" }
    ],
    "request_id": "req_9f8a7b6c5d4e"
  }
}

Code	Status	Description
`400`	Bad Request	Invalid parameters, malformed JSON, or unsupported CRS
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Insufficient permissions for the requested layer
`404`	Not Found	Layer or resource does not exist
`429`	Too Many Requests	Rate limit exceeded. Retry after header indicates cooldown
`500`	Server Error	Internal processing failure. Contact support with request_id

SDKs & Tools

Official and community-maintained libraries to integrate GeoServer into your stack faster.

Python SDK

import geoserver_client

client = geoserver_client.Client("YOUR_API_KEY")
layers = client.layers.list(type="vector")
print(f"Found {len(layers)} layers")

→ Install with pip: pip install geoserver-client

JavaScript / Node.js

const GeoServer = require("@geoserver/sdk");
const gsv = new GeoServer(process.env.GSV_KEY);

const tiles = await gsv.render({
  bbox: [-180, -90, 180, 90]
});

→ Install with npm: npm i @geoserver/sdk