WFS output formats

WFS returns features and feature information in a number of formats. The syntax for specifying an output format is:

outputFormat=<format>

where <format> is one of the following options:

Format

Syntax

Notes

GML2

outputFormat=GML2

Default option for WFS 1.0.0

GML3

outputFormat=GML3

Default option for WFS 1.1.0 and 2.0.0

Shapefile

outputFormat=shape-zip

ZIP archive will be generated containing the shapefile (see Shapefile output below).

JSON

outputFormat=application/json

Returns a GeoJSON or a JSON output. Note outputFormat=json is only supported for getFeature (for backward compatibility).

JSONP

outputFormat=text/javascript

Returns a JSONP in the form: parseResponse(...json...). See WMS vendor parameters to change the callback name. Note that this format is disabled by default (See Global variables affecting WMS).

CSV

outputFormat=csv

Returns a CSV (comma-separated values) file

Note

Some additional output formats (such as Excel) are available with the use of an extension. The full list of output formats supported by a particular GeoServer instance can be found by performing a WFS GetCapabilities request.

GeoServer provides the format_options vendor-specific parameter to specify parameters that are specific to each format. The syntax is:

format_options=param1:value1;param2:value2;...

Shapefile output

The shapefile format has a number of limitations that would prevent turning data sources into an equivalent shapefile. In order to abide with such limitations the shape-zip output format will automatically apply some transformations on the source data, and eventually split the single collection into multiple shapefiles. In particular, the shape-zip format will:

  • Reduce attribute names to the DBF accepted length, making sure there are not conflicts (counters being added at the end of the attribute name to handle this).

  • Fan out multiple geometry type into parallel shapefiles, named after the original feature type, plus the geometry type as a suffix.

  • Fan out multiple shapefiles in case the maximum size is reached

The default max size for both .shp and .dbf file is 2GB, it’s possible to modify those limits by setting the GS_SHP_MAX_SIZE and GS_DBF_MAX_SIZE system variables to a different value (as a byte count, the default value being 2147483647).

Shapefile output format_options:

  • format_option=filename:<zipfile>: if a file name is provided, the name is used as the output file name. For example, format_options=filename:roads.zip.

Shapefile filename customization

If a file name is not specified, the output file name is inferred from the requested feature type name. The shapefile output format output can be customized by preparing a Freemarker template which will configure the file name of the archive (ZIP file) and the files it contains. The default template is:

zip=${typename}
shp=${typename}${geometryName}${geometryType}
txt=wfsrequest

The zip property is the name of the archive, the shp property is the name of the shapefile for a given feature type, and txt is the dump of the actual WFS request.

The properties available in the template are:

  • typename—Feature type name (for the zip property this will be the first feature type if the request contains many feature types)

  • geometryName—Name of the geometry attribute. Used only if the original feature type has more than one geometry attribute.

  • geometryType—Type of geometry contained in the shapefile. This is only used if the output geometry type is generic and the various geometries are stored in one shapefile per type.

  • workspace—Workspace of the feature type

  • timestamp—Date object with the request timestamp

  • iso_timestamp—String (ISO timestamp of the request at GMT) in yyyyMMdd_HHmmss format

JSON and JSONP output

The JSON output format (and JSONP if enabled) return feature content as a GeoJSON document. Here is an example of a simple GeoJSON file;

{  "type": "Feature",
   "geometry": {
      "type": "Point",
      "coordinates": [125.6, 10.1]
   },
   "properties": {
      "name": "Dinagat Islands"
   }
}

The output properties can include the use of lists and maps:

{
  "type": "Feature",
  "id": "example.3",
  "geometry": {
    "type": "POINT",
    "coordinates": [ -75.70742, 38.557476 ],
  },
  "geometry_name": "geom",
  "properties": {
    "CONDITION": "Orange",
    "RANGE": {"min":"37","max":"93"}
  }
}

JSON output format_options:

  • format_options=id_policy:<attribute name>=<attribute|true|false> is used to determine if the id values are included in the output.

    Use format_options=id_policy:reference_no for feature id generation using the reference_no attribute, or format_options=id_policy:reference_no=true for default feature id generation, or format_options=id_policy:reference_no=false to suppress feature id output.

    If id_policy is not specified the geotools default feature id generation is used.

  • format_options=callback:<parseResponse> applies only to the JSONP output format. See WMS vendor parameters to change the callback name. Note that this format is disabled by default (See Global variables affecting WMS).

  • format_option=filename:<file>: if a file name is provided, the name is used as the output file name. The extension json is optional, for example format_options=filename:export or format_options=features.json

JSON output system properties:

  • json.maxDepth=<max_value> is used to determine the max number of allowed JSON nested objects on encoding phase. By default the value is 100.

CSV output

A Default CSV file uses a comma to separate values. Each line of the file is a data record. Each record consists of one or more fields, separated by commas. The separator can be changed using format_options as specified below.

csv file output format_options:

  • format_option=filename:<file>: if a file name is provided, the name is used as the output file name. For example, format_options=filename:roads.csv.

  • format_option=csvseparator:<csvseparator> (default is `,` ): if a separator is provided, it is used to separate values in output csv file. For example, format_options=csvseparator:- is used to get dash separated file.

Some special characters need to be handled using keywords as below:

  • space separated: format_options=csvseparator:space

  • tab separated: format_options=csvseparator:tab

  • semicolon separated: format_options=csvseparator:semicolon