Added a new GeoJSON serialization format for GeoDjango

Thanks Reinout van Rees for the review.

4 files changed, 80 insertions, 2 deletions

diff --git a/docs/ref/contrib/gis/serializers.txt b/docs/ref/contrib/gis/serializers.txt
new file mode 100644
index 0000000000..4e445f03ad
--- /dev/null
+++ b/docs/ref/contrib/gis/serializers.txt
@@ -0,0 +1,69 @@
+.. _ref-geojson-serializer:
+
+==================
+GeoJSON Serializer
+==================
+
+.. versionadded:: 1.8
+
+.. module:: django.contrib.gis.serializers.geojson
+   :synopsis: Serialization of GeoDjango models in the GeoJSON format.
+
+GeoDjango provides a specific serializer for the `GeoJSON`__ format. The GDAL
+library is required for this serializer. See :doc:`/topics/serialization` for
+more information on serialization.
+
+__ http://geojson.org/
+
+The ``geojson`` serializer is not meant for round-tripping data, as it has no
+deserializer equivalent. For example, you cannot use :djadmin:`loaddata` to
+reload the output produced by this serializer. If you plan to reload the
+outputted data, use the plain :ref:`json serializer <serialization-formats-json>`
+instead.
+
+In addition to the options of the ``json`` serializer, the ``geojson``
+serializer accepts the following additional option when it is called by
+``serializers.serialize()``:
+
+* ``geometry_field``: A string containing the name of a geometry field to use
+  for the ``geometry`` key of the GeoJSON feature. This is only needed when you
+  have a model with more than one geometry field and you don't want to use the
+  first defined geometry field (by default, the first geometry field is picked).
+
+* ``srid``: The SRID to use for the ``geometry`` content. Defaults to 4326
+  (WGS 84).
+
+The :ref:`fields <subset-of-fields>` option can be used to limit fields that
+will be present in the ``properties`` key, as it works with all other
+serializers.
+
+Example::
+
+    from django.core.serializers import serialize
+    from my_app.models import City
+
+    serialize('geojson', City.objects.all(),
+              geometry_field='point',
+              fields=('name',))
+
+Would output::
+
+    {
+      'type': 'FeatureCollection',
+      'crs': {
+        'type': 'name',
+        'properties': {'name': 'EPSG:4326'}
+      },
+      'features': [
+        {
+          'type': 'Feature',
+          'geometry': {
+            'type': 'Point',
+            'coordinates': [-87.650175, 41.850385]
+          },
+          'properties': {
+            'name': 'Chicago'
+          }
+        }
+      ]
+    }
diff --git a/docs/ref/contrib/gis/utils.txt b/docs/ref/contrib/gis/utils.txt
index fee6325437..539a4ca9a2 100644
--- a/docs/ref/contrib/gis/utils.txt
+++ b/docs/ref/contrib/gis/utils.txt
@@ -15,3 +15,4 @@ useful in creating geospatial Web applications.
 
    layermapping
    ogrinspect
+   serializers
diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt
index 6bfe9435a6..dc3b4211c8 100644
--- a/docs/releases/1.8.txt
+++ b/docs/releases/1.8.txt
@@ -131,12 +131,15 @@ Minor features
 :mod:`django.contrib.gis`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-* Compatibility shims for ``SpatialRefSys`` and ``GeometryColumns`` changed in
-  Django 1.2 have been removed.
+* A new :doc:`GeoJSON serializer </ref/contrib/gis/serializers>` is now
+  available.
 
 * The Spatialite backend now supports ``Collect`` and ``Extent`` aggregates
   when the database version is 3.0 or later.
 
+* Compatibility shims for ``SpatialRefSys`` and ``GeometryColumns`` changed in
+  Django 1.2 have been removed.
+
 :mod:`django.contrib.messages`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/docs/topics/serialization.txt b/docs/topics/serialization.txt
index 8ddf6a6b57..514b472b01 100644
--- a/docs/topics/serialization.txt
+++ b/docs/topics/serialization.txt
@@ -47,6 +47,8 @@ This is useful if you want to serialize data directly to a file-like object
     :ref:`format <serialization-formats>` will raise a
     ``django.core.serializers.SerializerDoesNotExist`` exception.
 
+.. _subset-of-fields:
+
 Subset of fields
 ~~~~~~~~~~~~~~~~
 
@@ -257,6 +259,9 @@ In particular, :ref:`lazy translation objects <lazy-translations>` need a
                 return force_text(obj)
             return super(LazyEncoder, self).default(obj)
 
+Also note that GeoDjango provides a :doc:`customized GeoJSON serializer
+</ref/contrib/gis/serializers>`.
+
 .. _special encoder: http://docs.python.org/library/json.html#encoders-and-decoders
 .. _ecma-262: http://www.ecma-international.org/ecma-262/5.1/#sec-15.9.1.15