Documentation

The what, how, where, ..., and why.

Download (installation)

Download the latest development bild from github://iocast/featureserver or take the latest release.

Dependencies (installation)

The following dependendies are requrired and need to be installed:

  • dxfwrite
  • lxml
  • pyspatialite
  • Cheetah
  • simplejson
  • psycopg2

Virtual Environment (installation)

download the recent version of virtualenv.py from http://pypi.python.org/pypi/virtualenv

curl https://raw.github.com/pypa/virtualenv/master/virtualenv.py -o virtualenv.py

To create a new environment with the name featureserver run:

python virtualenv.py featureserver

To activate the virtual env call:

source featureserver/bin/activate

Now you can install the needed dependencies using the command pip install as follow:

pip install lxml

Mac OS X Mountain Lion (installation)

GEOS and PROJ are required. Use the unix compatibility (OS X) frameworks from http://www.kyngchaos.com/software/frameworks

Layer (configuration)

A layer is a named section in the featureserver.cfg file. Using for a example WFS jargon, a layer is the value of the typename parameter in the HTTP request

featureserver.cgi?typename=pois

Every layer is bracket by [<layer>] and has to be on a sperate line as every key. Keys can vary from datasource to datasource. E.g. SpatialLite does not need to have a dsn in contrast for PostGIS it is mandatory to connect to the database. The following example shows a sample configuration for a SpatialLite datasource.

[sqlite_layer]
type=SpatialLite
file=/home/featureserver/test.sqlite
layer=featureserver // table name
fid=fid // id attribute
attribute_cols=name // additional attributes to be displayed

The follwing sections describes all the possible keys for each supported datasource.

Metadata (configuration)

This is not a realy serive as all the others. This section (have to be called [metadata]) in the configuration file is used to define some meta information for the FeatureServer. The following keys could be used:

KeyValue/Description
default_service (required) Is used if no service or typename is given in the reuqest.
default_exception (optional) Use it to define a service that is able to return a excpetion report. If it is not set, then FeatureServer would try to return the exception report in the format of the requested service. If that is not possible too, it takes the default_service if it is able and WFS otherwise.
error_log (required) Path to the log file.

DBM (BerkleyDB) (configuration)

The DBM datasource uses anydbm combined with pickle to store features in a file on disk. This works on any platform, and works right out of the box.
Info The BerkleyDB datasource is a subclass of the DBM datasource. It uses a BerkleyDB module for storage.

KeyValue/Description
types DBM
title new Title of the layer
abstract new Short description of the layer
file path to the file on disk

Flickr (configuration)

The Flickr datasource loads data from geotagged Flickr photos. Filtering the results can be done by using any of the parameters listed at: http://flickr.com/services/api/flickr.photos.search.html

KeyValue/Description
types Flickr
title new Title of the layer
abstract new Short description of the layer
user_id Flickr user id
tags Comma seperated list of tags that need to be matched according to tag_mode.
tag_mode Mode of matching tags. Either 'any' for an OR combination of tags, or 'all' for an AND combination. Defaults to 'any' if not specified.
... more parameters see Flickr's API

Important By default, this only shows public photos. To grant the datasource access to your non-public photos, you must fetch a 'read' permissions token from the API. You can use the Flickr.py as a command line application to do this:

./FeatureServer/DataSource/Flickr.py
Open the following URL in a browser:
http://flickr.com/services/auth/?api_key=[...]&perms=read&frob=[...]
Press enter when complete. The result of this will be something like:
Your token is:
                        
721576-5d6044
                        
Add the following line to a Flickr data source to complete configuration:
                        
auth_token=721576-5d6044
With this example, the the key/value auth_token=721576-5d6044 need to be added to the Flickr datasource.

GeoAlchemy (configuration)

GeoAlchemy is an extension of SQLAlchemy, the python database toolkit, for spatial databases. GeoAlchemy datasource for FeatureServer allows you to access features stored in one of the supported spatial databases. As the moment GeoAlchemy supports PostGIS, MySQL and Spatialite.

The actual geoalchemy model definition may lie in a separate package. This makes it easy to integrate feature server with other applications/frameworks. A basic GeoAlchemy configuration might look like:

KeyValue/Description
types GeoAlchemy
title new Title of the layer
abstract new Short description of the layer
dburi Connection information to the respective database. E.g. postgres://user:password@dbhost/dbname
model Path to the model definition. E.g. mypackage.mymodule
cls Class name inside the model definition. E.g. MyLayer
fid Attribute name of the feature id.
geometry Attribute name of the geometry data. Default is the_geom

Note Instead of using dburi in the config it is possible to pass the sqlalchemy session to the datasource. Developers using the FeatureServer API may choose to pass the session object instead. GeoAlchemy also supports the use of relations where the geometry column may be in a related table. The config in this would be:

[mylayerexterior]
type=GeoAlchemy
dburi=postgres://user:password@dbhost/dbname
model=mypackage.mymodule
cls=MyLayer
fid=id
geometry=geom # defaults to the_geom
geom_cls=Exterior
geom_rel=exterior

OGR (configuration)

The OGR datasource allows you to take any OGR datasource - such as a shapefile, PostGIS database, GML file, or other formats supported by OGR - and use it as a backend for a FeatureServer layer.

The OGR layer requires a dsn property and a layer property. In many cases, the layer is part of the DSN.

KeyValue/Description
types OGR
title new Title of the layer
abstract new Short description of the layer
dsn (Required) Connnection information to the datasource.
layer (Required) layer (table name) inside the datasource.
attribute_cols A comma seperated list of attributes to be queried on the defined datasource. Default is attribute_cols=*

An example OGR configuration might look like:

[myshape]
type=OGR
dsn=/home/example/myshape.shp
layer=myshape
attribute_cols=name,some_interesting_column #optional; only these columns will be returned.

OSM (configuration)

Allows for requests to hit the OpenStreetMap API to request data. No configuration necessary. Only supports query-by-bounding-box and query-by-id. The latter will only search for 'ways', not nodes or relations. Relations are not handled at all.

It is possible to add an osmxapi=yes option. This will use the OSM Extended API instead of the main API. This API may be several hours out of date, but it does allow attribute queries: see http://wiki.openstreetmap.org/index.php/Osmxapi . It does not support ID queries, and if one is sent, it will instead be redirected to the main API.

KeyValue/Description
types OSM
title new Title of the layer
abstract new Short description of the layer
osmxapi [yes|no] uses OSM Extended API and the main API respectively.

PostGIS (configuration)

The PostGIS datasource implements a direct connection to PostGIS. This datasource requires a dsn parameter and a layer parameter. It also accepts a variety of optional parameters, some of which you may need to override the default value of, depending on your schema.

KeyValue/Description
types PostGIS
title new Title of the layer
abstract new Short description of the layer
dsn (required) connection information to the database.
layer (required) Name of the datasource's layer aka. table name.
fid Attribute name of the feature's id. Default is fid=gid
geometry Attribute name that holds the geometry information. Default is geometry=the_geom
srid Spatial Refernece System Identifier of the data stored in the datasource. Default is srid=4326
srid_out new Spatial Refernece System Identifier of the data given back to the client. Default is srid=4326
attribute_cols A comma seperated list of attributes to be queried on the defined datasource. Default is attribute_cols=*. If hstore=true then hstore syntax is allowed e.g.
attribute_cols=name, gtype as "geometry_type", hstore(tags)->'operator' as "operator", hstore(tags)->'highway' as "highway"
encoding Default is encoding=utf-8
order Order data by a attribute.
hstore new Defines if datasource uses hstore. Possible values: [true|false]
version new Version attribute. If hstore=true then hstore syntax is allowed e.g.
version=hstore(tags)->'version'
ele new Elevation attribute. If hstore=true then hstore syntax is allowed e.g.
ele=hstore(tags)->'ele'
bbox new Max bounding box of the data in the format min_x min_y max_x max_y
geometry_type new Comma seperated list of geometry types Point, Line and/or Polygon

SpatialLite new (configuration)

KeyValue/Description
types SpatialLite
title Title of the layer
abstract Short description of the layer
fid Attribute name of the feature's id. Default is fid=gid
geometry Attribute name that holds the geometry information. Default is geometry=the_geom
srid Spatial Refernece System Identifier of the data stored in the datasource. Default is srid=4326
srid_out Spatial Refernece System Identifier of the data given back to the client. Default is srid=4326
attribute_cols A comma seperated list of attributes to be queried on the defined datasource. Default is attribute_cols=*
version Version attribute.
ele Elevation attribute.
bbox Max bounding box of the data in the format min_x min_y max_x max_y
geometry_type Comma seperated list of geometry types Point, Line and/or Polygon

SQLite (configuration)

A simple SQLite datasource that can be used on any website with Python support for SQLite. Creates 2 tables for each layer: one for the features, and one for any attributes/properties pertaining to those features. The features table can be used as input to OGR.

KeyValue/Description
types SQLite
title new Title of the layer
abstract new Short description of the layer
file (required) path including file name
layer Name of table. Defaults to layer name
[lines]
type=SQLite
goes to layer=lines

Twitter (configuration)

Powered by Twittervision, the twitter datasource lets you use twittervision's API to display the current location of a user.

Very simplistic, doesn't do much:

KeyValue/Description
types Twitter
title new Title of the layer
abstract new Short description of the layer
username (required) name of the Twitter user

WFS (configuration)

The WFS datasource implements read-only access to WFS servers.

KeyValue/Description
types WFS
title new Title of the layer
abstract new Short description of the layer
url (required) url to the WFS service.
typename (required) typename/layer of of the requested WFS service