django/docs/ref/contrib/gis/feeds.txt

.. _ref-gis-feeds:

================
Geographic Feeds
================

.. module:: django.contrib.gis.feeds
   :synopsis: GeoDjango's framework for generating spatial feeds.

GeoDjango has its own :class:`Feed` subclass that may embed location information
in RSS/Atom feeds formatted according to either the `Simple GeoRSS`__ or 
`W3C Geo`_ standards.  Because GeoDjango's syndication API is a superset of
Django's, please consult `Django's syndication documentation <ref-contrib-syndication>`
for details on general usage.

.. _W3C Geo: http://www.w3.org/2003/01/geo/

__ http://georss.org/1.0#simple

Example
=======

API Reference
=============

``Feed`` Subclass
-----------------

.. class:: Feed

   In addition to methods provided by 
   the :class:`django.contrib.syndication.feeds.Feed`
   base class, GeoDjango's ``Feed`` class provides
   the following overrides.  Note that these overrides may be done in multiple ways::

       from django.contrib.gis.feeds import Feed

       class MyFeed(Feed):

            # First, as a class attribute.
            geometry = ...
            item_geometry = ...

            # Also a function with no arguments
            def geometry(self):
                ...

            def item_geometry(self):
                ...

            # And as a function with a single argument
            def geometry(self, obj):
                ...

            def item_geometry(self, item):
                ...

   .. method:: geometry(obj)

   Takes the object returned by ``get_object()`` and returns the *feed's*
   geometry.  Typically this is a ``GEOSGeometry`` instance, or can be a
   tuple to represent a point or a box.  For example::

       class ZipcodeFeed(Feed):

           def geometry(self, obj):
               # Can also return: `obj.poly`, and `obj.poly.centroid`.
               return obj.poly.extent # tuple like: (X0, Y0, X1, Y1).

   .. method:: item_geometry(item)

   Set this to return the geometry for each *item* in the feed.  This
   can be a ``GEOSGeometry`` instance, or a tuple that represents a
   point coordinate or bounding box.  For example::

       class ZipcodeFeed(Feed):

           def item_geometry(self, obj):
	       # Returns the polygon.
               return obj.poly

``SyndicationFeed`` Subclasses
------------------------------

The following :class:`django.utils.feedgenerator.SyndicationFeed` subclasses
are available:

.. class:: GeoRSSFeed

.. class:: GeoAtom1Feed

.. class:: W3CGeoFeed

.. note::

    `W3C Geo`_ formatted feeds only support
    :class:`~django.contrib.gis.db.models.PointField` geometries.