The Changeset API makes a feature by feature comparison between dataset versions returning data for any feature that is new, updated or deleted.
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 knows what information is added, modified or deleted by tracking the unique primary key identifier for the dataset and matches and compares rows or features using this identifier. The primary key is identified under the Technical Details column of the About tab.
Any change in data will be defined as either an INSERT, DELETE or UPDATE. This is recorded in the “__change__” column of the changeset table.
Each row in the changeset dataset will be separate action and there will only ever be one action for any given feature in a changeset – 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 one or more times within the timeframe of the changeset, the changeset will only have an insert record but it will have incorporated the updates. Likewise if a feature has been updated and deleted, it will only have a delete action in the changeset.
|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, i.e. what specific attribute has changed.|
Note: Additional filter parameters applied in the changeset request may impact on the returned changeset actions. See our documentation on changeset filtering for more information.
Simple example of action types
In the simple example below we have a persons table which 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.
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 an actual 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.
Secondary School New Zealand Gazette 1981 p 1975
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.
New Zealand Gazette 2017 ln 3735