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
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-hydroshedsOr via uv:
uv add django-hydroshedsQuick Start
Add hydrosheds and its dependencies to INSTALLED_APPS:
INSTALLED_APPS = [
# ...
"django.contrib.gis",
"django_filters",
"rest_framework",
"hydrosheds",
]Include the URL configuration in your project’s urls.py:
from django.urls import path, include
urlpatterns = [
# ...
path("api/", include("hydrosheds.urls")),
]Run migrations:
python manage.py migrateModels
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 -hConfiguration
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
1 maintainer
Metadata
1 maintainer
Release files for django-hydrosheds 1.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| django_hydrosheds-1.0.2.tar.gz | 23.3 kB | With provenance | Details for django_hydrosheds-1.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| django_hydrosheds-1.0.2-py3-none-any.whl | Python 3 | none | any | Details for django_hydrosheds-1.0.2-py3-none-any.whl |
Total release size: 47.9 kB
Release files / django_hydrosheds-1.0.2.tar.gz
| Download URL | django_hydrosheds-1.0.2.tar.gz |
|---|---|
| Size | 23.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
38d34c547fdd15145082f80a5c157a0522e519f5f77bf4ea212636d5a782f354
|
|
BLAKE2b-256 checksum How to use checksums |
d3f2b5dcb1d5ff04a6efb402244151faa259881e9110265b90b741f900d3d258
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 25, 2026.
Transparency logRelease files / django_hydrosheds-1.0.2-py3-none-any.whl
| Download URL | django_hydrosheds-1.0.2-py3-none-any.whl |
|---|---|
| Size | 24.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c74bc815a7866d14bac3b7e6473c0e7de985ac196eb1c9cfd26b92297094cf00
|
|
BLAKE2b-256 checksum How to use checksums |
ff32c01367ba4898c5a3fc3928cc67be6a2c6387e5065c01d7f8a9abcf66054b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 25, 2026.
Transparency logSecurity for django-hydrosheds 1.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for django_hydrosheds-1.0.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 25, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
