Geographic add-ons for Django Rest Framework - Mailing List.
pip install djangorestframework-gis
DRF-gis version | DRF version | Django version | Python version |
0.4.0 | higher than 2.3.14 | 1.5.x to 1.7 | 2.6 to 3.4 |
0.3.0 | higher than 2.3.14 | 1.5.x, 1.6.x | 2.6, 2.7 |
0.2.0 | from 2.2.2 to 2.3.13 | 1.5.x, 1.6.x | 2.6, 2.7 |
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.
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 GeoModelSerizalizer
will output:
{
"id": 1,
"address": "742 Evergreen Terrace",
"city": "Springfield",
"state": "Oregon",
"point": {
"type": "Point",
"coordinates": [-123.0208, 44.0464],
}
}
GeoFeatureModelSerializer
is a subclass of GeoModelSerializer
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
:
(NOTE: This currenty does not work with the default pagination serializer)
{
"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"
}
}
}
GeoFeatureModelSerializer
requires you to define a ``geo_field``
to be serialized as the "geometry". For example:
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')
The primary key of the model (usually the "id" attribute) is automatically put outside the "properties" object (before "type") unless ``id_field`` is set to False:
class LocationSerializer(GeoFeatureModelSerializer):
class Meta:
model = Location
geo_field = "point"
id_field = False
fields = ('id', 'address', 'city', 'state')
You could also set the ``id_field`` to some other unique field in your model, like "slug":
class LocationSerializer(GeoFeatureModelSerializer):
class Meta:
model = Location
geo_field = "point"
id_field = "slug"
fields = ('slug', 'address', 'city', 'state')
We provide a GeometryFilter
field as well as a GeoFilterSet
for usage with django_filter
. You simply provide, in the query
string, one of the textual types supported by GEOSGeometry
. By
default, this includes WKT, HEXEWKB, WKB (in a buffer), and GeoJSON.
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 ] }
.
The GeoFilterSet
provides a django_filter
compatible
FilterSet
that will automatically create GeometryFilters
for
GeometryFields
.
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,)
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.
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%.
- Nodeshot: Extensible Django web application for management of community-led georeferenced data
Assuming one has the dependencies installed (restframework and restframework_gis), and one of the Spatial Database server supported by GeoDjango is up and running:
./runtests.py
You might need to tweak the DB settings according to your DB
configuration. You can copy the file local_settings.example.py
to
local_settings.py
and change the DATABASES
and/or
INSTALLED_APPS
directives there.
If you want to contribute you need to install the test app in a proper development environment.
These steps should do the trick:
- create a spatial database named "django_restframework_gis"
- create
local_settings.py
, eg:cp local_settings.example.py local_settings.py
- tweak the
DATABASES
configuration directive according to your DB settings - optionally install
olwidget
withpip install olwidget
- uncomment
INSTALLED_APPS
(remove olwidget if you did not install it) - run
python manage.py syncdb
- run
python manage.py collectstatic
- run
python manage.py runserver
- Join the Django REST Framework GIS Mailing List and announce your intentions
- Follow the PEP8 Style Guide for Python Code
- Fork this repo
- Write code
- Write tests for your code
- Ensure all tests pass
- Ensure test coverage is not under 90%
- Document your changes
- Send pull request