zid-harmonie v2.2.1

harmonie :seedling:

harmonie is a software package that harmonizes farm subsidy application files of all German federal states. It takes the various xml, gml, shp, and dbf files issued by the federal farm subsidy application softwares, and converts them into WGS84 projected GeoJSON geometries suitable for any web mapping service.

With harmonie, you can outsource parsing of the different direct payment application files, so you can rely on a given input data structure.

harmonie

• ✅ works in the browser/Node.js
• ✅ adheres to the agroJSON specification
• ✅ is open source (MIT license)

Converting the geometries (fields) contained in the application files is supported for all federal states in Germany. For most federal states, additional information as the primary crop cultivated on a field, as well as the fieldblock number (FLIK) are obtained as well.

The following overview table displays the current state of the project:

✅ Federal states fully supported by 'harmonie': Plot geometries, including crop cultivation code and FLIK are obtained.
☑️ Federal states partially supported by 'harmonie': Only plot geometries are obtained.

Installation

Browser

<script src='https://cdn.jsdelivr.net/npm/zid-harmonie@2.1.0/dist/harmonie.min.js'></script>

Or grab a release from the relases tab. Loading the minified file via script tag exposes the global function harmonie.

Internet Explorer compatibility: Note that this package makes use of modern ES6 language features which are not compatible with Internet Explorer (also not by polyfilling). In order to support Internet Explorer directly, you may transpile the code (e.g. using @babel). Alternatively, you may use the plugin on the server side, or use our (upcoming) API.

Node.js / build tools

npm install zid-harmonie

The module exports a single function.

const harmonie = require('zid-harmonie')
// or using ES6 import
import harmonie from 'zid-harmonie'

Demonstration

Check out the following Observable notebook demonstrating the use of the library with a minimal user interface.

https://observablehq.com/@chrispahm/harmonizing-common-agricultural-policy-cap-farm-applicat

Usage

The function takes a single argument (object), returning a Promise.

const data = harmonie({
  state: 'DE-NW', // Required. The federal state (ISO 3166-2 code) that issued the ZID/IACS files
  xml: '<?xml version="1.0" encoding="UTF-8"?><nn>...</nn>', // The input data. Please see table below for required input data files for each federal state, and the required encoding.
  gml: '<?xml version="1.0" encoding="UTF-8"?><wfs>...</wfs>'  
}).then(data => {
  console.log(data)
  // data is an array of "part of field" (DE: 'Teilschläge') objects
}).catch(error => {
  // handle errors
})

API

harmonie(query)

Returns an array of objects containing individual parts of fields (German: Teilschläge). Properties adhere to the naming conventions defined by agroJSON

• query \<object>, required
  • state \<string, ISO 3166-2> required
  • xml \<string, UTF-8> may be required, depending on state
  • gml \<string, UTF-8>
  • shp \<blob>
  • dbf \<blob>
  • prj \<string, UTF-8> optional when passing shapefiles

Sample return value:

[{
  id: 'harmonie_runningIndex_FieldBlockNumber', // e.g. 'harmonie_36_DEBBLI0261009129'
  referenceDate: 2020,
  NameOfField: 'Hinterm Hof',
  NumberOfField: 0,
  Area: 1.1,
  FieldBlockNumber: 'DENW...',
  PartOfField: 0,
  SpatialData: {
    // a GeoJSON feature
  },
  Cultivation: {
    PrimaryCrop: {
      CropSpeciesCode: 415,
      Name: 'Wiesen'
    }
  }
}]

The following table displays the required properties for a query depending on the federal state:

Specifics for certain federal states

DE-HE: Hessen

According to the test data received from Hessen, the shape file and accompanying database does not contain information about the reference date of the files. Therefore, please expect the referenceDate to be undefined for this federal state.

DE-TH: Thüringen

According to the test data received from Thüringen, the shape file and accompanying database does not contain information about the crop cultivation for a particular field. Therefore, expect the Cultivation property to be empty.

Contribution

Contribution is highly appreciated 👍!
Please open an issue in case of questions / bug reports or a pull request if you implemented a new feature / bug fix.
In the latter case, please make sure to run npm test (and adapt test/test.js to your changes) and / or update the README 🙂

License

MIT @Christoph Pahmeyer

This software is crafted with :heart: at the University of Bonn - EMAS Group