KiwiFert user guide

Five clicks gets you a full programme: open the app, click your block on the map, choose a plant type, choose a rotation, read the recommendation. Everything after that is refinement — and the refinement is where the value is, because the default answer is a national average dressed up in your soil order.

1Getting it running

On the web, KiwiFert is one of the interactive tools on the KiwiScience site: open it from the sidebar or the home page and there is nothing to install.

To run it from a copy of the site on your own computer, double-click Open KiwiFert.command in the kiwifert folder. It hands over to the site launcher, Open KiwiScience.command, which starts a small local server for the whole site and opens the calculator in your browser. Leave the Terminal window alone while you work; closing it (or pressing Ctrl+C in it) stops the server. It does not start a second server if the site is already being served.

The equivalent from a shell, run from the site folder:

python3 scripts/kiwiscience_server.py 57931

Do not open index.html by double-clicking it. The calculator itself will work, but the map will not. Browsers block a page loaded over file:// from reading data files beside it, and reading one pixel out of a KiwiMap raster needs an HTTP Range request, which file:// has no equivalent of. If you do open it that way, the app says so and lets you enter the site by hand.

The server deliberately serves the whole kiwiscience.com folder, not just kiwifert, because KiwiFert reads KiwiMap's data from ../kiwimap/webapp/. If your folders are arranged differently, open Where KiwiMap is at the foot of the Site tab and set the path there; it is remembered between sessions.

2Pick the block

Click anywhere on New Zealand. KiwiFert reads thirty-three values at that point — soil order and subgroup, pH, cation exchange capacity, carbon, drainage, texture, depth, bypass flow, land use, land cover, ecological district, seven climate variables and fourteen soil geochemistry elements — and fills the Site table beside the map. It takes about a second.

Zoom in before you click. The soil layers are on a 100 m grid, and at national zoom a click can easily land on the wrong side of a soil boundary or in a river bed.

Changing what the map read

Every row of the Site table has a third column you can type into. Type a value and the model uses yours instead; clear the box and it goes back to the map. Anything you have overridden is highlighted, and the Source column changes from KiwiMap to entered, so you can always see which numbers are yours.

The map picker in the top right switches between the Topo50 base map, soil order, soil pH and land use. It changes what is drawn only — a click reads every dataset whatever is on screen.

3Choose the crop and rotation

Two dropdowns, and they do different jobs.

Plant type / land use

51 options, grouped by sector. This sets the annual nutrient requirement, the target pH, the product forms and the liming regime. It is the choice the whole calculation turns on.

Rotation regime

45 options, or none. Choosing a rotation switches the app into rotation mode: the programme becomes the workbook's own application events across every phase of that rotation, and the nutrient budget is computed phase by phase with each phase's own species and yield. Leaving it blank gives annual mode: a product basket solved for one crop for one year.

Rotation mode is the more informative of the two and is what the source workbooks were built for. Annual mode is quicker and is the right choice when you are asking “what does this one crop need this season?”

The rate position slider

Every published rate is a range. The slider decides where in that range to sit: 0 is the low end of every range, 1 the high end, 0.5 the middle. Pull it down for an extensive block, a low yield target or a nitrogen-sensitive catchment; push it up for irrigated high-production ground. It is the fastest way to see how much of the answer is the site and how much is the assumption.

Expected yield

Yield sets the removal side of the budget, not the fertiliser rate. Leave it blank to use the middle of the published range for that crop. The label tells you whether the crop is quoted as dry matter (pasture, forage, forestry) or fresh weight (everything else) — the conversion is automatic, but entering a fresh-weight figure where dry matter is wanted will be out by a factor of five or more.

4Enter a soil test

This is the single biggest improvement you can make to the answer. Without an Olsen P, KiwiFert can only give maintenance phosphorus — it has no way of knowing whether the block needs capital P to reach the target range, and the difference is often larger than everything else in the calculation put together.

Four fields, on the Crop & rotation tab:

Olsen P (mg/L)

Used. Drives the capital phosphorus calculation against the target band for your soil order and land use.

Soil pH (laboratory)

Used. Replaces KiwiMap's modelled pH everywhere in the calculation, including the lime requirement.

QT potassium

Recorded with the scenario but not used to set a rate. The source workbook deliberately does not reproduce the QT K interpretation table, because it belongs to the laboratory that produced the number and differs between laboratories.

Sulphate sulphur (mg/kg)

Recorded but not used to set a rate, for the same reason.

5Read the recommendation

The Recommendation tab is in five parts, top to bottom.

1. Read these first. Regulatory ceilings, agronomic cautions and data gaps. A red box is a limit you would be breaking; an amber box is a decision to make; a blue box is information about the quality of the answer. Nothing here is decoration — if a box says no soil test has been entered, the phosphorus figure above it means less than it looks.
2. Nutrient targets. Published range, the base at your slider position, the site factor, and the target. If you want to know why a factor is what it is, the list underneath says so in words, and names the sheet it came from.
3. Trace elements to check. Elements the soil order is flagged for but this crop's published rate does not cover. These are advice, not a rate, and are not in any total. Test before you add one; boron and selenium in particular have very little margin for a careless second application.
4. Lime. Target band, current pH, the trigger, the arithmetic, and the split. Capital lime is a one-off correction; maintenance lime is annual and includes the acidity the nitrogen programme itself creates.
5. The programme. In rotation mode, every application event with its month, product, rate and the mass of each element it delivers. The × column is how many times an application repeats inside its phase — an annual dressing in an eight-year pasture phase is one row carrying ×8. In annual mode, the solved product basket.

Hover a product name in annual mode to see the form the workbook actually specifies for that crop. The prose is often more useful than the product name — “Triple super, 25–50 mm from the seed” tells you something the analysis does not.

6Read the nutrient budget

Three tables.

Total mass of elements applied per hectare is the headline: sixteen elements, per year and per rotation cycle, with oxide equivalents for the ones fertiliser labels use, and lime kept in its own columns because its calcium dwarfs everything else. This is the table to read if you want to know what you are actually putting on the ground, as opposed to what you thought you were buying.

Nutrient removal is what leaves in the harvest. In rotation mode it is broken out phase by phase, each with its own species and yield.

Nutrient balance is applied minus removed. A positive balance builds soil reserves or is lost; a negative one mines them. Neither is automatically wrong — a capital phosphorus programme is deliberately positive, and a well-supplied Allophanic soil can run a negative phosphorus balance for years. What matters is that the sign is the one you meant.

7Change a parameter

Every coefficient the model uses is on the Parameters tab, with its default, its units, an explanation, and where the default came from. Change one and everything recalculates immediately.

Each parameter names its source. The ones marked KiwiFert are the app's own interpretations — typically a workbook that states something as a word (“potassium reserve: very low”) turned into a number. Those are the ones to argue with. The ones citing a sheet or a regulation are lifted directly and should only be changed if you know the source has changed.

Changed parameters are highlighted, counted at the top of the tab, and are the only ones written to a saved scenario — so a scenario saved today will pick up a corrected default tomorrow while keeping the changes you meant to make. Reset every parameter puts everything back.

8Save and load scenarios

A scenario is the whole state of the calculator in one JSON file: the location, everything KiwiMap read there, everything you typed over the top, the crop, the rotation, the soil test and any changed parameters. Save scenario writes it; Load reads one back.

Two things worth knowing about the format:

• The KiwiMap readings travel with the file. A scenario opened on a machine with no KiwiMap folder still calculates in full; only re-clicking the map needs KiwiMap.
• Only changed parameters are saved. If a default is corrected in a later version of the app, your old scenario picks up the correction rather than freezing the old value — but anything you deliberately changed still travels with the file.

The file also carries a computed block: a snapshot of the answer at the time you saved, so the file makes sense opened in a text editor. It is ignored on load — the numbers are always recalculated from the inputs.

Work in progress is kept in the browser between reloads, so closing the tab by accident does not lose it. That is a convenience, not a filing system: if a scenario matters, save the file.

A scenario written by a newer version of KiwiFert than the one you are running will be refused rather than half-loaded. A scenario naming a crop or rotation that no longer exists in the data will load, drop that selection, and tell you it did.

9Print and share

Print in the header prints every tab, not just the one on screen, with the navigation, the map and the buttons removed. Printing to PDF gives a complete record of the recommendation, the programme, the budget and the site data behind them.

To share the working rather than the output, send the scenario JSON file. It is small, it is readable, and it reproduces the whole calculation.

10Troubleshooting

The map area says KiwiMap is not available

Either the page was opened over file:// (use Open KiwiFert.command), or the server is serving the kiwifert folder alone rather than the whole site (the same launcher fixes it), or the kiwimap folder is somewhere else (set the path under Where KiwiMap is at the foot of the Site tab). The message on screen says which.

A click on the map returns nothing for some layers

Normal near a coast or on non-soil ground. S-map covers about 43 % of the land area and is blank elsewhere; the Fundamental Soil Layers leave towns, lakes, rivers, ice and quarries with no soil attributes at all. Move the click onto the block itself.

The soil order comes back as “Urban area” or “River bed”

You have clicked a map unit that carries no soil. No soil-order adjustment can be made, and the app says so. Click on the paddock.

The lime figure looks enormous

Check the soil order and the pH. An Allophanic or Oxidic soil needs 13–15 t of lime per pH unit against 9–10 on a Pallic one, so the same pH gap costs half as much again; and a modelled pH that is 0.3 units low adds four tonnes. The app flags a figure above the published capital range for that land use. Get a laboratory pH before spending it.

The rotation programme does not match the target table

Expected, and explained in the blue box above the programme. The targets are an annual figure for one land use; the programme is the real event schedule across all the phases of the rotation, including the phases growing something else.

An element is far above its target

Co-delivery. Superphosphate bought for phosphorus brings sulphur and calcium; muriate of potash brings chloride; DAP brings nitrogen. It is real fertiliser and real cost, it appears in the budget, and the way to change it is to change the product.

The page is slow to answer a click

Fourteen geochemistry elements are read as fourteen separate files. On a slow connection that dominates. Everything else lands first.

11Questions

Can I use this to write a fertiliser plan for a real farm?

No. It describes typical practice adjusted for a point on a map; a plan needs soil tests, herbage or leaf tests, a nutrient budget for the block, and the regional plan if the block sits in a sensitive catchment. Use it to understand the arithmetic and to ask better questions of an adviser.

Why is the nitrogen capped at 190?

The Resource Management (National Environmental Standards for Freshwater) Regulations 2020 cap synthetic nitrogen on pastoral land at 190 kg N ha⁻¹ yr⁻¹, applied both to each individual hectare of pasture and to the average across all pastoral land use on the farm. It is a regulatory ceiling, not an agronomic optimum.

Why does a ryegrass/clover pasture still get nitrogen?

Because it is a mixed sward, not a legume stand. The clover fixes 100–200 kg N ha⁻¹ yr⁻¹ and that is already reflected in the published range, which for sheep and beef pasture starts at zero. Pure legume stands — lucerne, white clover, pulses — get none unless you turn the option on.

Where does the geochemistry fit in?

It does not set a rate, ever. Total soil concentration is not plant availability. It is there as supporting evidence when a deficiency is flagged, and to give a sense of the geochemical setting.

Can I add a crop or a product?

Yes — edit the source spreadsheet and re-run scripts/extract.py. Nothing in data/ is hand-edited. See section 15 of How the calculations work.

Does anything leave my machine?

No. There is no backend, no analytics and no external request. Everything runs in the browser against files on your own disk.

Still stuck, or think a number is wrong? The place to look first is How the calculations work, which gives the equation and the source for every figure the app produces.

↑ Back to top