API Overview

The GeoServer REST API provides programmatic access to geospatial data management, map rendering, and spatial analysis capabilities. All requests are made over HTTPS and return data in JSON format unless specified otherwise.

All endpoints require authentication via API Key or OAuth2 Bearer token. See the Authentication section for setup instructions.

Authentication

Access the API by including your API key in the Authorization header. Keys can be generated from the Developer Console.

Header Format

curl -X GET https://api.geoserver.io/v1/layers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch('https://api.geoserver.io/v1/layers', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
  }
});

Rate Limiting

API requests are limited to ensure fair usage and system stability. Limits vary by subscription tier:

When rate limited, the API returns a 429 Too Many Requests status with X-RateLimit-Reset header indicating when the window resets.

Layers

Manage geospatial vector and raster layers. Layers define the data sources, styling rules, and rendering parameters for your maps.

Retrieve a paginated list of all available layers in your account.

Query Parameters

Create a new geospatial layer from GeoJSON, Shapefile, or WMS source.

Request Body

{
  "name": "urban_green_space",
  "workspace": "environment",
  "type": "vector",
  "source": {
    "type": "geojson_url",
    "url": "https://data.example.org/parks.geojson"
  },
  "style": {
    "color": "#4CAF50",
    "stroke": "#2E7D32",
    "min_zoom": 10
  }
}

Response (201 Created)

{
  "id": "lyr_8f3k29x1",
  "name": "urban_green_space",
  "status": "processing",
  "created_at": "2025-04-12T08:30:00Z",
  "bounds": { "min_lon": -122.5, "min_lat": 37.7, "max_lon": -122.3, "max_lat": 37.9 }
}

Maps & Workspaces

Fetch map configuration, layer order, and projection settings.

Create a new map composition by combining multiple layers with custom styling and extent.

Tile Generation

Request pre-rendered map tiles in XYZ tiling scheme. Supports PNG, JPEG, and WebP formats. Tiles are cached at edge locations for low-latency delivery.

Spatial Analysis

Perform geometric operations and spatial queries. Accepts GeoJSON FeatureCollections and returns transformed geometries.

Request Body

{
  "input": {
    "type": "Feature",
    "geometry": { "type": "Point", "coordinates": [-122.4194, 37.7749] },
    "properties": {}
  },
  "operation": "buffer",
  "parameters": { "radius_meters": 500, "segments": 32 }
}

Error Handling

The API uses standard HTTP status codes. Error responses include a JSON body with machine-readable codes and human-readable messages.

Error Response Format

{
  "error": {
    "code": "INVALID_GEOJSON",
    "message": "FeatureCollection must contain valid coordinates array.",
    "details": {
      "field": "geometry.coordinates",
      "expected": "Array of numbers",
      "received": "null"
    }
  }
}

Client SDKs

Official libraries are available for popular languages to simplify authentication, request signing, and response parsing.