SuperMap iServer REST API
Feb 25,2026

GISBox is a one-stop 3D GIS data editing, conversion and publishing platform that supports editing in multiple GIS formats such as OSGB/GEOTIFF/RVT, converting to 3DTiles/Terrain and publishing.

Introduction

SuperMap iServer REST API is a comprehensive, resource-oriented application programming interface that exposes the full spectrum of GIS functionalities through standard HTTP protocols. Built upon the Representational State Transfer (REST) architectural style, this API encapsulates core GIS capabilities—including map services, data management, spatial analysis, 3D visualization, and distributed processing—as addressable resources uniquely identified by URIs. By adhering strictly to REST principles, SuperMap iServer transforms complex GIS operations into simple, lightweight HTTP interactions that support multiple representation formats (JSON, XML, HTML, binary images) and standard HTTP methods (GET, POST, PUT, DELETE). This design enables developers, system integrators, and GIS professionals to build web and mobile applications that seamlessly integrate with enterprise geospatial infrastructure, whether for dynamic map visualization, real-time spatial querying, or large-scale distributed spatial analytics.

File Structure

SuperMap iServer REST API follows a hierarchical resource organization that mirrors the functional modules of the server platform.

Resource Hierarchy: The API organizes resources into logical service groups, each with a distinct root URI pattern such as /iserver/services/{serviceName}/rest/maps for map services, /data for data resources, /spatialanalyst for spatial analysis, and /realspace for 3D capabilities. This hierarchical structure allows for intuitive navigation from service collections down to individual map layers, features, or analysis tasks .
Service Components Configuration: REST resources are defined through XML configuration files that map URI templates to resource implementation classes. Module configuration files (e.g., mapRest, dataRest, spatialanalystRest) specify encoders, decoders, and security verifiers, while resource configuration files (e.g., mappingResources.xml, dataResources.xml) define resource IDs, URL templates, and implementing classes for both Restlet-based and JAX-RS-based resources .
Domain Component Publishing: The API supports automatic publication of custom Java domain components as REST resources. Public methods in component classes are exposed as resources—simple methods with primitive parameters become {methodName}Result resources with URI parameter passing, while complex methods become {methodName}Results resources requiring POST requests and subsequent result retrieval .
Endpoint Structure: Core endpoints include workspaces resources for rapid service publishing (supporting POST requests to create REST map, data, and OGC services simultaneously), maps resources for accessing map collections and individual map representations, and processingJobs resources for distributed spatial analysis task management .

Pros

True RESTful Conformance and Resource Orientation: Strictly adheres to ROA (Resource-Oriented Architecture) design principles, treating all GIS functions as resources with uniform HTTP method semantics—GET for retrieval, POST for creation, PUT for update, DELETE for removal—providing an intuitive and consistent programming model .
Comprehensive GIS Functionality Exposure: Encapsulates the entire spectrum of server-side GIS capabilities—map rendering, feature editing, spatial queries, buffer analysis, overlay operations, network analysis, terrain modeling, and 3D scene operations—through a single, unified API surface .
Multiple Representation Formats with Rich Semantics: Supports diverse output formats including JSON, RJSON (REST JSON), XML, HTML, PNG, and JavaScript, allowing clients to request exactly the representation that best suits their application context. The API also provides abundant HTTP status codes for precise error diagnosis and operation result inspection .
Flexible Extensibility and Customization: Offers the SuperMap iServer REST SDK, enabling developers to extend core resources, implement custom security controllers, add specialized representation encoders, and publish domain-specific components as first-class REST resources without modifying the underlying platform .
Distributed Processing Support: Provides dedicated REST endpoints for creating and managing distributed spatial analysis jobs, supporting large-scale operations like density analysis, point aggregation, and overlay analysis with configurable input/output across multiple data formats (CSV, UDB, spatial databases, HDFS) .

Cons

Complex Learning Curve for Comprehensive Usage: The extensive scope of the API—spanning dozens of service types and hundreds of resources—creates a steep learning curve for developers, requiring substantial investment to master the full capabilities and proper resource interaction patterns .
Platform Dependency and Vendor Lock-in: As a proprietary API tied specifically to the SuperMap iServer ecosystem, applications built directly against this API face significant migration challenges when considering alternative geospatial server platforms .
Historical Limitations in REST Support: Earlier versions of SuperMap iServer lacked comprehensive REST API capabilities, with some comparative analyses noting the absence of RESTful service exposure and modern web development patterns that competitors had already implemented .
Authentication and Security Complexity: While supporting token-based access for protected resources, the security configuration—particularly for distributed analysis jobs and multi-role access scenarios—requires careful planning and understanding of the underlying authentication mechanisms .
Version Compatibility Challenges: The API structure and available resources may evolve significantly across major SuperMap iServer releases, requiring application maintenance and potential refactoring when upgrading server versions.

Application Scenario

SuperMap iServer REST API serves as the foundational integration layer for building enterprise-grade geospatial applications that require seamless access to server-side GIS capabilities. In web GIS portals and dashboards, the API enables dynamic map visualization, layer querying, and feature editing by consuming map and data resources through lightweight JavaScript clients. For spatial data infrastructure (SDI) initiatives, it provides standardized access to centralized geospatial data stores, allowing disparate systems to discover, query, and analyze shared datasets. In urban planning and emergency response scenarios, the distributed processing endpoints support on-demand spatial analysis—such as buffer zone calculation, overlay analysis, and density mapping—by creating asynchronous processing jobs that leverage server-side computational resources. Mobile field applications utilize the API to synchronize data edits, perform spatial queries against central databases, and retrieve optimized map tiles for offline use. Additionally, system integrators leverage the REST SDK to extend the platform with custom domain-specific resources, embedding specialized GIS logic directly into the service layer for reuse across multiple client applications. The API's strength lies in transforming SuperMap iServer from a monolithic server product into a programmable, service-oriented platform that can be orchestrated within broader enterprise IT architectures and cloud-native deployments.