We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
GIS Data Provider Open API Specification - FIWARE Forge Wiki

GIS Data Provider Open API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the GIS Data Provider API

Please check the FI-WARE Open Specifications Legal Notice to understand the rights to use FI-WARE Open Specifications.

Interactive, multi-user Web applications such as virtual worlds often have the common requirements of retriveving environmental components for the graphical reproduction. Often this data is related to the geographical information, such as terrain soil, terrain texturing, water areas and such. GIS Data Provider acts as a service which is capable in serving such components via restful API.

GIS Data Provider API Core

The GIS Data Provider API is a RESTful, resource-oriented API accessed via HTTP that uses XML and octet-stream -based representations for information interchange. It is used to query the data contained in GIS Data Provider. The GIS data is organized according to its geographical coordinates which are used to sort the data spatially for the client queries.

Intended Audience

This specification is intended for both software developers and reimplementers of this API. For the former, this document provides a full specification of using the supported operations. For the latter, this specification provides a full specification of how to implement those operations.

API Change History

The GIS Data Provider API version history is described in the table below:

Revision Date Changes Summary
Feb 13, 2014
  • Initial version
May 27, 2015
  • Description part updated

How to Read This Document

All FI-WARE RESTful API specifications will follow the same list of conventions and will support certain common aspects. Please check Common aspects in FI-WARE Open Restful API Specifications.

For a description of some terms used along this document, see the Terns and Definitions.

Additional Resources

Here you can describe any other information or resources that you could need to understand this document. It could include also the link <url> in which to can obtain this specification and the link to obtain the schemas that we are using. E.g.

"You can download the most current version of this document from the FIWARE API specification website at <link to the url>. For more details about the <name of the GE service> that this API is based upon, please refer to <link to the High Level Description>. Related documents, including an Architectural Description, are available at the same site."


General GIS Data Provider API Information

Resources Summary

The following diagram describes the resources that can be accessed with the GIS Data Provider API, starting from the server base URL.

Image:GISRest.png


GIS Data Provider API resource summary

Representation Format

The GIS Data Provider API supports data in XML3D and octet-stream formats by giving format argument in the request.

  • XML3D (model/xml3d+xml)
    • Request returns group of XML3D 3d-models and those can directly be added to DOM tree
    • All coordinate values inside XML3D object are relative values to requested bounding box.
An example of XML3D output format request
   http://hostname:port/path?SERVICE=W3DS&REQUEST=GetScene&VERSION=0.4.0&CRS=EPSG:26916&FORMAT=model/xml3d+xml&BoundingBox=202759.0,3310170.0,213200.0,3320896.0&LAYERS=Terrain
  • XML3D (application/xml)
    • Request returns XML formatted file including group of XML3D 3d-models inside <asset> tag
    • All coordinate values inside XML3D object are relative values to requested bounding box.
    • Models can be used without populating 3D data to DOM tree
An example of XML3D output format request
   http://hostname:port/path?SERVICE=W3DS&REQUEST=GetScene&VERSION=0.4.0&CRS=EPSG:26916&FORMAT=application/xml&BoundingBox=202759.0,3310170.0,213200.0,3320896.0&LAYERS=Terrain
  • Octet-stream (application/octet-stream)
    • Request returns byte array in the following format:
      • First value in the array is 32bit integer with information how many points are in X-axis
      • Second value in the array is 32bit integer with information how many points are in Y-axis
      • Third value in the array is 32bit float with information about average distance between points in X-axis
      • Fourth value in the array is 32bit float with information about average distance between points in Y-axis
    • After those initialization values there are First * Second number of 32bit floats containing elevation information for each point in that grid.
      • First elevation value is from top right corner and last value is bottom left corner.
      • Values are read from a grid one row at a time, reading of each row is started from right to left.

An example of decoded octet-stream output:
   5 5 9.8 9.8 123.1 115.1 116.7 119.0 123.1 115.1 116.7 119.8 123.1 120.1 115.1 118.4 119.0 123.1 123.1 123.1 123.1 123.1 123.1 123.1 123.1 123.1 123.1 123.1 123.1
 
An example of octet-stream output format request
   http://hostname:port/path?SERVICE=W3DS&REQUEST=GetScene&VERSION=0.4.0&CRS=EPSG:3067&FORMAT=application/octet-stream&BOUNDINGBOX=374010,7548000,375210,7549200&LAYERS=Terrain

  • Asset instace (application/xml)
    • Request returns xml file which contains XML3D terrain presentation for the requested bounding box.

Resource Identification

All operations (GET, PUT, POST, DELETE) to the GIS DataProvider API require the target resource to be identified. For HTTP transport, this is made using the mechanisms described by HTTP protocol specification as defined by IETF RFC-2616.

Links and References

N/A.

Limits

N/A.

Versions

N/A.

Extensions

N/A.

Faults

Synchronous Faults

Fault ElementAssociated Error CodesExpected in All Requests?
notFound404The resource was not found for a query operation.
badRequest400The resource identifier was invalid for a modification operation.

When a fault happens, it is also transmitted in the reply body as text for convenience.

Asynchronous Faults

All current GIS Data Provider API operations are synchronous in nature; therefore there are no asynchronous faults.


API Operations

Capability Query

Verb URI Description
GET /path?SERVICE=W3DS&ACCEPTVERSIONS=0.3.0,0.4.0&request=GetCapabilities GetCapabilities operation allows clients to retrieve service metadata from a server. The response to a GetCapabilities request shall be an XML document containing service metadata about the server, including specific information about layer properties and how to access data from the server.

Normal Response Code(s): 200

Error Response Code(s): 404


Scene Query

Verb URI Description
GET /path?SERVICE=W3DS&REQUEST=GetScene&VERSION=0.4.0&CRS=EPSG:26916

&FORMAT=application/xml3d&BoundingBox=202759.0,3310170.0,213200.0,3320896.0&LAYERS=Terrain&LOD=4

The GetScene operation returns a 3D scene representing a subset of the natural or man made structures on the earth surface. Upon receiving a GetScene request, a W3DS shall either satisfy the request or issue a service exception. The required parameters for retrieving a 3D scene from a W3DS comprise spatial, thematic, and other constraints. The minimum set of parameters include, in addition to the mandatory parameters service, request and version, which are part of every W3DS operation, the spatial extent of the scene given as bounding box, the CRS in which the scene shall be provided, the format, and the list of layers. The bounding box defines a rectangular region with edges perpendicular to the selected CRS. LOD is Level of details definition value, this is optional parameter. In order to get LOD working properly, defined layer needs to support LOD data.

Format is the definition of the response data format, there is 3 alternative response data formats available: application/xml3d, application/xml and application/octet-stream. application/xml3d returns XML3D presentation of the requested area, application/xml return xml-file which can be used with asset instancing feature and application/octet-stream return binary data in octet-stream format.

Normal Response Code(s): 200

Error Response Code(s): 404

Feature Info Query

Verb URI Description
GET /path?SERVICE=W3DS&REQUEST=GetFeatureInfo&VERSION=0.4.0&CRS=EPSG:26916

&FORMAT=text/xml&LAYERS=bldgs&FEATURECOUNT=5&COORDINATE=202042.233,3310094.983,334.0&EXCEPTIONS=text/html

The GetFeatureInfo operation is designed to provide clients with additional attribute information about features within a scene that is currently displayed.

Example use case for GetFeatureInfo is that a user explores the response of a GetScene request and points at an object within the scene for which to obtain more information. The concept of this operation is that the client determines a location in 3D space by clicking on an object and calculates either the intersection point of the object geometry with the picking ray or the center point of the object and submits this location together with additional parameters to the server.

Normal Response Code(s): 200

Error Response Code(s): 404

Map Query

Verb URI Description
GET /path?SERVICE=WMS&REQUEST=GetMap&VERSION=1.1.0&SRS=EPSG:26916

&FORMAT=application/octet-stream&BoundingBox=202759.0,3310170.0,213200.0,3320896.0&LAYERS=Terrain&width=100&height=100

The GetMap operation returns a binary data from the requested bounding box area. Binary data contains only information how many elevation points there is within bounding box and what are the elevation values for these points.

Upon receiving a GetMap request, a WMS shall either satisfy the request or issue a service exception. The required parameters for retrieving a 3D map from a WMS comprise spatial, thematic, and other constraints.

The minimum set of parameters include, in addition to the mandatory parameters service, request and version, which are part of every WMS operation, the spatial extent of the map given as bounding box, the SRS in which the scene shall be provided, the format, and the list of layers. The bounding box defines a rectangular region with edges perpendicular to the selected SRS.

Format is the definition of the response data format, application/octet-stream. application/octet-stream return binary data in octet-stream format.

Normal Response Code(s): 200

Error Response Code(s): 404

Personal tools
Create a book