Documentation Geocure (Geodata REST-API)

About

The 52°North Geocure Rest API serves as a proxy for OGC Web- and Featureservices, which enables a REST-like interaction with WM- and WF-services. The goal is to provide an easy to use interface for accessing geodata.

Currently the GeoServer is supported.
Please keep in mind:
Currently GeoServer version 10.11-beta can send exceptions in JSON-format, which are piped to the client. Prior versions will send xml.

Document status

What	When
Initial creation	2016-08-16
Updating documentation	2017-01-21
Updating Endpoint maps -> map	2017-04-15
SLD & getFeatureInfo	2017-09-26
SLD update: sldbody -> sld	2017-10-24

Role of Geocure

As you can see in the diagram above, the client communicates with Geocure, using the REST-API described in this documentation. Geocure translates the requests for the Geoserver and returns the answers per defaultas JSON.

Configuration

All configurations are carried out in services.json, locatet in the folder app/config. In this file an array is used to aggregate objects. Each object is used to described an offered service. An offered service is a service which is offered by the used Geoserver.


                          [
                              {
                                  "id" : "example_A",
                                  "label" : "Lable can be used for a short description or a self-describing name.",
                                  "description" : "Description of the service",
                                  "url" : "http://localhost:8080/geoserver/example_A",
                                  "capabilities" : {
                                      "map" : {
                                          "enabled" : true,
                                          "defaultvalues" : {
                                              "width" : 1330,
                                              "height" : 944,
                                              "format" : "image/png"
                                          }

                                      },
                                      "features" : {
                                          "enabled" : true,
                                          "defaultvalues" : {
                                              "format" : "application/json"
                                          }
                                      }
                                  }

                              },
                              {
                                  "id" : "example_B",
                                  "label" : "Lable can be used for a short description or a self-describing name.",
                                  "description" : "Description of the service",
                                  "url" : "http://localhost:8080/geoserver/example_B",
                                  "capabilities" : {
                                      "map" : {
                                          "enabled" : true,
                                          "defaultvalues" : {
                                              "width" : 1330,
                                              "height" : 944,
                                              "format" : "image/png"
                                          }

                                      },
                                      "features" : {
                                          "enabled" : false,
                                          "defaultvalues" : {
                                              "format" : "application/json"
                                          }
                                      }
                                  }

                              },
                              {
                                  "id" : "example_C",
                                  "label" : "Lable can be used for a short description or a self-describing name.",
                                  "description" : "Description of the service",
                                  "url" : "http://localhost:8080/geoserver/example_C",
                                  "capabilities" : {
                                      "map" : {
                                          "enabled" : false,
                                          "defaultvalues" : {
                                              "width" : 1330,
                                              "height" : 944,
                                              "format" : "image/png"
                                          }

                                      },
                                      "features" : {
                                          "enabled" : false,
                                          "defaultvalues" : {
                                              "format" : "application/json"
                                          }
                                      }
                                  }

                              }
                          ]

Description of an services.json object

Key	Allowed values	Description
id	alphanumerical value without spaces	As the key connotes, the id must be under all ids in the array unique. The id is used to identifie a services in a request.
label	alphanumerical values and spaces	Used to provice a descriptive name for the service.
description	alphanumerical values and spaces	Description of the service. For instance what is offered and what the use is.
url	url	The url to the service in Geoserver.
capabilities	object	The elements of this object are used to configure capabilities and defaultvalues for the service.
map	object	This object describes the capabilities of a map.
features	object	This object describes the capabilities for features/data.
enabled	boolean	If true, Geocure enables requesting of maps/images respectively features/data. If both (maps and features) are disabled (false), the whole service is not listed in Geocure. By this means, services can be disabled without deleting the whole configuration in services.json
defaultvalues	object	Allows defaultvalues for requests, so these have not to be repeated with every request. Whether they are used or not, defaultvalues have to be given.
width	integer > 0	The width of an returned image in pixel.
height	integer > 0	The height of an returned image in pixel.
format	string	The format of the requested image/data. It must be correspond the the formats, supported by Geoserver.

Common Status Codes

A client shall expect the following HTTP status codes returned by the API.

Code	When
`200`	Status `OK`. Nothing detected
`404`	Status `Bad Request`. The request is not valid.
`500`	Status `Internal Server Error`. An internal error in Geocure appeared.
`900`	Status `Error in Geocure or Geoserver`. Origin of the error can be taken from the errormessage.

Endpoint URL

A valid endpoint for testing is provided by the following enpoint URL: http://colabis.dev.52north.org/geocure/services.

URLs

API calls are triggered by using the following URLs.

Method	Path	Content-Type	Description
`GET`	`<base-url>/services`	`application/json`	Returns a list of offered services.

Examples

Available Services Request

GET http://colabis.dev.52north.org/geocure/services HTTP/1.1
Host: colabis.dev.52north.org
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

[

    {
        "id": "service1COLABIS",
        "label": "name of the service",
        "description": "Returns sample data via a WM-Service",
        "href": "http://colabis.dev.52north.org/geocure/services/service1COLABIS"
    }

]

The returned values are defined in the file services/services.json. For more information, see Configuration.
The value of href is a composition of the current href and the id of the service. It is a reference to the next ressource.

URLs

API calls are triggered by using the following URLs.

Method	Path	Content-Type	Description
`GET`	`<base-url>/services/{service-id}`	`application/json`	Returns the capabilities of a requested service.

Examples

GET http://colabis.dev.52north.org/geocure/services/service1COLABIS HTTP/1.1
Host: colabis.dev.52north.org
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{

    "id": "service1COLABIS",
    "label": "name of the service",
    "description": "Returns sample data via a WM-Service",
    "capabilities": [
        "http://colabis.dev.52north.org/geocure/services/service1COLABIS/map",
        "http://colabis.dev.52north.org/geocure/services/service1COLABIS/features"
    ]

}

The value of the key capabilities is an array, containing hrefs. As the endpoints of these indicate, they are poining to the resources map and features.
Only for enabled services the corresponding href is returned. For further information, see Configuration.

URLs

API calls are triggered by using the following URLs.

Method	Path	Content-Type	Description
`GET`	`<base-url>/services/{service-id}/map`	`application/json`	Returns an overview of the offered layers and their global extent for the service with id `{service-id}`.

Query Parameters

For map-request several queryparameters are supported. The paramater layer is obligatory!

Parameter	Example	Description	Default values
`layer`	`layer=mapLayer1,mapLayer2`	Single layer or comma separated list of of layers. The order matters. The first layer is drawn on top, and so on.	No default value.
`bbox`	`bbox=5.86,47.27,15.04,55.05`	Changes the extend of the uses bbox	Values from WMS_1_3_0.EXGeographicBoundingBox. See resource map The order for the coordinates is minx,miny,maxx,maxy
`width`	`width=500`	Number of pixels for image width.	Taken from services.json See configuration
`height`	`height=500`	Number of pixels for image height.	Taken from services.json See configuration
`format`	`format=image/png`	Sets the response format	Taken from services.json See configuration
`transparent`	`transparent=true`	With true, the background is transparent (not possible for all formats).	`false`
`bgcolor`	`bgcolor=0x000000`	Hex-code for background color.	`0xFFFFFF`
`sld`	See example below	Styling with sld	No default, but optional
`crs`	`crs=EPSG:4326`	Sets the coordinate reference system of the response. May be restricted by the service. Currently supported by Geocure: `EPSG:4326` `EPSG:4269` `EPSG:5243` `EPSG:4839` `EPSG:3068` `EPSG:3857`	`EPSG:4326`

Since the query parameter layer has no default value, the client has to provide it.
All other parameters are optional.

Examples

Resource Description

GET http://colabis.dev.52north.org/geocure/services/service1COLABIS/map HTTP/1.1
    Host: colabis.dev.52north.org
    Accept: application/json

HTTP/1.1 200 OK
    Content-Type: application/json;charset=UTF-8

    {

        "layers": [
            {
                "id": "ckandev:_23964ffe_67e1_476c_9c71_f25ed8dfe5e2",
                "title": "Sample measurements of road pollution in Dresden ",
                "href": "http://localhost:8001/services/service1COLABIS/map/render?layer=ckandev:_23964ffe_67e1_476c_9c71_f25ed8dfe5e2"
            },
            {
                "id": "ckandev:_a2508d4e_74c1_4a02_b1cc_c05db68f538e",
                "title": "DWD administrative areas",
                "href": "http://localhost:8001/services/service1COLABIS/map/render?layer=ckandev:_a2508d4e_74c1_4a02_b1cc_c05db68f538e"
            },
            {
                "id": "ckandev:_eece6e0c_0384_4889_9cb8_8529bd148116",
                "title": "dwd-regionen-staedte-und-gemeinden",
                "href": "http://localhost:8001/services/service1COLABIS/map/render?layer=ckandev:_eece6e0c_0384_4889_9cb8_8529bd148116"
            }
        ],
        "crs": [
            {
                "TYPE_NAME": "WMS_1_3_0.EXGeographicBoundingBox",
                "westBoundLongitude": 5.82013988494873,
                "eastBoundLongitude": 15.0836019515991,
                "southBoundLatitude": 47.2314224243164,
                "northBoundLatitude": 55.0963134765625,
                "crs": "EPSG:4326"
            }
        ]

    }

The response shows an array of layer-objects. Each object has the property "id", which is used to request the laye from the service. The property "title" describes the layer. "href" is the url to request the layer.
crs describes the maximal boundingbox.

Image Requests

API calls are triggered by using the following URLs.

Method	Path	Content-Type	Description
`GET`	`<base-url>/services/{service-id}/map/render`	`image/png`	This is the basic url for request. But keep in minde, that it has to be completed with at least the requested layer(s)

Minimal Examples

GET http://colabis.dev.52north.org/services/service1COLABIS/map/render?layer=ckandev:_a2508d4e_74c1_4a02_b1cc_c05db68f538e HTTP/1.1
                                        
Host: colabis.dev.52north.org
Accept: image/png

HTTP/1.1 200 OK
                                  Content-Type: image/png;

In this example, a single layer is requested. This is the most basic form of a request.

Maximal Examples without SLD

GET http://colabis.dev.52north.org/services/service1COLABIS/map/render?layer=ckandev:_eece6e0c_0384_4889_9cb8_8529bd148116,ckandev:_23964ffe_67e1_476c_9c71_f25ed8dfe5e2&bbox=13,50,14,52&width=250&height=350&EPSG:4326&format=image/tiff&transparent=false&bgcolor=0xFFFFFF
                      
Host: localhost:8001
Accept: image/tiff

HTTP/1.1 200 OK
                      Content-Type: image/tiff;

This example shows a request, asking for two layers and using all supported request parameters.

Examples with SLD

GET http://colabis.dev.52north.org/geocure/services/colabis-geoserver/map/render?service=WMS&version=1.3.0&request=GetMap&format=image/png&transparent=true&layer=ckan:_d6bea91f_ac86_4990_a2d5_c603de92e22c&tiled=true&width=256&height=256&crs=EPSG:4326&styles=&bbox=13.7109375,51.064453125,13.7548828125,51.1083984375&sld=%3CStyledLayerDescriptor%0A%20version%3D%221.3.0%22%0A%20xsi%3AschemaLocation%3D%22http%3A%2F%2Fschemas.opengis.net%2Fsld%2F1.3.0%2FStyledLayerDescriptor.xsd%22%0A%20xmlns%3D%22http%3A%2F%2Fwww.opengis.net%2Fsld%22%0A%20xmlns%3Aogc%3D%22http%3A%2F%2Fwww.opengis.net%2Fogc%22%0A%20xmlns%3Axlink%3D%22http%3A%2F%2Fwww.w3.org%2F1999%2Fxlink%22%0A%20xmlns%3Axsi%3D%22http%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema-instance%22%3E%20%20%3CNamedLayer%3E%0A%3CName%3Eckan%3A_d6bea91f_ac86_4990_a2d5_c603de92e22c%3C%2FName%3E%0A%20%20%20%3CUserStyle%3E%3CTitle%3ESLD%20Cook%20Book%3A%20Simple%20polygon%3C%2FTitle%3E%3CFeatureTypeStyle%3E%3CRule%3E%3CPolygonSymbolizer%3E%3CFill%3E%3CCssParameter%20name%3D%22fill%22%3E%230000FF%3C%2FCssParameter%3E%3C%2FFill%3E%20%3CStroke%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3CCssParameter%20name%3D%22stroke%22%3E%23FF50AA%0A%3C%2FCssParameter%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3CCssParameter%20name%3D%22stroke-width%22%3E2%3C%2FCssParameter%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3C%2FStroke%3E%3C%2FPolygonSymbolizer%3E%3C%2FRule%3E%3C%2FFeatureTypeStyle%3E%3C%2FUserStyle%3E%0A%20%3C%2FNamedLayer%3E%0A%3C%2FStyledLayerDescriptor%3E%0A%0A%0A
                      
Host: localhost:8001
Accept: image/png

HTTP/1.1 200 OK
                      Content-Type: image/png;

This example shows a request, using sld to style the response.
The sld part can be decoded/encoded here: meyerweb.com

URLs

API calls are triggered by using the following URLs.

Method	Path	Content-Type	Description
`GET`	`<base-url>/services/{service-id}/map/info`	`application/json`	Provides information to elements on map.

Query Parameters

Parameters to request information from elements on map.

Parameter	Example	Description	Default values
`layer`	`layer=mapLayer1,mapLayer2`	Single layer or comma separated list of of layers. The order matters. The first layer is drawn on top, and so on.	No default value.
`bbox`	`bbox=5.86,47.27,15.04,55.05`	Changes the extend of the uses bbox	Values from WMS_1_3_0.EXGeographicBoundingBox. See resource map The order for the coordinates is minx,miny,maxx,maxy
`width`	`width=500`	Number of pixels for image width.	Default taken from services.json See configuration
`height`	`height=500`	Number of pixels for image height.	Default taken from services.json See configuration
`format`	`format=image/png`	Sets the response format	Default taken from services.json See configuration
`x`	`x=320`	Pixel coordinate for getFeatureInfo request	No default.
`y`	`y=320`	Pixel coordinate for getFeatureInfo request	No default.
`feature_count`	`feature_count=50`	Maximum number of features to return.	Default is 1.
`buffer`	`buffer=10`	search radius around query point.	Default is 3.
`info_format`	`info_format=text/html`	Format for the feature information response: `text/plain` `application/vnd.ogc.gml` `application/vnd.ogc.gml/3.1.1` `text/html` `application/json` `text/javascript`	`application/json`
`crs`	`crs=EPSG:4326`	Sets the coordinate reference system of the response. May be restricted by the service. Currently supported by Geocure: `EPSG:4326` `EPSG:4269` `EPSG:5243` `EPSG:4839` `EPSG:3068` `EPSG:3857`	`EPSG:4326`

Since the query parameters layer, x, y have no default values, the client has to provide these.
All other parameters are optional.

Minimal Examples

GET http://127.0.0.1:8002/geocure/services/colabis-geoserver/map/info?layer=ckan:_53fbae20_e2fb_4fd1_b5d6_c798e11b96d1,ckan:_7f1cce1a_62b3_49f3_ac3f_cf73ed1586fa,ckan:_8e2bef33_248f_42b5_bd50_0f474a54d11f,ckan:_9f064e17_799e_4261_8599_d3ee31b5392b&x=400&y=350&buffer=100&info_format=text/javascript HTTP/1.1
                                        
Host: colabis.dev.52north.org
Accept: application/json

HTTP/1.1 200 OK
                                  Content-Type: application/json;

Content-Type: text/javascript ;charset=UTF-8 parseResponse({"type":"FeatureCollection","totalFeatures":"unknown","features":[{"type":"Feature","id":"_53fbae20_e2fb_4fd1_b5d6_c798e11b96d1.553","geometry":{"type":"MultiPolygon","coordinates":[[[[8.444678,52.361456],[8.46112,52.317408],[8.463046,52.276068],[8.396957,52.282587],[8.345655,52.27155],[8.324176,52.277571],[8.293352,52.304279],[8.290541,52.326978],[8.31145,52.349808],[8.329124,52.35047],[8.339329,52.36712],[8.360447,52.361563],[8.390992,52.38382],[8.444678,52.361456]]]]},"geometry_name":"wkb_geometry","properties":{"warncellid":803459003,"ags_2015":"03459003","name":"Bad Essen","typed_name":"Gemeinde Bad Essen","state":"NS","min_height":0,"max_height":400}}],"crs":{"type":"name","properties":{"name":"urn:ogc:def:crs:EPSG::4326"}}})

Maximal Examples

GET https://geoserver.colabis.de/geoserver/wms?SERVICE=wms&VERSION=1.1.1&REQUEST=GetFeatureInfo&srs=EPSG:4326&format=application/json&layers=ckan:_53fbae20_e2fb_4fd1_b5d6_c798e11b96d1,ckan:_7f1cce1a_62b3_49f3_ac3f_cf73ed1586fa,ckan:_8e2bef33_248f_42b5_bd50_0f474a54d11f,ckan:_9f064e17_799e_4261_8599_d3ee31b5392b&bbox=5.86599881341562,47.270362,15.037743335938,55.057374701071&WIDTH=1330&HEIGHT=944&x=400&y=350&query_layers=ckan:_53fbae20_e2fb_4fd1_b5d6_c798e11b96d1,ckan:_7f1cce1a_62b3_49f3_ac3f_cf73ed1586fa,ckan:_8e2bef33_248f_42b5_bd50_0f474a54d11f,ckan:_9f064e17_799e_4261_8599_d3ee31b5392b&info_format=text/plain&buffer=100  HTTP/1.1
                                  
Host: localhost:8001
Accept: text/plain

HTTP/1.1 200 OK
            Content-Type: text/html;

Results for FeatureType 'de.colabis.ckan:_53fbae20_e2fb_4fd1_b5d6_c798e11b96d1': -------------------------------------------- wkb_geometry = [GEOMETRY (Polygon) with 14 points] warncellid = 803459003 ags_2015 = 03459003 name = Bad Essen typed_name = Gemeinde Bad Essen state = NS min_height = 0 max_height = 400 --------------------------------------------

URLs

API calls are triggered by using the following URLs.

Method	Path	Content-Type	Description
`GET`	`<base-url>/services/{service-id}/features`	`application/json`	Returns an overview of the offered features and their global extent for the service with id `{service-id}`.

Query Parameters

For feature-requests several queryparameters are supported. No parameter is obligatory!

Parameter	Example	Description	Default values
`bbox`	`bbox=5.86,47.27,15.04,55.05`	Changes the extend of the uses bbox.	Values from WGS84BoundingBoxType. See resource features The order for the coordinates is minx,miny,maxx,maxy
`format`	`format=application/json`	Sets the response format.	Taken from services.json See configuration
`crs`	`crs=EPSG:4326`	Sets the coordinate reference system of the response. May be restricted by the service. Currently supported by Geocure: `EPSG:4326` `EPSG:4269` `EPSG:5243` `EPSG:4839` `EPSG:3068` `EPSG:3857`	`EPSG:4326`

Examples

Resource Description

GET http://colabis.dev.52north.org/geocure/services/service1COLABIS/features HTTP/1.1
                              
Host: colabis.dev.52north.org
Accept: application/json

HTTP/1.1 200 OK
        Content-Type: application/json;charset=UTF-8

        {

            "features": [
                {
                    "id": "ckandev:_a2508d4e_74c1_4a02_b1cc_c05db68f538e",
                    "title": "DWD administrative areas",
                    "href": "http://localhost:8001/services/service1COLABIS/features/ckandev:_a2508d4e_74c1_4a02_b1cc_c05db68f538e/data"
                },
                {
                    "id": "ckandev:_23964ffe_67e1_476c_9c71_f25ed8dfe5e2",
                    "title": "Sample measurements of road pollution in Dresden ",
                    "href": "http://localhost:8001/services/service1COLABIS/features/ckandev:_23964ffe_67e1_476c_9c71_f25ed8dfe5e2/data"
                },
                {
                    "id": "ckandev:_eece6e0c_0384_4889_9cb8_8529bd148116",
                    "title": "dwd-regionen-staedte-und-gemeinden",
                    "href": "http://localhost:8001/services/service1COLABIS/features/ckandev:_eece6e0c_0384_4889_9cb8_8529bd148116/data"
                }
            ],
            "crs": [
                {
                    "TYPE_NAME": "OWS_1_1_0.WGS84BoundingBoxType",
                    "westBoundLongitude": 13.726043,
                    "eastBoundLongitude": 15.0836019515991,
                    "southBoundLatitude": 51.003874,
                    "northBoundLatitude": 55.0963134765625,
                    "crs": "EPSG:4326"
                }
            ]

        }

The response shows an array of feature-objects. Each object has the property "id", which is used to request the feature from the service. The property "title" describes the feature. "href" is the url to request the feature.

Request Data

URLs

API calls are triggered by using the following URLs.

Method	Path	Content-Type	Description
`GET`	`<base-url>/services/{service-id}/map/{feature-id}/data`	`application/json`	Returns the by `{feature-id}` specified feature for a service with id `service-id` in the default format, which is defined in file `services/services.json`.

Minimal Request

GET http://colabis.dev.52north.org/services/service1COLABIS/features/ckandev:_a2508d4e_74c1_4a02_b1cc_c05db68f538e/data HTTP/1.1
            Host: colabis.dev.52north.org
            Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "type": "FeatureCollection",
  "totalFeatures": 403,
  "features": [
    {
      "type": "Feature",
      "id": "_a2508d4e_74c1_4a02_b1cc_c05db68f538e.614",
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
          [
            [
              [
                11.50466915716252,
                50.90692760854206
              ],
              [
                11.50905239913563,
                50.91479018440299
              ],
              [
                11.510171577362986,
                50.91716503595331
              ],
              [
                11.507686894628645,
                50.92533907105912
              ],
              [
                11.504694033263837,
                50.93376036553791
              ],
              [
                11.498977225909524,
                50.95398374662671
              ],
              [
                11.50329752641306,
                50.96734502642258
              ],
              [
                11.508608573086736,
                ...
                ...
                ...

The response shows an extract of the requested data from ckandev:_a2508d4e_74c1_4a02_b1cc_c05db68f538e.

Maximal Request

GET http://colabis.dev.52north.org/services/service1/features/COLABIS_REST_TEST:gis.osm_waterways_v06/data?&bbox=1557352.87110,6613867.768936746,1558472.87111,7361866.11305&crs=EPSG:3857&format=csv
Host: localhost:8001
Accept: text/csv

HTTP/1.1 200 OK
Content-Type: text/csv;

FID,the_geom,osm_id,lastchange,code,fclass,name,width gis.osm_waterways_v06.1111,"MULTILINESTRING ((1557285.7155282141 6652863.81549924, 1557333.8612079823 6652885.923121373, 1557368.5817571608 6652899.329780743, 1557397.0016231602 6652915.648644755, 1557401.209499912 6652921.703857196, 1557419.6217436893 6652933.2815779075))",201855608,2013-01-19T03:28:56Z,8102,stream,,0

In this request, all query parameters are used.

About

Document status

General

Role of Geocure

Configuration

Description of an services.json object

Common Status Codes

Offered Resources

Endpoint URL

URLs

Examples

Available Services Request

Service Capabilities

URLs

Examples

Resource Map

URLs

Query Parameters

Examples

Resource Description

Image Requests

Minimal Examples

Maximal Examples without SLD

Examples with SLD

Resource Map Info

URLs

Query Parameters

Minimal Examples

Maximal Examples

Resource Features

URLs

Query Parameters

Examples

Resource Description

Request Data

URLs

Minimal Request

Maximal Request