Home

geosapi - R Interface to GeoServer REST API

R Interface to GeoServer REST API – Allows to perform programmatically from R

CRUD operations (Create, Read, Update, Delete) on GeoServer resources including workspace, namespaces, dataStores featureTypes, layers, styles, etc.
Data upload to Geoserver data directory (e.g. upload shapefile)

If you wish to sponsor geosapi, do not hesitate to contact me

Table of contents

1. Overview
2. Package status
3. Credits
4. User guide
   4.1 Installation
   4.2 Connect to GeoServer REST API
   4.3 GeoServer workspaces
      4.3.1 Get a (list of) workspace(s)
      4.3.2 Create a new workspace
      4.3.3 Update a new workspace
      4.3.4 Delete a new workspace
   4.4 GeoServer namespaces
      4.4.1 Get a (list of) namespace(s)
      4.4.2 Create a new namespace
      4.4.3 Update a new namespace
      4.4.4 Delete a new namespace
   4.5 Manage vector data in GeoServer
      4.5.1 GeoServer dataStores
         4.5.1.1 Get a (list of) dataStore(s)
         4.5.1.2 Create a new dataStore
            4.5.1.2.1 Create a Shapefile dataStore
         4.5.1.3 Update a new dataStore
         4.5.1.4 Delete a new dataStore
      4.5.2 GeoServer featureTypes
         4.5.2.1 Get a (list of) featureType(s)
         4.5.2.2 Create a new featureType
         4.5.2.3 Update a new featureType
         4.5.2.4 Delete a new featureType
      4.5.3 GeoServer layers
         4.5.3.1 Get a (list of) layer(s)
         4.5.3.2 Create a new layer
         4.5.3.3 Update a new layer
         4.5.3.4 Delete a new layer
      4.5.4 Publication of GeoServer feature layer
         4.5.4.1 Publish Geoserver feature layer
         4.5.4.2 Unpublish Geoserver feature layer
      4.5.5 GeoServer layer groups
         4.5.5.1 Get a (list of) layer group(s)
         4.5.5.2 Create a new layer group
         4.5.5.3 Update a new layer group
         4.5.5.4 Delete a new layer group
   4.6 Manage raster data in GeoServer
   4.7 Manage styles in GeoServer
      4.7.1 Get a (list of) style(s)
      4.7.2 Create a new style
      4.7.3 Update a new style
      4.7.4 Delete a new style
   4.8 Manage settings in GeoServer
      4.8.1 Workspace settings
      4.8.2 OGC Services settings
5. API Documentation
6. Issue reporting

1. Overview and vision

Until now, equivalent tools were existing for other programming languages (e.g. Java, Python) but not in R. geosapi intends to provide R native interface to the GeoServer REST API, in order to facilitate publication of geographic data resources from R to GeoServer.

2. Development status

Under development. Vector data management is currently supported with the first release of geosapi.

Published on CRAN

3. Credits

Package distributed under MIT license.

If you use geosapi, i would be very grateful if you can add a citation in your published work. By citing geosapi, beyond acknowledging the work, you contribute to make it more visible and guarantee its growing and sustainability. You can get the preferred citation by running citation("geosapi) in R.

You can reference geosapi through its DOI:

4. User guide

4.1 How to install geosapi in R

For now, the package can be installed from Github

install.packages("devtools")

Once the devtools package loaded, you can use the install_github to install geosapi. By default, package will be installed from master`` which is the current version in development (likely to be unstable).

require("devtools")
install_github("eblondel/geosapi")

4.2 Connect to GeoServer REST API

The main entry point of geosapi is the GSManager. To configure it, enter the following line, specifying the base URL of your GeoServer, and your credentials:

gsman <- GSManager$new(
    url = "http://localhost:8080/geoserver", #baseUrl of the Geoserver
    user = "admin", pwd = "geoserver", #credentials
    logger = NULL #logger, for info or debugging purpose
)

By default, the geosapi logger is deactivated. To enable the logger, specify the level of log you wish as parameter of the above R code. Two logging levels are available:

INFO: will print the geosapi logs. Three types of messages can be distinguished: INFO, WARN, ERROR. The latter is generally associated with a stop and indicate an blocking error for the R method executed.
DEBUG will print the above geosapi logs, and report all logs from HTTP requests performed with cURL

The GSManager inherits all methods of resource dependent managers, to provide the users with a single R interface to GeoServer REST API operations. In addition, the GSManager allows accessing the different resource managers through specific methods. The following managers are available:

GSNamespaceManager: Manage namespaces
GSWorkspaceManager: Manage workspaces
GSDataStoreManager: Manage dataStores

4.3 Manipulate GeoServer `workspaces`

GeoServer API doc: http://docs.geoserver.org/stable/en/user/rest/api/workspaces.html

4.3.1 Get a (list of) `workspace(s)`

  #get workspace objects
  wslist <- gsman$getWorkspaces()

  #get workspace names only
  wsnames <- gsman$getWorkspaceNames()

  #get workspace by name
  ws <- gsman$getWorkspace("topp")

4.3.2 Create a new `workspace`

  created <- gsman$createWorkspace("geosapi", "http://geoapi")

4.3.3 Update an existing `workspace`

  updated <- gsman$updateWorkspace("geosapi", "http://newgeoapi")

4.3.4 Delete an existing `workspace`

  deleted <- gsman$deleteWorkspace("geosapi", recurse = TRUE)

The recurse parameter allows to delete all layers published under the deleted workspace.

#### 4.4 Manipulate GeoServer ``namespaces``

GeoServer API doc: http://docs.geoserver.org/stable/en/user/rest/api/namespaces.html

4.4.1 Get a (list of) `namespace(s)`

  #get namespace objects
  nslist <- gsman$getNamespaces()

  #get namespace names only
  nsnames <- gsman$getNamespaceNames()

  #get namespace by name
  ns <- gsman$getNamespace("topp")

4.4.2 Create a new `namespace`

  created <- gsman$createNamespace("geosapi", "http://geoapi")

4.4.3 Update an existing `namespace`

  updated <- gsman$updateNamespace("geosapi", "http://newgeoapi")

4.4.4 Delete an existing `namespace`

  deleted <- gsman$deleteNamespace("geosapi", recurse = TRUE)

The recurse parameter allows to delete all layers published under the deleted namespace.

4.5 Manage vector data with GeoServer

##### 4.5.1 Manipulate GeoServer ``dataStores``

GeoServer API doc: http://docs.geoserver.org/stable/en/user/rest/api/datastores.html

4.5.1.1 Get a (list of) `dataStore(s)`

  #get datastore objects
  dslist <- gsman$getDataStores("topp")

  #get datastore names only
  dsnames <- gsman$getDataStoreNames("topp")

  #get datastore by name
  ns <- gsman$getDataStore("topp", "states_shapefile")

4.5.1.2 Create a new `dataStore`

####### 4.5.1.2.1 Create a **Shapefile** ``dataStore``

  ds = GSShapefileDataStore$new(dataStore="topp_datastore",
                                description = "topp_datastore description",
                                enabled = TRUE,
                                url = "file:data/shapefiles/states.shp")
  created <- gsman$createDataStore("topp", ds)

4.5.1.3 Update an existing `dataStore`

  dataStore <- gsman$getDataStore("topp", "topp_datastore")
  dataStore$setDescription("topp_datastore updated description")
  dataStore$setEnabled(FALSE)
  
  updated <- gsman$updateDataStore("topp", dataStore)

4.5.1.4 Delete an existing `dataStore`

  deleted <- gsman$deleteDataStore("topp", "topp_datastore", recurse = TRUE)

The recurse parameter allows to delete all layers published under the deleted datastore.

4.5.2 Manipulate GeoServer `featureType`

GeoServer API doc: http://docs.geoserver.org/stable/en/user/rest/api/featuretypes.html

4.5.2.1 Get a (list of) `featureType(s)`

  #get featureType objects
  ftlist <- gsman$getFeatureTypes("topp", "taz_shapes")

  #get featureType names only
  ftnames <- gsman$getFeatureTypeNames()

  #get featureType by name
  ft <- gsman$getFeatureType("topp", "taz_shapes", "tasmania_cities")

4.5.2.2 Create a new `featureType`

  #create featuretype object
  featureType <- GSFeatureType$new()
  featureType$setName("tasmania_cities2")
  featureType$setNativeName("tasmania_cities")
  featureType$setAbstract("abstract")
  featureType$setTitle("title")
  featureType$setSrs("EPSG:4326")
  featureType$setNativeCRS("EPSG:4326")
  featureType$setEnabled(TRUE)
  featureType$setProjectionPolicy("REPROJECT_TO_DECLARED")
  featureType$setLatLonBoundingBox(-180,-90,180,90, crs = "EPSG:4326")
  featureType$setNativeBoundingBox(-180,-90,180,90, crs ="EPSG:4326") 
  
  md1 <- GSMetadataLink$new(type = "text/xml", metadataType = "ISO19115:2003", content = "http://somelink.org/xml")
  featureType$addMetadataLink(md1)
  md2 <- GSMetadataLink$new(type = "text/html", metadataType = "ISO19115:2003", content = "http://somelink.org/html")
  featureType$addMetadataLink(md2)

  #create the feature type in GeoServer
  created <- gsman$createFeatureType("topp", "taz_shapes", featureType)

How to set a Geoserver SQL View

With geosapi, it is also possible to configure a Geoserver SQL View, possibly with dynamic parameters. For this, GeoServer uses the concept of VirtualTable. The code below explains how to configure such virtual table with geosapi:

##virtual table
vt <- GSVirtualTable$new()
vt$setName("view name")
vt$setSql("select * from mydataset where flag = '%flag%' and year between %start_year% and %end_year%")

## incase of spatial virtual table, specify the geometry column name, type and SRID
vtg <- GSVirtualTableGeometry$new(name = "the_geom", type = "MultiPolygon", srid = 4326)
vt$setGeometry(vtg)

##in case of dynamic parameters handled in your sql (bound with %)
vtp1 <- GSVirtualTableParameter$new(name = "flag", defaultValue = "FRA", regexpValidator = "^[\\w\\d\\s]+$")
vtp2 <- GSVirtualTableParameter$new(name = "start_year", defaultValue = "2000",regexpValidator = "^[\\d]+$")
vtp3 <- GSVirtualTableParameter$new(name = "end_year", defaultValue = "2010",regexpValidator = "^[\\d]+$")
vt$addParameter(vtp1)
vt$addParameter(vtp2)
vt$addParameter(vtp3)

##add virtual table to featureType
featureType$setVirtualTable(vt)

4.5.2.3 Update an existing `featureType`

  #fetch featureType and update some properties
  featureType <- gsman$getFeatureType("topp", "taz_shapes", "tasmania_cities2")
  featureType$setAbstract("abstract updated")
  featureType$setEnabled(FALSE)
  
  #update featureType in GeoServer
  updated <- gsman$updateFeatureType("topp", "taz_shapes", featureType)

4.5.2.4 Delete an existing `featureType`

  deleted <- gsman$deleteFeatureType("topp", "taz_shapes", "tasmania_cities2", recurse = TRUE)

The recurse parameter allows to delete the layer published for the deleted featureType.

4.5.3 Manipulate GeoServer `layers`

GeoServer API doc: http://docs.geoserver.org/stable/en/user/rest/api/layers.html

4.5.3.1 Get a (list of) `layer(s)`

  #get layer objects
  layers <- gsman$getLayers()

  #get layer names only
  layerNames <- gsman$getLayerNames()

  #get layer by name
  layer <- gsman$getLayer("tasmania_cities")

4.5.3.2 Create a new `layer`

This method shows how to publish a created featureType (as created in 4.6.2 Create a new FeatureType)

  layer <- GSLayer$new()
  layer$setName("tasmania_cities2")
  layer$setDefaultStyle("capitals")
  layer$addStyle("generic")
  created <- gsman$createLayer(layer)

4.5.3.3 Update an existing `layer`

  lyr <- gsman$getLayer("tasmania_cities")
  lyr$setDefaultStyle("generic")
  updated <- gsman$updateLayer(lyr)

###### 4.5.3.4 Delete an existing ``layer``

  deleted <- gsman$deleteLayer("tasmania_cities2")

4.5.4 Publication of GeoServer feature layer

GeoServer manages feature data layers by means of two different types of resources: the featureType and the layer. When created, the latter will publish the former. Hence, in order to publish a complete feature data layer, two GeoServer resources should be created. The below methods allow the user to do both creation through a single method. To distinguish them from the above API methods and avoid confusion, we don't use the terminology create / delete but publish / unpublish.

4.5.4.1 Publish Geoserver feature layer

The method publishLayer will sequentially do two requests to GeoServer:

Create featureType
Create layer

  #create featuretype
  featureType <- GSFeatureType$new()
  featureType$setName("tasmania_cities2")
  featureType$setNativeName("tasmania_cities")
  featureType$setAbstract("abstract")
  featureType$setTitle("title")
  featureType$setSrs("EPSG:4326")
  featureType$setNativeCRS("EPSG:4326")
  featureType$setEnabled(TRUE)
  featureType$setProjectionPolicy("REPROJECT_TO_DECLARED")
  featureType$setLatLonBoundingBox(-180,-90,180,90, crs = "EPSG:4326")
  featureType$setNativeBoundingBox(-180,-90,180,90, crs ="EPSG:4326") 
  md1 <- GSMetadataLink$new(type = "text/xml", metadataType = "ISO19115:2003", content = "http://somelink.org/xml")
  featureType$addMetadataLink(md1)
  md2 <- GSMetadataLink$new(type = "text/html", metadataType = "ISO19115:2003", content = "http://somelink.org/html")
  featureType$addMetadataLink(md2)
  
  #create layer
  layer <- GSLayer$new()
  layer$setName("tasmania_cities2")
  layer$setDefaultStyle("capitals")
  layer$addStyle("generic")
  
  #try to publish the complete layer (featuretype + layer)
  published <- gsman$publishLayer("topp", "taz_shapes", featureType, layer)

4.5.4.2 Unpublish Geoserver feature layer

The method publishLayer will sequentially do two requests to GeoServer:

Delete layer
Delete featureType

  #try to unpublish the complete layer (featuretype + layer)
  published <- gsman$unpublishLayer("topp", "taz_shapes", "tasmania_cities2")

4.5.5 Manipulate GeoServer `layer groups`

GeoServer API doc: http://docs.geoserver.org/stable/en/user/rest/api/layergroups.html

4.5.5.1 Get a (list of) `layer group(s)`

  #get layer groups objects
  layerGroups <- gsman$getLayerGroups()

  #get layer group names only
  layerGroupNames <- gsman$getLayerGroupNames()

  #get layer group by name
  layerGroup <- gsman$getLayerGroup("test_layergroup")

4.5.5.2 Create a new `layer group`

  lyr <- GSLayerGroup$new()
  lyr$setName("test_layergroup")
  lyr$setTitle("title")
  lyr$setAbstract("abstract")
  lyr$setMode("SINGLE")
  lyr$addLayer(layer = "tasmania_cities", style = "generic")
  lyr$setBounds(-180,-90,180,90,crs = "EPSG:4326")
  gsman$createLayerGroup(layerGroup = lyr)

4.5.5.3 Update an existing `layer group`

  lyr <- GSLayerGroup$new()
  lyr$setName("test_layergroup")
  lyr$setTitle("title")
  lyr$setAbstract("abstract 2")
  lyr$setMode("SINGLE")
  lyr$addLayer(layer = "tasmania_cities", style = "generic")
  lyr$setBounds(-180,-90,180,90,crs = "EPSG:4326")
  gsman$updateLayerGroup(layerGroup = lyr)

4.5.5.4 Delete an existing `layer group`

  deleted <- gsman$deleteLayerGroup("test_layergroup")

4.6. Manage raster data with GeoServer

Currently not supported with geosapi R package

4.7. Manage styles with GeoServer

4.7.1 Get a (list of) `style`(s)

  styles <- gsman$getStyles()
  stylenames <- gsman$getStyleNames()
  style <- gsman$getStyle("capitals")

From GeoServer 2.2, it is also possible to get the content of a style, ie the SLD body:

  sld <- gsman$getSLDBody("capitals")

4.7.2 Create a new `style`

  sldFile <- system.file("extdata", "mystyle.sld", package = "geosapi") #to use 'file' argument of gsman$createStyle
  sldStyle <- xmlParse(sldFile) #to use 'sldBody' argument of gsman$createStyle
  created <- gsman$createStyle(file = sldFile, name = "mystyle")

4.7.3 Update a new `style`

  sldFile2 <- system.file("extdata", "mystyle2.sld", package = "geosapi") #to use 'file' argument of gsman$updateStyle
  sldStyle2 <- xmlParse(sldFile2) #to use 'sldBody' argument of gsman$updateStyle
  updated <- gsman$updateStyle(sldBody = sldStyle2, name = "mystyle")

4.7.4 Delete an existing `style`

  deleted <- gsman$deleteStyle("mystyle", recurse = TRUE, purge = TRUE)

All methods describe here above also support a ws argument where a workspace can be specified.

4.8. Manage settings with GeoServer

4.8.1 Workspace settings

TBD

4.8.2 OGC Service settings

TBD

5. API documentation

TBD

6. Issue reporting

Issues can be reported at https://github.com/eblondel/geosapi/issues

Home

geosapi - R Interface to GeoServer REST API

1. Overview and vision

2. Development status

3. Credits

4. User guide

4.1 How to install geosapi in R

4.2 Connect to GeoServer REST API

4.3 Manipulate GeoServer workspaces

4.3.1 Get a (list of) workspace(s)

4.3.2 Create a new workspace

4.3.3 Update an existing workspace

4.3.4 Delete an existing workspace

4.4.1 Get a (list of) namespace(s)

4.4.2 Create a new namespace

4.4.3 Update an existing namespace

4.4.4 Delete an existing namespace

4.5 Manage vector data with GeoServer

4.5.1.1 Get a (list of) dataStore(s)

4.5.1.2 Create a new dataStore

4.5.1.3 Update an existing dataStore

4.5.1.4 Delete an existing dataStore

4.5.2 Manipulate GeoServer featureType

4.5.2.1 Get a (list of) featureType(s)

4.5.2.2 Create a new featureType

4.5.2.3 Update an existing featureType

4.5.2.4 Delete an existing featureType

4.5.3 Manipulate GeoServer layers

4.5.3.1 Get a (list of) layer(s)

4.5.3.2 Create a new layer

4.5.3.3 Update an existing layer