djangorestframework-gis-distance 1.0.0
UNKNOWN
License: MIT

|Build Status|

Django-Rest-Framework-Gis-Distance
==================================

This is a extension to
`Django-Rest-Framework-Gis <https://github.com/djangonauts/django-rest-framework-gis>`__
that adds sorting and distance distance to the
`DistanceToPointerFilter <https://github.com/djangonauts/django-rest-framework-gis#distancetopointfilter>`__.

Requirements
------------

-  Python 2.7
-  Django 1.7+
-  Django-Rest-Framework-Gis 0.10+

Installation
------------

Install the library with pip:

::

    $ pip install djangorestframework-gis-distance

Quick Setup
-----------

Make sure ``rest_framework_gis_distance`` is added to your
``INSTALLED_APPS``, after ``rest_framework`` and ``restframework_gis``.

.. code:: python

    INSTALLED_APPS = (
        # ...

        'rest_framework',
        'rest_framework_gis',
        'rest_framework_gis_distance',
    )

Usage
-----

Regular implementation
~~~~~~~~~~~~~~~~~~~~~~

First include DistanceField in your serializer.

.. code:: python

    from restframework_gis_distance.fields import DistanceField

    class RecordSerializer(serializers.ModelSerializer):
        distance = DistanceField(unit='m')

        class Meta:
            model = Record
            fields = ('location', 'title', 'created', 'distance')

Then use the filter ``OrderedDistanceToPointFilter`` in your view.

.. code:: python

    from restframework_gis_distance.filters import OrderedDistanceToPointFilter

    class RecordListView(mixins.ListModelMixin, generics.GenericAPIView):
        permission_classes = (AllowAny,)
        serializer_class = RecordSerializer
        queryset = Record.objects.all()
        filter_backends = (OrderedDistanceToPointFilter,)
        distance_filter_field = 'location'
        distance_filter_convert_meters = True
        distance_filter_add_distance = True

After this, set up your urls as usual and call your endpoint like this:
``example.com/api/endpoint/?dist=1000&point=long,lat``

Optional field
~~~~~~~~~~~~~~

Using distance as a optional field (for the cases when you only want to
display distance when geo coordinates is supplied)

Instead of declaring a straight DistanceField, wrap the DistanceField as
a SerializerMethodField, like this:

.. code:: python

    from restframework_gis_distance.filters import OrderedDistanceToPointFilter

    class RecordOptionalSerializer(serializers.ModelSerializer):
        distance = serializers.SerializerMethodField()

        class Meta:
            model = Record
            fields = ('location', 'title', 'created', 'distance')

        def get_distance(self, obj):
            distance = getattr(obj, "distance", None)
            return DistanceField(unit='m').to_representation(distance)

Options
-------

These belong in your DRF view:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-  ``distance_filter_field``: Target geo filtering field (inherited from
   DistanceToPointerFilter).
-  ``distance_srid``: (Optional) The srid you want to use on your
   distance. (Default ``4326``)
-  ``distance_sort_order``: (Optional) Indicates the sort order, closest
   (``True``) or farthest (``False``). (Default: ``True``)

Questions
---------

-  How do I change distance unit?

   -  Add the param unit=DESIRED\_UNIT to your DistanceField, make sure
      you use a `django supported
      unit <https://docs.djangoproject.com/en/1.9/ref/contrib/gis/measure/#supported-units>`__.

Tests
-----

This library include tests, just run ``python runtests.py``.

Contributing
------------

Want to contribute? Awesome. Just send a pull request.

License
-------

Django-Rest-Framework-Gis-Distance is released under the `MIT
License <http://www.opensource.org/licenses/MIT>`__.

.. |Build Status| image:: https://travis-ci.org/Frojd/restframework-gis-distance.svg?branch=master
   :target: https://travis-ci.org/Frojd/restframework-gis-distance