Version 4 (modified by jbronn, 17 years ago) ( diff )

--

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(<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)
  • 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.
    • PostGIS equivelent Relate(geometry, geometry)

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.

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