Version 1 (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 [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:

- 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)`

`intersects`

- PostGIS equivalent
`Intersects(geometry, geometry)`

- PostGIS equivalent
`touches`

- PostGIS equivalent
`Touches(geometry, geometry)`

- PostGIS equivalent
`crosses`

- PostGIS equivalent
`Crosses(geometry, geometry)`

- PostGIS equivalent
`overlaps`

- PostGIS equivalent
`Overlaps(geometry, geometry)`

- PostGIS equivalent
`contains`

- PostGIS equivalent
`Contains(geometry, geometry)`

- PostGIS equivalent
`intersects`

- PostGIS equivalent
`Intersects(geometry, geometry)`

- PostGIS equivalent
`relate`

- PostGIS equivelent
`Relate(geometry, geometry)`

- PostGIS equivelent

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