pg_featureserv
A lightweight RESTful geospatial feature server for PostGIS, written in Go.
It supports the OGC API - Features REST API standard.
See also our companion project pg_tileserv
.
Features
- Implements the OGC API - Features standard.
- Standard query parameters:
limit
, bbox
, bbox-crs
, property filtering, sortby
, crs
- Query parameters
filter
and filter-crs
allow CQL filtering, with spatial support
- Extended query parameters:
offset
, properties
, transform
, precision
, groupby
- Data responses are formatted in JSON and GeoJSON
- Provides a simple HTML user interface, with web maps to view spatial data
- Uses the power of PostgreSQL to reduce the amount of code
and to make data definition easy and familiar.
- Feature collections are defined by database objects (tables and views)
- Filters are executed in the database, and use indexes where defined
- Uses PostGIS to provide geospatial functionality:
- Spatial filtering
- Transforming geometry data into the output coordinate system
- Marshalling feature data into GeoJSON
- Full-featured HTTP support
- CORS support with configurable Allowed Origins
- GZIP response encoding
- HTTP and HTTPS support
For a full list of software capabilities see FEATURES.
Documentation
Relevant Standards
Download
Builds of the latest code:
Build from Source
pg_featureserv
is developed under Go 1.13. It may also work with earlier versions.
In the following, replace version <VERSION>
with the pg_featureserv
version are building against.
Without a Go environment
Without go
installed, you can build pg_featureserv
in a docker image:
In Go environment
-
Download or clone this repository into $GOPATH/src/github.com/CrunchyData/pg_featureserv
-
To build the executable, run the following commands:
cd $GOPATH/src/github.com/CrunchyData/pg_featureserv/
go build
-
This creates a pg_featureserv
executable in the application directory
-
(Optional) Run the unit tests using go test
Docker image of pg_featureserv
Build the image
make APPVERSION=<VERSION> clean docker
Run the image
To run using an image built above:
docker run --rm -dt -e DATABASE_URL=postgres://user:pass@host/dbname -p 9000:9000 pramsey/pg_featureserv:<VERSION>
The configuration file is automatically read from the following locations, if it exists:
- In the system configuration directory, at
/etc/pg_featureserv.toml
- Relative to the directory from which the program is run,
./config/pg_featureserv.toml
- In a root volume at
/config/pg_featureserv.toml
To specify a configuration file directly use the --config
commandline parameter.
In this case configuration files in other locations are ignored.
Configuration Using Environment Variables
To set the database connection the environment variable DATABASE_URL
can be used with a
Postgres connection string:
export DATABASE_URL="host=localhost user=postgres"
Other parameters in the configuration file can be over-ridden in the environment.
Prepend the upper-cased parameter name with PGFS_section_
to set the value.
For example, to change the HTTP port and service title:
export PGFS_SERVER_HTTPPORT=8889
export PGFS_METADATA_TITLE="My PGFS"
SSL
For SSL support, a server private key and an authority certificate are needed.
For testing purposes you can generate a self-signed key/cert pair using openssl
:
openssl req -nodes -new -x509 -keyout server.key -out server.crt
These are set in the configuration file:
TlsServerCertificateFile = "/path/server.crt"
TlsServerPrivateKeyFile = "/path/server.key"
Run the service
- Change to the application directory:
cd $GOPATH/src/github.com/CrunchyData/pg_featureserv
- Start the server:
- Open the service home page in a browser:
http:/localhost:9000/home.html
Command-line options
-?
- show command usage
--config file.toml
- specify configuration file to use
--debug
- set logging level to TRACE (can also be set in config file)
--devel
- run in development mode (e.g. HTML templates reloaded every query)
--test
- run in test mode, with an internal catalog of tables and data
--version
- display the version number
Troubleshooting
To get detailed information about service operation
run with the --debug
commandline parameter.
./pg_featureserv --debug
Debugging can also be enabled via the configuration file (Server.Debug=true
),
or in the environment:
export PGFS_SERVER_DEBUG=true
Requests Overview
Features are identified by a collection name and feature id pair.
The default response is in JSON/GeoJSON format.
Append .html
to the request path to see the UI page for the resource.
In a web browser, to request a JSON response append .json
to the path (which overrides the browser Accept
header).
The example requests assume that the service is running locally and configured
to listen on port 9000.
See API Summary for a summary of the web service API.