Fields

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.

This field takes two optional arguments:

precision: Passes coordinates through Python's builtin round() function (docs), rounding values to
the provided level of precision. E.g. A Point with lat/lng of
[51.0486, -114.0708] passed through a GeometryField(precision=2)
would return a Point with a lat/lng of [51.05, -114.07].

remove_duplicates: Remove sequential duplicate coordinates from line and
polygon geometries. This is particularly useful when used with the precision
argument, as the likelihood of duplicate coordinates increase as precision of
coordinates are reduced.

Note: While both above arguments are designed to reduce the
byte size of the API response, they will also increase the processing time
required to render the response. This will likely be negligible for small GeoJSON
responses but may become an issue for large responses.

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.

Serializers

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 subclass 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:

classLocation(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()

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:

Bounding Box: "auto_bbox" and "bbox_geo_field"

The GeoJSON specification allows a feature to contain a
boundingbox of a feature.
GeoFeatureModelSerializer allows two different ways to fill this property. The first
is using the geo_field to calculate the bounding box of a feature. This only allows
read access for a REST client and can be achieved using auto_bbox. Example:

The second approach uses the bbox_geo_field to specify an additional
GeometryField of the model which will be used to calculate the bounding box. This allows
boundingboxes differ from the exact extent of a features geometry. Additionally this
enables read and write access for the REST client. Bounding boxes send from the client will
be saved as Polygons. Example:

Custom GeoJSON properties source

In GeoJSON each feature can have a properties member containing the
attributes of the feature. By default this field is filled with the
attributes from your Django model, excluding the id, geometry and bounding
box fields. It's possible to override this behaviour and implement a custom
source for the properties member.

The following example shows how to use a PostgreSQL HStore field as a source for
the properties member:

When the serializer renders GeoJSON, it calls the method
get_properties for each object in the database. This function
should return a dictionary containing the attributes for the feature. In the
case of a HStore field, this function is easily implemented.

The reverse is also required: mapping a GeoJSON formatted structure to
attributes of your model. This task is done by unformat_geojson. It should
return a dictionary with your model attributes as keys, and the corresponding
values retrieved from the GeoJSON feature data.

Filters

note: this feature has been tested up to django-filter 1.0.

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.

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.

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.

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%.

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.

This should allow you to run the tests already.

For reference, the following steps will setup a development environment for
contributing to the project: