Version 1 (modified by jbronn, 18 years ago) ( diff )

GeoDjango database api

TOC

Database API

Note: The following database lookup types can only be used with on geographic fields with filter(). Filters on 'normal' fields (e.g. CharField) may be chained with those on geographic fields. Thus, geographic queries take the following form (assuming the Zip model used in the [GeoDjangoModelAPI GeoDjango Model API docs]: 

>>> qs = Zip.objects.filter(<geo field A>__<geo lookup type>=<geo string B>)
>>> qs = Zip.objects.exclude(...)

Creating and Saving Geographic-Enabled Objects

Here is an example of how to create a geometry object (assuming the Zip model example above): 

>>> from zipcode.models import Zip
>>> z = Zip(code=77096, poly='POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))')
>>> z.save()

Geometries are represented as strings in either of the formats WKT (Well Known Text) or HEXEWKB (PostGIS specific, essentially a WKB geometry in hexadecimal). For example:

PostGIS Operator Field Lookup Types

  • See generally, ​"Operators", PostGIS Documentation at Ch. 6.2.2
  • Note: This API is subject to some change -- we're open to suggestions.
  • overlaps_left
    • Returns true if A's bounding box overlaps or is to the left of B's bounding box.
    • PostGIS equivalent "&<"
  • overlaps_right
    • Returns true if A's bounding box overlaps or is to the right of B's bounding box.
    • PostGIS equivalent "&>"
  • left
    • Returns true if A's bounding box is strictly to the left of B's bounding box.
    • PostGIS equivalent "<<"
  • right
    • Returns true if A's bounding box is strictly to the right of B's bounding box.
    • PostGIS equivalent ">>"
  • overlaps_below
    • Returns true if A's bounding box overlaps or is below B's bounding box.
    • PostGIS equivalent "&<|"
  • overlaps_above
    • Returns true if A's bounding box overlaps or is above B's bounding box.
    • PostGIS equivalent "|&>"
  • strictly_below
    • Returns true if A's bounding box is strictly below B's bounding box.
    • PostGIS equivalent "<<|"
  • strictly_above
    • Returns true if A's bounding box is strictly above B's bounding box.
    • PostGIS equivalent "|>>"
  • same_as or exact
    • The "same as" operator. It tests actual geometric equality of two features. So if A and B are the same feature, vertex-by-vertex, the operator returns true.
    • PostGIS equivalent "~="
  • contained
    • Returns true if A's bounding box is completely contained by B's bounding box.
    • PostGIS equivalent "@"
  • bbcontains
    • Returns true if A's bounding box completely contains B's bounding box.
    • PostGIS equivalent "~"
  • bboverlaps
    • Returns true if A's bounding box overlaps B's bounding box.
    • PostGIS equivalent "&&"

PostGIS GEOS Function Field Lookup Types

  • See generally ​"Geometry Relationship Functions", PostGIS Documentation at Ch. 6.1.2.
  • This documentation will be updated completely with the content from the aforementioned PostGIS docs.
  • equals
    • Requires GEOS
    • Returns 1 (TRUE) if the given Geometries are "spatially equal".
    • Use this for a 'better' answer than '='. equals('LINESTRING(0 0, 10 10)','LINESTRING(0 0, 5 5, 10 10)') is true.
    • PostGIS equivalent Equals(geometry, geometry), OGC SPEC s2.1.1.2
  • disjoint
    • Requires GEOS
    • Returns 1 (TRUE) if the Geometries are "spatially disjoint".
    • PostGIS equivalent Disjoint(geometry, geometry)
  • intersects
    • PostGIS equivalent Intersects(geometry, geometry)
  • touches
    • PostGIS equivalent Touches(geometry, geometry)
  • crosses
    • PostGIS equivalent Crosses(geometry, geometry)
  • overlaps
    • PostGIS equivalent Overlaps(geometry, geometry)
  • contains
    • PostGIS equivalent Contains(geometry, geometry)
  • intersects
    • PostGIS equivalent Intersects(geometry, geometry)
  • relate
    • PostGIS equivelent Relate(geometry, geometry)

Extra Instance Methods

A model with geometry fields will get the following methods, substitute GEOM with the name of the geometry field:

get_GEOM_ogr

Returns a OGRGeometry instance for the geometry.

get_GEOM_geos

Returns a GEOSGeometry instance for the geometry. For example (using the District model from above): 

>>> from django.contrib.gis.geos import GEOSGeometry
>>> dist = District.objects.get(name='Houston ISD')
>>> geom = dist.get_poly_geos()
>>> print geom.centroid.wkt
POINT(-95.231713 29.723235)
>>> print geom.area
0.08332
>>> print geom.geom_type
Polygon
>>> print geom.centroid.geom_type
Point
>>> print geom.intersects(GEOSGeometry('POINT(-95.395223 29.798088)'))
False

get_GEOM_wkt

Returns the OGC WKT (Well Known Text) for the geometry. For example (using the School model from above): 

>>> skool = School.objects.get(name='PSAS')
>>> print skool.get_point_wkt()
POINT(-95.460822 29.745463)

get_GEOM_centroid

This routine will return the centroid of the geometry. For example (using the District model from above): 

>>> dist = District.objects.get(name='Houston ISD')
>>> print dist.get_poly_centroid()
POINT(-95.231713 29.723235)

get_GEOM_area

This routine will return the area of the geometry field. 

>>> dist = District.objects.get(name='Houston ISD')
>>> print dist.get_poly_area()
0.08332

Note: Units are in the projected units of the coordinate system. In the example above, the units are in degrees since we're using WGS84.

Note: See TracWiki for help on using the wiki.
Back to Top