Query API and Web Services

  1. Home
  2. Query API and Web Services
  3. Use Changesets via WFS

Use Changesets via WFS

To automate updates of data accessed via WFS web services, Koordinates supports a WFS changeset service.

WFS changesets allow applications to incrementally update local copies of vector or tabular datasets. When a dataset is updated, instead of grabbing it in its entirety, the application will only grab those bits of the dataset that have been updated.

The WFS changeset will do this on an ongoing basis, which makes it particularly useful for users of datasets that are regularly updated, as it saves repeatedly downloading copies of a particular dataset.

The Koordinates WFS changeset supports both WFS 1.x and WFS 2.x

What are WFS web services?

WFS web services allow users to extract vector and tabular datasets from a Koordinates site. These web services are commonly used for geoprocessing tasks and desktop GIS data access, and enable complex geospatial data to get from one machine to another. Koordinates supports WFS 1.x and WFS 2.x OGC web services.

What is a changeset?

A changeset outlines what has been added, updated or deleted in a particular dataset. Users can use a changeset to update their data, without having to download the entire dataset from scratch.

For example, if there are 50 versions of a large dataset, and the user has downloaded version 39, the changeset will ensure that you get all the changes made in the intervening 11 versions.

Changesets and primary keys

Changesets are only available for layers where the supplier has provided a unique primary key field. If changesets are available for a specific layer, information will be shown on the Web Services tab for the layer.

We suggest you use the same primary key field for your internal copy of the data.

What will the WFS changeset do?

The WFS changeset will:

  1. Request a changeset for a layer for a 24-hour period from the service.
  2. Start a new database transaction in your internal database.
  3. For each record in the response with __change__=DELETE, remove the corresponding record from your internal database using the primary key field value.
  4. For each record in the response with __change__=ADD, insert a record into your internal database.
  5. Commit the database transaction.

All results will be full records in the specified format, with an additional attribute __change__. The value of this attribute specifies whether a record was added (ADD) or deleted (DELETE) in the timeframe specified in your query.

WFS changeset query parameters

Your changeset query parameters will look like so:


Note that this differs from a regular WFS query on Koordinates, as the feature type (layer) identifier is specified as x123-changes (where 123 is the layer number).

Also, an additional viewparams parameter is required, of the form from:;to:. This specifies the range of time to return changes between, defined as (from <= change-time < to). Timestamps are specified in ISO 8601 style via the subset and rules defined in RFC3339. Any timestamp without a specified time zone is interpreted as a UTC time.

For example, a timestamp parameter might be written as: 2pm on August 1 2011 in NZST: 2011-08-01T14:00+1200

If you are regularly querying the service, we strongly recommend that you use a fixed period such as a single month or day (eg. from:2012-02-01;to:2012-02-02) rather than using the current time when your script runs. This will ensure that you get all the changes on your chosen dataset, and avoids needing to save the exact timestamp specified previously and re-supply it to the changeset service with subsequent queries.

Note that all query parameter values must be URL-encoded as per RFC3986.

Output formats

There are several formats available, which you can specify using the outputFormat query parameter.

GML2:  &outputFormat=GML2 (Default for WFS 1.0.0)

GML3: &outputFormat=GML3 (Default for WFS 1.1.0)

JSON: &outputFormat=json

CSV: &outputFormat=csv