Integration of with Django
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Integration of with Django


This project extends Django's QuerySet, some initial configurations need to be done in each model that use CartoDB integration:

See yoinup/django-cartodb/django_cartodb/

from django_cartodb.django_cartodb.models import CartoManager

class SomeModel(models.Model):
    objects = CartoManager()
    _cartodb_table = 'somemodeltable'  # model's table name in CartoDB


All django method's in models manager are the same, your actual code don't need modifications to work.

CartoManager includes a filter_cartodb() method to do complex queries to CartoDB.

Also, two shortcuts were added:

  • Get objects nearest to a position:
nearest(lat, lon, limit=10, offset=0)
  • Get objects inside a distance from a position:
distance(self, lat, lon, distance=1000, limit=10, offset=0)


Other methods like filter(), exclude(), order_by() can be chained and used together with filter_cartodb()

IMPORTANT: filter_cartodb() isn't lazy like filter() is, so each time is called, a request will be sent to CartoDB and your code will block until the response is received.

Parameters required:

  • lat: float with the latitude
  • lon: float with the longitude


  • distance: int, query objects inside a distance (in meters).
  • limit: int, limit number of objects retrieved
  • offset: int, remove from list first offset objects
# To get first 10 objects in 1km around the (lat, lon) point.
SomeModel.objects.filter_cartodb(lat=0.123434, lon=-3.154774, distance=1000, limit=10)
# To get the next 10 objects
SomeModel.objects.filter_cartodb(lat=0.123434, lon=-3.154774, distance=1000, limit=10, offset=10)

When iterating over the list of objects returned, each object get a distance attr added with the distance between the object and the point queried.


An initial JOINs support is available, add a param like tableJOIN__fieldJOIN__pkJOIN when calling filter_cartodb():

  • tableJOIN: is the name of the table in CartoDB to do the join.
  • fieldJOIN: the field in tableJOIN to filter
  • pkJOIN: the field in tableJOIN with the primary key reference to mix each table.
# add JOIN querying *categorytable* with field *category_id* equals to 2 and *model_id* as primary key field.


  • Return object list ordered by distance, in MySQL maybe FIELD(param, values) can be used.
  • Support to custom ORDER BY.
  • Support to add custom SQL queries.