Change definition and actions

The Changeset API makes a feature by feature comparison between dataset versions returning data for any feature that is new, updated or deleted.

On this page

The Changeset API is very strict in its definition of change. Any alteration to the data, no matter how small, constitutes a change and will be included in the changeset.

For example, in the case of plain text data, any change in white space, case, or special characters are part of the changeset. In the case of geometry data any change in coordinate sequence or value will be included. Schema changes will also trigger a changeset.

Unique feature identifier

LDS tracks the unique primary key identifier for the dataset and matches and compares rows or features using this identifier. This means it can identify information that has been added, modified or deleted. The primary key is identified under the Technical Details column of the About tab.

LDS screen with primary key highlighted

Action types

Any change in data will be defined as an INSERT, DELETE or UPDATE. This is recorded in the “__change__” column of the changeset table.

Each row in the changeset dataset is a separate action, and there is only ever one action for any given feature in a changeset. This is true even if a series of actions have happened for that single feature as the Changeset API processes all actions server-side.

For example, if a feature has been inserted and updated several times within the timeframe of the changeset, the changeset will only have an insert record and it will have incorporated the updates. If a feature was updated and then deleted, it will only have a delete action in the changeset.

Action type Description
INSERT Features are marked as an INSERT if the feature identifier exists in the new version of the dataset but not in the existing version.
DELETE Features are marked as a DELETE if the feature identifier is in the existing data but not in the new data.
UPDATE Features are marked as an UPDATE if the feature identifier exists in both the new and old data, but any of the feature attributes or geometries are different. While the changeset will tell you that a feature has been affected by an UPDATE, it will not tell you the reason for change (that is, it will not tell you what specific attribute has changed).

Note that additional filter parameters applied in the changeset request may impact on the returned changeset actions. See our documentation on changeset filtering for more information.

Changeset examples

Simple example of action types

The example below has a schema of first and last names, along with a unique identifier for each person. In revision A of the table there is John, Jane and Roger. In revision B, Mary has been added, Jane has married John, and Roger has been deleted.

Diagram of changeset revisions

The end result is a changeset table that has the same schema as revisions A and B with the addition of a “__change__” column, indicating the type of change that occurred to the row between revisions. In this case, Roger Jones has been deleted, Jane has been updated to have a last name of 'Smith' and Mary Pond has been added.

Changeset example using LINZ data

These examples show what a changeset result using the LDS Changeset API may look like. 

This example shows records from a changeset table for the NZ Parcel Statutory Actions List. In this example the feature identifier is the ‘id’ attribute.

FID

__change__

id

par_id

status

action

statutory_action

table-51565-changeset.281745

UPDATE

23392

3505013

Historic

Create

Secondary School New Zealand Gazette 1981 p 1975

table-51565-changeset.227552

DELETE

249105

3105056

Current

Referenced

Road New Zealand Gazette 2013 p 956 Pursuant to Sec 5 of the Land Transport Management Act 2003, forms part of State Highway 1 and vests in the Crown.

table-51565-changeset.281362

INSERT

300405

3525650

Historic

Extinguished

New Zealand Gazette 2017 ln 3735