djangorestframework-gis 0.11

GeometryField

Provides a GeometryField, which is a subclass of Django Rest Framework (from now on DRF) WritableField. This field handles GeoDjango geometry fields, providing custom to_native and from_native methods for GeoJSON input/output.

New in 0.9.3: there is no need to define this field explicitly in your serializer, it’s mapped automatically during initialization in rest_framework_gis.apps.AppConfig.ready().

GeometrySerializerMethodField

Provides a GeometrySerializerMethodField, which is a subclass of DRF SerializerMethodField and handles values which are computed with a serializer method and are used as a geo_field. See example below.

GeoModelSerializer (DEPRECATED)

Deprecated, will be removed in 1.0: Using this serializer is not needed anymore since 0.9.3 if you add rest_framework_gis in settings.INSTALLED_APPS

Provides a GeoModelSerializer, which is a sublass of DRF ModelSerializer. This serializer updates the field_mapping dictionary to include field mapping of GeoDjango geometry fields to the above GeometryField.

For example, the following model:

class Location(models.Model):
    """
    A model which holds information about a particular location
    """
    address = models.Charfield(max_length=255)
    city = models.CharField(max_length=100)
    state = models.CharField(max_length=100)
    point = models.PointField()

By default, the DRF ModelSerializer will output:

{
    "id": 1,
    "address": "742 Evergreen Terrace",
    "city":  "Springfield",
    "state": "Oregon",
    "point": "POINT(-123.0208 44.0464)"
}

In contrast, the GeoModelSerializer will output:

{
    "id": 1,
    "address": "742 Evergreen Terrace",
    "city":  "Springfield",
    "state": "Oregon",
    "point": {
        "type": "Point",
        "coordinates": [-123.0208, 44.0464],
    }
}

GeoFeatureModelSerializer

GeoFeatureModelSerializer is a subclass of rest_framework.ModelSerializer which will output data in a format that is GeoJSON compatible. Using the above example, the GeoFeatureModelSerializer will output:

 {
    "id": 1,
    "type": "Feature",
    "geometry": {
        "point": {
            "type": "Point",
            "coordinates": [-123.0208, 44.0464],
        },
    },
    "properties": {
        "address": "742 Evergreen Terrace",
        "city":  "Springfield",
        "state": "Oregon"
    }
}

If you are serializing an object list, GeoFeatureModelSerializer will create a FeatureCollection:

{
    "type": "FeatureCollection",
    "features": [
    {
        "id": 1
        "type": "Feature",
        "geometry": {
            "point": {
                "type": "Point",
                "coordinates": [-123.0208, 44.0464],
            }
        },
        "properties": {
            "address": "742 Evergreen Terrace",
            "city":  "Springfield",
            "state": "Oregon",
        }
    }
    {
        "id": 2,
        "type": "Feature",
        "geometry": {
            "point": {
                "type": "Point",
                "coordinates": [-123.0208, 44.0489],
            },
        },
        "properties": {
            "address": "744 Evergreen Terrace",
            "city":  "Springfield",
            "state": "Oregon"
        }
    }
}

from rest_framework_gis.serializers import GeoFeatureModelSerializer

class LocationSerializer(GeoFeatureModelSerializer):
    """ A class to serialize locations as GeoJSON compatible data """

    class Meta:
        model = Location
        geo_field = "point"

        # you can also explicitly declare which fields you want to include
        # as with a ModelSerializer.
        fields = ('id', 'address', 'city', 'state')

from django.contrib.gis.geos import Point
from rest_framework_gis.serializers import GeoFeatureModelSerializer, GeometrySerializerMethodField

class LocationSerializer(GeoFeatureModelSerializer):
    """ A class to serialize locations as GeoJSON compatible data """

    # a field which contains a geometry value and can be used as geo_field
    other_point = GeometrySerializerMethodField()

    def get_other_point(self, obj):
        return Point(obj.point.lat / 2, obj.point.lon / 2)

    class Meta:
        model = Location
        geo_field = 'other_point'

from rest_framework_gis.serializers import GeoFeatureModelSerializer

class LocationSerializer(GeoFeatureModelSerializer):

    class Meta:
        model = Location
        geo_field = "point"
        id_field = False
        fields = ('id', 'address', 'city', 'state')

from rest_framework_gis.serializers import GeoFeatureModelSerializer

class LocationSerializer(GeoFeatureModelSerializer):

    class Meta:
        model = Location
        geo_field = 'point'
        id_field = 'slug'
        fields = ('slug', 'address', 'city', 'state')

from rest_framework_gis.serializers import GeoFeatureModelSerializer

class LocationSerializer(GeoFeatureModelSerializer):
    class Meta:
        model = Location
        geo_field = 'geometry'
        auto_bbox = True

from rest_framework_gis.serializers import GeoFeatureModelSerializer

class LocationSerializer(GeoFeatureModelSerializer):

    class Meta:
        model = BoxedLocation
        geo_field = 'geometry'
        bbox_geo_field = 'bbox_geometry'

# models.py
class Link(models.Model):
    """
    Metadata is stored in a PostgreSQL HStore field, which allows us to
    store arbitrary key-value pairs with a link record.
    """
    metadata = HStoreField(blank=True, null=True, default=dict)
    geo = models.LineStringField()
    objects = models.GeoManager()

# serializers.py
class NetworkGeoSerializer(GeoFeatureModelSerializer):
    class Meta:
        model = models.Link
        geo_field = 'geo'
        auto_bbox = True

    def get_properties(self, instance, fields):
        # This is a PostgreSQL HStore field, which django maps to a dict
        return instance.metadata

    def unformat_geojson(self, feature):
        attrs = {
            self.Meta.geo_field: feature["geometry"],
            "metadata": feature["properties"]
        }

        if self.Meta.bbox_geo_field and "bbox" in feature:
            attrs[self.Meta.bbox_geo_field] = Polygon.from_bbox(feature["bbox"])

        return attrs

GeoJsonPagination

Based on rest_framework.pagination.PageNumberPagination.

Code example:

from rest_framework_gis.pagination import GeoJsonPagination
# --- other omitted imports --- #

class GeojsonLocationList(generics.ListCreateAPIView):
    # -- other omitted view attributes --- #
    pagination_class = GeoJsonPagination

Example result response (cut to one element only instead of 10):

{
    "type": "FeatureCollection",
    "count": 25,
    "next": "http://localhost:8000/geojson/?page=2",
    "previous": null,
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    42.0,
                    50.0
                ]
            },
            "properties": {
                "name": "test"
            }
        }
    ]
}

GeometryFilter

from rest_framework_gis.filterset import GeoFilterSet

class RegionFilter(GeoFilterSet):
    slug = filters.CharFilter(name='slug', lookup_type='istartswith')
    contains_geom = filters.GeometryFilter(name='geom', lookup_type='contains')

    class Meta:
        model = Region

We can then filter in the URL, using GeoJSON, and we will perform a __contains geometry lookup, e.g. /region/?contains_geom={ "type": "Point", "coordinates": [ -123.26436996459961, 44.564178042345375 ] }.

GeoFilterSet

The GeoFilterSet provides a django_filter compatible FilterSet that will automatically create GeometryFilters for GeometryFields.

InBBoxFilter

Provides a InBBoxFilter, which is a subclass of DRF BaseFilterBackend. Filters a queryset to only those instances within a certain bounding box.

views.py:

from rest_framework_gis.filters import InBBoxFilter

class LocationList(ListAPIView):

    queryset = models.Location.objects.all()
    serializer_class = serializers.LocationSerializer
    bbox_filter_field = 'point'
    filter_backends = (InBBoxFilter, )
    bbox_filter_include_overlapping = True # Optional

We can then filter in the URL, using Bounding Box format (min Lon, min Lat, max Lon, max Lat), and we can search for instances within the bounding box, e.g.: /location/?in_bbox=-90,29,-89,35.

By default, InBBoxFilter will only return those instances entirely within the stated bounding box. To include those instances which overlap the bounding box, include bbox_filter_include_overlapping = True in your view.

Note that if you are using other filters, you’ll want to include your other filter backend in your view. For example:

filter_backends = (InBBoxFilter, DjangoFilterBackend,)

TMSTileFilter

Provides a TMSTileFilter, which is a subclass of InBBoxFilter. Filters a queryset to only those instances within a bounding box defined by a TMS tile address.

views.py:

from rest_framework_gis.filters import TMSTileFilter

class LocationList(ListAPIView):

    queryset = models.Location.objects.all()
    serializer_class = serializers.LocationSerializer
    bbox_filter_field = 'point'
    filter_backends = (TMSTileFilter, )
    bbox_filter_include_overlapping = True # Optional

We can then filter in the URL, using TMS tile addresses in the zoom/x/y format, eg:. /location/?tile=8/100/200 which is equivalant to filtering on the bbox (-39.37500,-71.07406,-37.96875,-70.61261).

For more information on configuration options see InBBoxFilter.

Note that the tile address start in the upper left, not the lower left origin used by some implementations.

DistanceToPointFilter

Provides a DistanceToPointFilter, which is a subclass of DRF BaseFilterBackend. Filters a queryset to only those instances within a certain distance of a given point.

views.py:

from rest_framework_gis.filters import DistanceToPointFilter

class LocationList(ListAPIView):

    queryset = models.Location.objects.all()
    serializer_class = serializers.LocationSerializer
    distance_filter_field = 'geometry'
    filter_backends = (DistanceToPointFilter, )
    bbox_filter_include_overlapping = True # Optional

We can then filter in the URL, using a distance and a point in (lon, lat) format. The distance can be given in meters or in degrees.

eg:. /location/?dist=4000&point=-122.4862,37.7694&format=json which is equivalant to filtering within 4000 meters of the point (-122.4862, 37.7694).

By default, DistanceToPointFilter will pass the ‘distance’ in the URL directly to the database for the search. The effect depends on the srid of the database in use. If geo data is indexed in meters (srid 3875, aka 900913), a distance in meters can be passed in directly without conversion. For lat-lon databases such as srid 4326, which is indexed in degrees, the ‘distance’ will be interpreted as degrees. Set the flag, ‘distance_filter_convert_meters’ to ‘True’ in order to convert an input distance in meters to degrees. This conversion is approximate, and the errors at latitudes > 60 degrees are > 25%.