django-hydrosheds 1.0.1

django-hydrosheds is a Django application for handling hydrosheds data.

A reusable Django application that provides ready-to-use GeoDjango models, REST API endpoints, serializers, and admin integration for the HydroSHEDS family of datasets:

• HydroLAKES — global lake and reservoir polygons

• HydroRIVERS — global river network line segments

• HydroBASINS — global watershed / sub-basin boundaries

• HydroWASTE — global wastewater treatment plant locations

Table of Contents

• Requirements

• Installation

• Quick Start

• Models

• REST API

• Management Command ‘geodata’

• Configuration

• License

• Links

Requirements

• Python ≥ 3.12

• Django ≥ 6.0

Runtime dependencies (installed automatically):

• django-filter ≥ 25

• djangorestframework ≥ 3.16

Runtime dependencies available for spatialite:

• libspatialite-dev (Debian/Ubuntu)

• spatialite-devel (Fedora/CentOS)

• libspatialite (macOS)

• libgdal-dev (Debian/Ubuntu)

• libgeos-dev (Debian/Ubuntu)

• libproj-dev (Debian/Ubuntu)

• libsqlite3-mod-spatialite (Debian/Ubuntu)

• libopenblas-dev (Debian/Ubuntu)

Installation

Install from PyPI:

pip install django-hydrosheds

Or via uv:

uv add django-hydrosheds

Quick Start

1. Add hydrosheds and its dependencies to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "django.contrib.gis",
    "django_filters",
    "rest_framework",
    "hydrosheds",
]

2. Include the URL configuration in your project’s urls.py:

from django.urls import path, include

urlpatterns = [
    # ...
    path("api/", include("hydrosheds.urls")),
]

3. Run migrations:

python manage.py migrate

Models

All models live under hydrosheds.db and are backed by abstract base classes defined in hydrosheds.db.core. Each field carries descriptive help_text derived from the official HydroSHEDS technical documentation.

Concrete Model	Abstract Base (core)	Geometry
HydroLake	HydroLakePoint	PointField
HydroRiver	HydroRiverLine	LineStringField
HydroBasin	HydroBasinPolygon	MultiPolygon
HydroWaste	HydroWastePoint	PointField

All geometry fields use SRID 4326 (WGS 84).

REST API

The package ships with ModelViewSet views registered through a DefaultRouter. Each endpoint supports filtering, search, and ordering out of the box via django-filter.

Endpoint	ViewSet
/HydroLakePoint	HydroLakePointViewSet
/HydroRiverLine	HydroRiverLineViewSet
/HydroWastePoint	HydroWastePointViewSet
/HydroBasinPolygon	HydroBasinViewSet

Permissions default to IsAuthenticatedOrReadOnly.

Management Command ‘geodata’

Download shapefiles from https://www.hydrosheds.org/products

Use the bundled management command to import shapefiles:

# load data to database table
python manage.py geodata -f path/to/HydroRIVERS_v10.shp -n HydroRiver --load

# print model classes and mappings
python manage.py geodata -f path/to/HydroRIVERS_v10.shp -n HydroRiver

# print help
python manage.py geodata -h

Configuration

The following Django settings are available:

HYDROSHEDS_DISABLE_MODELS

Set to True to prevent model registration (useful in projects that only need the abstract base classes).

HYDROSHEDS_DISABLE_ADMIN

Set to True to skip automatic admin site registration.

License

GPL-3.0 — see LICENSE for details.

Links

• Repository: https://github.com/groupeffect/django-hydrosheds

• Changelog: https://github.com/groupeffect/django-hydrosheds/blob/main/CHANGELOG.rst

• HydroSHEDS: https://www.hydrosheds.org/products