geosapi User Manual

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, settings (workspaces, OGC services) etc.
  • Data upload to Geoserver data directory (e.g. upload shapefile)

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

Many thanks to the following organizations that have provided fundings for strenghtening the geosapi package:

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.2.2 Create a Shapefiles Directory dataStore
            4.5.1.2.3 Create a GeoPackage dataStore
         4.5.1.3 Update a new dataStore
         4.5.1.4 Delete a new dataStore
      4.5.2 Upload features/vector data
      4.5.3 GeoServer featureTypes
         4.5.3.1 Get a (list of) featureType(s)
         4.5.3.2 Create a new featureType
         4.5.3.3 Update a new featureType
         4.5.3.4 Delete a new featureType
      4.5.3 GeoServer layers
         4.5.4.1 Get a (list of) layer(s)
         4.5.4.2 Create a new layer
         4.5.4.3 Update a new layer
         4.5.4.4 Delete a new layer
      4.5.5 Publication of GeoServer feature layer
         4.5.5.1 Publish Geoserver feature layer
         4.5.5.2 Unpublish Geoserver feature layer
      4.5.6 GeoServer layer groups
         4.5.6.1 Get a (list of) layer group(s)
         4.5.6.2 Create a new layer group
         4.5.6.3 Update a new layer group
         4.5.6.4 Delete a new layer group
   4.6 Manage raster data in GeoServer
      4.6.1 GeoServer coveragestores
         4.6.1.1 Get a (list of) coveragestore(s)
         4.6.1.2 Create a new coveragestore
            4.6.1.2.1 Create a GeoTIFF coveragestore
            4.6.1.2.2 Create a WorldImage coveragestore
            4.6.1.2.3 Create a ArcGrid coveragestore
            4.6.1.2.4 Create a ImageMosaic coveragestore
         4.6.1.3 Update a new coveragestore
         4.6.1.4 Delete a new coveragetore
      4.6.2 Upload coverage/raster data
      4.6.3 GeoServer coverages
         4.6.3.1 Get a (list of) coverage(s)
         4.6.3.2 Create a new coverage
         4.6.3.3 Update a new coverage
         4.6.3.4 Delete a new coverage
   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 workspace settings in GeoServer
      4.8.1 Create a workspace settings
      4.8.2 Get a workspace settings
      4.8.3 Update a workspace settings
      4.8.4 Delete a workspace settings
   4.9 Manage OGC service (WMS/WFS/WCS) settings in GeoServer
      4.9.1 Get an OGC service (WMS/WFS/WCS) settings
      4.9.2 Update an OGC service (WMS/WFS/WCS) settings
      4.9.3 Enable/Disable an OGC service (WMS/WFS/WCS)
5. 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

Published on CRAN

3. Credits

  1. 2016, Emmanuel Blondel

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: DOI

4. User guide

4.1 How to install geosapi in R

For now, the package can be installed from Github

install.packages("remotes")

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

remotes::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: https://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: https://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: https://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.2.2 Create a Shapefiles Directory dataStore
  ds = GSShapefileDirectoryDataStore$new(dataStore="topp_datastore",
                                description = "topp_datastore description",
                                enabled = TRUE,
                                url = "file:data/shapefiles")
  created <- gsman$createDataStore("topp", ds)

  • 4.5.1.2.3 Create a GeoPackage dataStore
  ds = GSGeoPackageDataStore$new(dataStore="topp_datastore",
                                description = "topp_datastore description",
                                enabled = TRUE,
                                database = "file:data/somefile.gpkg")
  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 Upload features/vector data

The geosapi offers methods to upload vector data to configured datastores. A generic method gsman$uploadData allows to upload any kind of data type supported by GeoServer, by specifying the file extension. To upload data, several parameters have to be specified including: * ws: the workspace in which the datastore is configured * ds: the datastore in which data has to be uploaded * endpoint: choice among file (use a local file content as body), url (use a file URL), or external (path to a file). Important note: So far only file was tested and is supported. * extension: the data file extension * configure: either none (upload only, with no featuretype/layer configured by default), first (upload and configure featuretype/layer over the uploaded vector data) * update: update strategy, either append (upload that will fails in case data was already uploaded), or overwrite (overwrite the already uploaded data if existing) * filename: filename of the data resource to upload * charset: character set of the data resource * `contentType: data content type

To simplify the upload, several data-specific methods were designed targeting specific data file extensions. These methods share the same parameters as above except the extension and contentType that will be pre-set accordin