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
.
- Implements the OGC API - Features standard.
- Standard query parameters:
limit
,bbox
,bbox-crs
, property filtering,sortby
,crs
- Query parameters
filter
andfilter-crs
allow CQL filtering, with spatial support - Extended query parameters:
offset
,properties
,transform
,precision
,groupby
- Standard query parameters:
- 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.
- User Guide
- FEATURES - full list of software capabilities
- API - summary of the web service API
- OGC API - Features - Part 1: Core
- OGC API - Features - Part 2: Coordinate Reference Systems by Reference
- DRAFT OGC API - Features - Part 3: Filtering
- DRAFT Common Query Language (CQL2)
- GeoJSON
Builds of the latest code:
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 go
installed, you can build pg_featureserv
in a docker image:
- Download or clone this repository into
$GOPATH/src/github.com/CrunchyData/pg_featureserv
- Run the following command in
pg_featureserv/
:make APPVERSION=<VERSION> clean build-in-docker
-
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
make APPVERSION=<VERSION> clean docker
To run using an image built above:
docker run --rm -dt -e DATABASE_URL=postgres:https://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.
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"
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"
- Change to the application directory:
cd $GOPATH/src/github.com/CrunchyData/pg_featureserv
- Start the server:
./pg_featureserv
- Open the service home page in a browser:
http:/localhost:9000/home.html
-?
- 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
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
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.
- Landing page (HTML or JSON): https://localhost:9000/
- Landing page (HTML): https://localhost:9000/index,html
- Landing page (JSON): https://localhost:9000/index.json
- OpenAPI definition: https://localhost:9000/api
- OpenAPI test UI: https://localhost:9000/api.html
- Conformance: https://localhost:9000/conformance
- Collections: https://localhost:9000/collections
- Collections UI: https://localhost:9000/collections.html
- Feature collection metadata: https://localhost:9000/collections/{name}
- Feature collection UI: https://localhost:9000/collections/{name}.html
- Features from a single feature collection: https://localhost:9000/collections/{name}/items
- Features from a single feature collection (Map UI): https://localhost:9000/collections/{name}/items.html
- Single feature from a feature collection: https://localhost:9000/collections/{name}/items/{featureid}
- Functions (JSON): https://localhost:9000/functions
- Functions UI: https://localhost:9000/functions.html
- Function metadata: https://localhost:9000/functions/{name}
- Function UI: https://localhost:9000/functions/{name}.html
- Features from a function (JSON): https://localhost:9000/functions/{name}/items
- Features from a function (Map UI): https://localhost:9000/functions/{name}/items.html
See API Summary for a summary of the web service API.