Version 4 (modified by 11 years ago) (diff) | ,
---|

# 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:

- 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 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.