TOC(GeoDjangoDatabaseAPI)

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 GeoDjango Model API docs:

>>> qs = Zip.objects.filter(<field>__<lookup type>=<parameter>)
>>> qs = Zip.objects.exclude(...)

For example:

>>> qs = Zip.objects.filter(poly__contains=pnt)

In this case, poly is the geographic field, contains is the lookup type, and pnt is the parameter (which may be a GEOSGeometry object, a string of WKT, or a string of HEXEWKB).

Creating and Saving Geographic Models

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

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

GEOSGeometry objects may also be used to save geometric models:

>>> from django.contrib.gis.geos import GEOSGeometry
>>> z = Zip(code=77096, poly=GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))'))
>>> z.save()

Moreover, if the GEOSGeometry is in a different coordinate system (has a different SRID value) than that of the field, then it will be implicitly transformed into the SRID of the model's field, using the spatial database's transform procedure:

>>> poly_3084 = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))', srid=3084) # SRID 3084 is 'NAD83(HARN) / Texas Centric Lambert Conformal'
>>> z = Zip(code=78212, poly=poly_3084)
>>> z.save()
>>> from django.db import connection
>>> print connection.queries[-1]['sql'] # printing the last SQL statement executed
INSERT INTO "geoapp_zip" ("code", "poly") VALUES (78212, ST_Transform(ST_GeomFromWKB('\\001 ... ', 3084), 4326))

Thus, geometry parameters may be passed in using the GEOSGeometry object, WKT (Well Known Text) or HEXEWKB (PostGIS specific, essentially a WKB geometry in hexadecimal). Essentially, if the input is not a GEOSGeometry object, it will try interpret it as WKT or HEXEWKB. For example:

• GEOS Geometry:

  >>> from django.contrib.gis.geos import *
  >>> pnt  = Point(5, 23)
  >>> ls   = LineString((0, 0), (5, 23))
  >>> poly = GEOSGeometry('POLYGON (( 10 10, 10 20, 20 20, 20 15, 10 10))')
  

• WKT Polygon: 'POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))'
  • See Open GIS Consortium, Inc., ​OpenGIS Simple Feature Specification For SQL, Document 99-049 (May 5, 1999), at Ch. 3.2.5 (SQL Textual Representation of Geometry, pg. 53).
• HEXEWKB Polygon: '0103000000010000000 ... 00000000000002440'
  • See ​PostGIS EWKB, EWKT and Canonical Forms, PostGIS documentation at Ch. 4.1.2.

PostGIS

PostGIS Operator Field Lookup Types

For more information, see generally, ​"Operators", PostGIS Documentation at Ch. 6.2.2

• 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

For more information, see generally ​Geometry Relationship Functions, PostGIS Documentation at Ch. 6.1.2.

Please note that when using PostGIS 1.3.1 and above, index support is automatically "inlined" -- in other words, the bounding box equivalent is automatically evaluated prior to calling these, more computationally expensive, functions.

• equals
  • 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
  • Returns 1 (TRUE) if the Geometries are "spatially disjoint".
  • PostGIS equivalent Disjoint(geometry, geometry)
• touches
  • Returns 1 (TRUE) if the Geometries "spatially touch".
  • PostGIS equivalent Touches(geometry, geometry)
• crosses
  • Returns 1 (TRUE) if the Geometries "spatially cross".
  • PostGIS equivalent Crosses(geometry, geometry)
• within
  • Returns 1 (TRUE) if Geometry A is "spatially within" Geometry B.
  • PostGIS equivalent Within(geometry, geometry)
• overlaps
  • Returns 1 (TRUE) if the Geometries "spatially overlap".
  • PostGIS equivalent Overlaps(geometry, geometry)
• contains
  • Returns 1 (TRUE) if Geometry A "spatially contains" Geometry B.
  • PostGIS equivalent Contains(geometry, geometry)
• relate
  • Returns the DE-9IM (dimensionally extended nine-intersection matrix) between the two geometries.
  • Tuple parameter (geom, pattern) required for lookup type, where pattern is an intersection pattern -- a string comprising nine characters, where each character is one of T, F, or *.).
  • PostGIS equivelent Relate(geometry, geometry, intersectionPatternMatrix)

The following lookup types are only available in PostGIS versions 1.3.1 and above:

• dwithin
  • Returns true if geometries are within the specified distance of one another. Uses indexes if available.
  • Tuple parameter (geom, distance) required for lookup type.
• coveredby
  • Returns 1 (TRUE) if no point in Geometry A is outside Geometry B
  • Refer to ​this resource for an explaination of the need of this function.
• covers
  • Returns 1 (TRUE) if no point in Geometry B is outside Geometry A
  • See link in coveredby documentation above for more information.

Oracle

For more information, see generally, ​Spatial Operators, Oracle Spatial User's Guide and Manual, at Ch. 11.

• contains
  • Oracle equivalent SDO_CONTAINS(geometry1, geometry2)
• coveredby
  • Oracle equivalent SDO_COVEREDBY(geometry1, geometry2)
• covers
  • Oracle equivalent SDO_COVERS(geometry1, geometry2)
• dwithin
  • Oracle equivalent SDO_WITHIN_DISTANCE(geometry1, geometry2, 'distance=<param>')
  • Tuple parameter (geom, distance) required for lookup type.
• equals, exact, same_as
  • Oracle equivalent, SDO_EQUALS(geometry1, geometry2)
• intersects
  • Oracle equivalent SDO_OVERLAPBDYINTERSECT(geometry1, geometry2)
• overlaps
  • Oracle equivalent SDO_OVERLAPS(geometry1, geometry2)
• touches
  • Oracle equivalent SDO_TOUCH(geometry1, geometry2)
• within
  • Oracle equivalent SDO_INSIDE(geometry1, geometry2)

MySQL

For more information, see generally, ​Relations on Geometry Minimal Bounding Rectangles (MBRs), MySQL 5.0 Reference Manual, at Ch. 17.5.5.

• bbcontains, contains
  • MySQL equivalent MBRContains(g1, g2)
• contained, within
  • MySQL equivalent MBRWithin(g1, g2)
• disjoint
  • MySQL equivalent MBRDisjoint(g1, g2)
• equals, exact, same_as
  • MySQL equivalent MBREqual(g1, g2)
• intersects
  • MySQL equivalent MBRIntersects(g1, g2)
• overlaps
  • MySQL equivalent MBROverlaps(g1, g2)
• touches
  • MySQL equivalent MBRTouches(g1, g2)

Extra Instance Methods

Update: All of the extra instance methods haave been deprecated as of r6467 because lazy geometry support includes all of their functionality (including OGR geometries and OSR spatial references with the ogr and srs properties, respectively). In other words, these properties may be directly accessed as attributes from the geometry field.