---

name: spatial-filtering description: "Apply django-rest-framework-gis spatial filter backends, geometry filter sets, tile and bbox query parameters, distance predicates, and distance ordering safely in DRF views." disable-model-invocation: true metadata: disco-role: operating license: MIT

Spatial filtering

Use this skill when a DRF endpoint must filter or order spatial model rows from URL query parameters. The public filter classes are exposed from rest_framework_gis.filters (and GeoFilterSet is also re-exported by rest_framework_gis.filterset). Start with references/api-reference.md for exact parameters, defaults, view attributes, and schema declarations; use references/workflows.md for view and filter-set recipes; use references/troubleshooting.md for malformed input and spatial-backend failures.

Route the request

• Use InBBoxFilter for in_bbox=min_lon,min_lat,max_lon,max_lat. It uses contained unless the view opts into bboverlaps with bbox_filter_include_overlapping = True.
• Use TMSTileFilter for tile=Z/X/Y. It converts a TMS tile whose Y origin is the upper left into the same bbox predicate as InBBoxFilter.
• Use GeometryFilter with GeoFilterSet and DjangoFilterBackend for django-filter geometry lookups such as contains, contains_properly, or within.
• Use DistanceToPointFilter for point=x,y and optional dist; configure distance_filter_field and decide explicitly whether the input distance is database units or metres.
• Use DistanceToPointOrderingFilter for nearest/farthest ordering with point=x,y, distance_ordering_filter_field, and optional order=desc. It uses a point with SRID 4326 and GeometryDistance; it is not a substitute for the dwithin filter.

Operating sequence

1. Confirm the queryset field is a GeoDjango geometry field and identify its SRID and database units.
2. Add the selected backend to the view's filter_backends and set the matching field attribute. If the attribute is absent or false, that backend intentionally returns the queryset unchanged.
3. Treat query coordinates as x,y = longitude/easting then latitude/northing. Treat bbox coordinates as west/south/east/north.
4. Let malformed bbox, tile, point, and distance values surface as DRF ParseError responses; do not silently coerce invalid input.
5. Test the ORM predicate against the actual spatial database. GEOS parsing/import smoke tests do not prove that contained, bboverlaps, dwithin, or GeometryDistance execute on the production database.

Minimal contracts

from rest_framework import generics
from rest_framework_gis.filters import InBBoxFilter

class PlaceList(generics.ListAPIView):
    queryset = Place.objects.all()
    serializer_class = PlaceSerializer
    bbox_filter_field = "geometry"
    filter_backends = (InBBoxFilter,)

from rest_framework_gis.filters import DistanceToPointFilter

class NearbyPlaceList(generics.ListAPIView):
    queryset = Place.objects.all()
    serializer_class = PlaceSerializer
    distance_filter_field = "geometry"
    distance_filter_convert_meters = True  # only for a WGS84 degree field
    filter_backends = (DistanceToPointFilter,)

The filter backends only construct/query geometry predicates. Route GeoJSON serializer output to the serialization skill, generated parameter/schema integration to pagination-and-schema, and end-to-end database/backend checks to integration-testing.

Bundled utility

From the runtime skill root, use python sub-skills/spatial-filtering/scripts/tile_bbox.py --help or python sub-skills/spatial-filtering/scripts/tile_bbox.py Z X Y to calculate a tile's west/south/east/north JSON. The utility is self-contained and does not require the application checkout. It is a coordinate/debugging aid, not a replacement for executing the ORM filter.

Hard warning

Every ORM predicate described here requires a spatially capable database and compatible geometry operations. The current production verified package/module imports and geometry smoke only; it did not verify PostGIS execution. Do not represent PostGIS behavior as verified without running the integration checks in the target environment.