Water Restrictions API Image

Water Restrictions API

A public .NET Web API that provides current water restriction data across New Zealand.

View the docs or API reference

The Water Restrictions API gives public access to water restriction data across New Zealand. It was built to make this information more accessible — particularly for developers who may want to integrate or visualize it.

It has been a long-running hobby project of mine. It began as a way to improve my .NET and C# skills, which is what I primarily use at work. Over time, it’s gone through a few iterations as I picked up new techniques and ideas — and it’s now in a place I’m really happy with.

Implementation ⚙️

Tech stack This project uses my standard platform setup.

Backend:

  • .NET - Web API framework
  • AWS Cognito - Handles authentication and authorization for the API

Infrastructure:

Entities and relationships

The Water Restrictions API is the gatekeeper for all water restriction data. For some context on the content of this page, here are the main entities and their relationships:

  • Organisations are responsible for setting water restrictions for one or more areas. Typically, this is a local council or water entity.
  • Areas are geographical locations, such as a region, city or town, where water restrictions can apply.
  • Schemes are defined sets of water restriction stages. They can apply to one or more areas.
  • Stages represent levels of water restrictions, typically increasing in severity (eg. Level 1, Level 2, etc.).

API Overview 📡

The API provides endpoints for retrieving current water restriction data across New Zealand. While it supports a number of operations, here’s a simple example that shows how to get the current restrictions for a specific area.

To fetch the current restriction status for an area, a GET request can be made to:

GET https://api.waterrestrictions.nz/v1/organisations/{organisationId}/areas/{areaId}

For example, to get the current restriction status for Upper Hutt, which is managed by Wellington Water, the following request can be made:

GET https://api.waterrestrictions.nz/v1/organisations/3f0412e0-7f15-41d9-adf0-6fc0e3985b7d/areas/73dac0b7-a246-4298-aa6f-d80cf23e93c2

This returns information about the area, including the current water restriction stage, if one’s in place:

{
  "id": "73dac0b7-a246-4298-aa6f-d80cf23e93c2",
  "name": "Upper Hutt",
  "scheme": {
    "id": "b3e4bf6d-c613-4ba6-bf4a-ff9e3bea15d4",
    "name": "Greater Wellington Region"
  },
  "currentStage": {
    "id": "5a3f7a40-fd8c-45ac-86c6-e17d5725e4a1",
    "severity": 1,
    "name": "Level 1",
    "description": "Outdoor residential water restrictions start at Level 1.\n\nIf you live in an even numbered house, you can use sprinklers or irrigation systems only on even numbered days between 6-8am and 7-9pm. If you live in an odd numbered house, the same rules apply for odd numbered days.\n\nYou can use handheld watering devices any time, on any day, so long as you don’t leave them unattended."
  }
}

For a full list of endpoints and detailed reference documentation, take a look at the API reference.

Future Plans 🚀

Now that the API is in a stable state, I have a few other features planned. The ones below are the most exciting to me, but there are many more ideas I have for the API which can be found on the docs site.

Geospatial Data 🌍

Adding geospatial data querying would allow developers to search areas based on their geographical location. This would enable more advanced applications, like visualizing water restrictions on maps, integrating with location-based services, or automation of water usage based on location.

I’d also like to use this data to create a website for the general public, with a map showing current restrictions across New Zealand. This would provide an easy way for people to see current restrictions in their area.

Notifications System 🔔

Eventually I’d like to add a way for users to subscribe to notifications about changes in water restrictions in their area. This would likely be by email, and would help keep people informed about any changes that might affect them.

Home Automation Integrations 🏠

One of the original motivators for the API was to integrate with home automation systems, particularly Home Assistant, allowing users to automate their water usage based on current restriction data. This could include features like adjusting irrigation schedules or sending alerts when restrictions change.

I’ve been an avid Home Assistant user for quite a few years, and thought this would be a great opportunity to learn how to build an integration or plugin with it.

Data Management 🌉

For the general public, the API is a read-only interface for water restriction data.

Behind the scenes, I manage the data myself. In the early stages, I did this by sending requests directly to the API. This was a stopgap solution while I built Bridge, a web application that makes it easier to visualise and manage the data. It also provides a way for me to interact with the API from a user’s perspective.

Reflections 💭

This project has been a long-term hobby and learning tool for me. While I don’t expect it to get a huge amount of traffic, it’s helped me grow immensely in .NET and C#. I plan to keep improving it over time — both for my own learning and in the hope it might be useful to others too.