Open Geospatial Consortium

Open Geospatial Consortium

Date:05/23/11

External identifier of this OGC® document: <http://www.opengis.net/doc/geoservices/1.0

Internal reference number of this OGC® document:11-049

Version: 1.0

Category: OGC® Candidate Implementation Standard

Editor:Satish Sankaran

OGC GeoServices REST Candidate Standard Version 1.0

Copyright notice

See copyright statement next page

Warning

This document is not an OGC Standard. It is distributed for review and comment. It is subject to change without notice and may not be referred to as an OGC Standard.

Document type: OGC® Draft Standard

Document subtype: Encoding

Document stage: Draft

Document language: English

Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

Draft copyright:

The organizations listed above have granted the Open Geospatial Consortium, Inc. (OGC) a nonexclusive, royalty-free, paid up, worldwide license to copy and distribute this document and to modify this document and distribute copies of the modified version.

Table of contents

1. Scope 6

2. Conformance 6

3. References 6

4. Terms and Definitions 7

5. Conventions 7

6. Overview of the Geoservices REST API 7

6.1 Resources and Operations 7

6.2 The Role of Services 8

6.3 Response Format 8

7. Catalogue 8

8. Map Service 9

9. Geocoding Service 55

10. GP Geoservice 60

11. Geometry 82

12. Image Service 136

13. Feature Service 167

14. Geometry Objects 211

15. Feature Object 214

16. Symbol Objects 215

17. Domain Objects 219

18. Label Objects 221

19. Renderer Objects 224

20. Spatial References 227

A.1 Conformance class: AAAA (repeat as necessary) 229

<Example – remove from document> 229

Preamble

Esri is offering this GeoServices REST API for consideration to become an OGC standard via the OGC Fast Track method.

This OGC GeoServices REST Candidate Standard Version 1.0 standard is derived from the “Esri GeoServices REST Specification Version 1.0” which was developed to provide interoperability between ArcGIS Server and the broader information technology community. The Esri specification has been widely implemented by Esri users and business partners over the last 4 years. In 2010 it was released as a non-proprietary open specification and has been implemented by developers outside of the Esri user community.

It is designed to be implemented without the use of Esri products.

This OGC version differs from the Esri version in that it is presented in a vendor neutral fashion appropriate for an OGC standard. For example the names of the types have been changed. The specification currently provides a JSON encoding, but does not limit alternate JSON representations (such as GeoJSON )

This candidate standard provides an established REST pattern that is web friendly in the geo and non geo web space, popular with Esri and non-Esri applications Although it is implemented by all ArcGIS Servers it does not tie back to anything Esri specific and can be used by anyone unrelated to Esri products.

i. Abstract

The GeoServices REST Specification provides a way for Web clients to communicate with geographic information system (GIS) servers through Representational State Transfer (REST) technology.

ii. Keywords

The following are keywords to be used by search engines and document catalogues

ogcdoc rest api services

iii. Preface

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation when possible.

iv. Submitting organizations

The following organizations submitted this Document to the Open Geospatial Consortium.

ESRI, ITTVIS, PCI, SAFE, 52 North

v. Submitters

All questions regarding this submission should be directed to the editor or the submitters:

Name / Company
Dave Danko / ESRI
Satish Sankaran / ESRI
Steven Keens / PCI
Don Murry / SAFE Software
Andreas Wytzisk / 52-North
Richard Cooke / ITTVIS

1. Scope

The GeoServices REST Specification provides a standard way for Web clients to communicate with geographic information system (GIS) servers through Representational State Transfer (REST) technology. Clients issue requests to the server through structured URLs. The server responds with map images, text-based geographic information, or other resources that satisfy the request.

2. Conformance

This Standard defines XXXX.

Requirements for N standardization target types are considered:

· AAAA

· BBBB

Conformance with this standard shall be checked using all the relevant tests specified in Annex A (normative) of this document. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site[1].

In order to conform to this OGC™ interface standard, a software implementation shall choose to implement:

a) Any one of the conformance levels specified in Annex A (normative).

b) Any one of the Distributed Computing Platform profiles specified in Annexes TBD through TBD (normative).

All requirements-classes and conformance-classes described in this document are owned by the standard identified as Error! Unknown document property name. .

3. References

The following normative documents contain provisions that, through reference in this text, constitute provisions of this document. For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. For undated references, the latest edition of the normative document referred to applies.

4. Terms and Definitions

This document uses the terms defined in Sub-clause 5.3 of [OGC 06-121r8], which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this standard.

For the purposes of this document, the following additional terms and definitions apply. <Additional terms and definitions to be provided>

4.1

term name

text of the definition

4.2

5. Conventions

This sections provides details and examples for any conventions used in the document. Examples of conventions are symbols, abbreviations, use of XML schema, or special notes regarding how to read the document.

6. Overview of the Geoservices REST API

All resources and operations exposed by the GeoServices REST API are accessible through a hierarchy of endpoints or uniform resource locators (URLs) for each available GIS service. When using the GeoServices REST API, users typically start from a well-known endpoint, which represents the server catalog. From the catalog, different types of resources are available as child nodes. These resources comprise services for mapping, geocoding, and so on.

The GeoServices REST API is stateless because REST does not keep track of transactions from one request to the next. Each request must contain all the information necessary for successful processing.

6.1 Resources and Operations

The GeoServices REST API works with a hierarchy of resources. Each service type recognized by the GeoServices REST Specification (map, geocode, and so on) is a resource and has a unique URL. Although a REST system always returns only representations of resources to client, for the sake of simplicity, the resources of the GeoServices REST Standard are divided into two types: resources and operations.

6.2 The Role of Services

The GeoServices REST Specification describes a catalog of Web services that are designed for different GIS functions (map, geocode, and so on). Esri® ArcGIS Server can be considered a reference implementation of this standard, meaning that it implements all the service types in the catalog. The GeoServices REST API Standard can be implemented with non-Esri GIS servers, but the back-end Web services must respond to the URL formats described in this document.

6.3 Response Format

Many resources in the GeoServices REST API have a parameter, “f”, that denotes the response format. Developers can program resources to respond to REST requests with various data formats, including JSON, HTML, and KMZ.

At the least, the JSON response format should be implemented, and examples for doing so are provided in this document. Other formats are optional, and they can be exposed through the f parameter; however, formats other than JSON are not detailed in this document.

7. Catalogue

The catalog resource is the root node and initial entry point into a server. This resource represents a catalog of folders and services published on the host.

The response optionally includes the specVersion and currentVersion properties. The specVersion is the version of the GeoServices REST API through which the catalog is implemented. If specVersion is not included in the response, its value is assumed to be 1.0.

The currentVersion property can be used to specify a version of the implementer's software.

7.1 Catalog Reference / ■ URL: http://<host>/.../<optional root folder >. Services may optionally be organized into folders, yielding a URL such as http://<host>/…/<optional root folder>/<folderName>.

■ Child Resources: Map Service, Geocode Service, GP Service, Geometry Service, Image Service, Feature Service.

7.2 Catalog Parameters
Parameter / Details
f / Description: The response format
Values: json | (other formats)
7.3 Catalog Example / Example

URL for the root directory of a GIS server:

http://myserver/rest/services

JSON Response Syntax

{

"specVersion": <versionOfGeoServicesRestSpecification>,

"currentVersion": <versionOfImplementerSoftware>,

"folders":["<folderName1>", "<folderName2>"],

"services":[

{"name" : "<serviceName1>", "type" : "<serviceType1>"},

{"name" : "<serviceName2>", "type" : "<serviceType2>"}

]

}

JSON Response Example

{

"specVersion": 1.0,

"currentVersion": 10,

"folders":["Editing", "USA"],

"services":[

{"name" : "Anaheim", "type" : "MapServer"},

{"name" : "Switzerland", "type" : "MapServer"},

{"name" : "USALocator", "type" : "GeocodeServer"}

]

}

8. Map Service

Map services offer access to map and layer content. A map service can either fulfill requests with precreated tiles from a cache or by dynamically rendering the map each time a request comes in. Map services using a tile cache can significantly improve performance when returning maps, while dynamic map services offer more flexibility.

Map services can also expose tabular data, whether this is associated with geographic features or not. The REST response from a map service includes a tables property that contains some basic information about tables. The child layer resource is a Layer/Table resource in that it represents either a layer or a table depending on the ID that was specified.

If the map supports querying and exporting maps based on time, the REST response includes a timeInfo property, which includes information about the map's time extent and the map's native time reference.

The GeoServices REST Specification Map Service resource provides basic information about the map, including the layers that it contains; whether the map has a tile cache; and the map's spatial reference, initial and full extents, map units, and copyright text. It also provides some metadata associated with the service such as its service description, its author, and keywords. If the map is cached, additional information about its tiling scheme, such as the origin of the cached tiles, the levels of detail, and tile size, is included.

The Map Service resource supports several operations:

· Export Map: Used to export a dynamically drawn map image.

· Identify: Returns information about features in one or more layers at a given location. This location commonly originates from a click of the mouse.

· Find: Returns information about features in one or more fields in one or more layers based on a keyword.

In addition to the above operations, a Query operation is available on a layer/table. It returns a subset of features in a layer or records in a table based on query criteria.

Map services do not expose editing capabilities. They provide read-only access to feature and attribute content. Feature services expose editing capabilities.

8.0.1 Map Service Reference / ■ URL: http://<catalog-url>/<serviceName>/MapServer
■ Supported Operations: Export Map, Identify, Find
■ Parent Resource: Catalog
■ Child Resources: Map Tile, Layer/Table, All Layers/Tables
8.0.2 Map Service Parameters
Parameter / Details
f / Description: The response format
Values: json | (other formats)
8.0.3 Map Service Example / Example

URL for the StateCityHighway service on myserver:

http://myserver/rest/services/StateCityHighway/MapServer

JSON Response Syntax

{

"serviceDescription" : "<serviceDescription>",

"mapName" : "<mapName>"

"description": "<description>",

"copyrightText" : "<copyrightText>",

"layers": [ //the spatial layers exposed by this service

{

"id" : <layerId1>,

"name" : "<layerName1>",

"defaultVisibility" : <true|false>,

"parentLayerId" : <parentLayerId1>,

"subLayerIds" : [<subLayerId11>, <subLayerId12>]

{

"id" : <layerId2>,

"name" : "<layerName2>",

"defaultVisibility" : <true|false>,

"parentLayerId" : <parentLayerId2>,

"subLayerIds" : [<subLayerId21>, <subLayerId22>]

}

"tables": [ //the tables exposed by this service

{

"id" : <tableId1>,

"name" : "<tableName1>"

{

"id" : <tableId2>,

"name" : "<tableName2>"

}

"spatialReference" : {<spatialReference>},

"singleFusedMapCache" : <true | false>,

"tileInfo": {

"rows" : <rows>, "cols" : <cols>, "dpi" : <dpi>, "format" : <format>, "compressionQuality" : <quality>,

"origin" : {<point>},

"spatialReference" : {<spatialReference>},

"lods": [

{"level" : <level1>, "resolution" : <resolution1>, "scale" : <scale1> },

{"level" : <level2>, "resolution" : <resolution2>, "scale" : <scale2> }

]

"initialExtent" : {<envelope>},

"fullExtent" : {<envelope>},

// if the map supports querying and exporting maps based on time

"timeInfo" : {

"timeExtent" : [<startTime>, <endTime>],