Geographic Database Functions¶
The functions documented on this page allow users to access geographic database functions to be used in annotations, aggregations, or filters in Django.
Example:
>>> from django.contrib.gis.db.models.functions import Length
>>> Track.objects.annotate(length=Length('line')).filter(length__gt=100)
Not all backends support all functions, so refer to the documentation of each
function to see if your database backend supports the function you want to use.
If you call a geographic function on a backend that doesn’t support it, you’ll
get a NotImplementedError
exception.
Function’s summary:
Measurement  Relationships  Operations  Editors  Output format  Miscellaneous 

Area 
BoundingCircle 
Difference 
ForceRHR 
AsGeoJSON 
MemSize 
Distance 
Centroid 
Intersection 
Reverse 
AsGML 
NumGeometries 
Length 
Envelope 
SymDifference 
Scale 
AsKML 
NumPoints 
Perimeter 
PointOnSurface 
Union 
SnapToGrid 
AsSVG 

Transform 
GeoHash 

Translate 
Area
¶
Availability: MySQL, Oracle, PostGIS, SpatiaLite
Accepts a single geographic field or expression and returns the area of the
field as an Area
measure. On MySQL, a raw
float value is returned, as it’s not possible to automatically determine the
unit of the field.
AsGeoJSON
¶
Availability: PostGIS, SpatiaLite (≥ 3.0)
Accepts a single geographic field or expression and returns a GeoJSON representation of the geometry. Note that the result is
not a complete GeoJSON structure but only the geometry
key content of a
GeoJSON structure. See also GeoJSON Serializer.
Example:
>>> City.objects.annotate(json=AsGeoJSON('point')).get(name='Chicago').json
{"type":"Point","coordinates":[87.65018,41.85039]}
Keyword Argument  Description 

bbox 
Set this to True if you want the bounding box
to be included in the returned GeoJSON. 
crs 
Set this to True if you want the coordinate
reference system to be included in the returned
GeoJSON. 
precision 
It may be used to specify the number of significant digits for the coordinates in the GeoJSON representation – the default value is 8. 
AsGML
¶
Availability: PostGIS, SpatiaLite (≥ 2.4.0RC4)
Accepts a single geographic field or expression and returns a Geographic Markup Language (GML) representation of the geometry.
Example:
>>> qs = Zipcode.objects.annotate(gml=AsGML('poly'))
>>> print(qs[0].gml)
<gml:Polygon srsName="EPSG:4326"><gml:OuterBoundaryIs>147.78711,70.245363 ...
147.78711,70.245363</gml:OuterBoundaryIs></gml:Polygon>
Keyword Argument  Description 

precision 
It may be used to specify the number of significant digits for the coordinates in the GML representation – the default value is 8. 
version 
It may be used to specify the GML version used, and may only be values of 2 or 3. The default value is 2. 
AsKML
¶
Availability: PostGIS, SpatiaLite (≥ 2.4.0RC4)
Accepts a single geographic field or expression and returns a Keyhole Markup Language (KML) representation of the geometry.
Example:
>>> qs = Zipcode.objects.annotate(kml=AsKML('poly'))
>>> print(qs[0].kml)
<Polygon><outerBoundaryIs><LinearRing><coordinates>103.04135,36.217596,0 ...
103.04135,36.217596,0</coordinates></LinearRing></outerBoundaryIs></Polygon>
Keyword Argument  Description 

precision 
This keyword may be used to specify the number of significant digits for the coordinates in the KML representation – the default value is 8. 
AsSVG
¶
Availability: PostGIS, SpatiaLite
Accepts a single geographic field or expression and returns a Scalable Vector Graphics (SVG) representation of the geometry.
Keyword Argument  Description 

relative 
If set to True , the path data will be implemented
in terms of relative moves. Defaults to False ,
meaning that absolute moves are used instead. 
precision 
This keyword may be used to specify the number of significant digits for the coordinates in the SVG representation – the default value is 8. 
BoundingCircle
¶
Availability: PostGIS
Accepts a single geographic field or expression and returns the smallest circle polygon that can fully contain the geometry.
Centroid
¶
Availability: MySQL, PostGIS, Oracle, SpatiaLite
Accepts a single geographic field or expression and returns the centroid
value of the geometry.
Difference
¶
Availability: PostGIS, Oracle, SpatiaLite
Accepts two geographic fields or expressions and returns the geometric difference, that is the part of geometry A that does not intersect with geometry B.
Distance
¶
Availability: MySQL (≥ 5.6.1), PostGIS, Oracle, SpatiaLite
Accepts two geographic fields or expressions and returns the distance between
them, as a Distance
object. On MySQL, a raw
float value is returned, as it’s not possible to automatically determine the
unit of the field.
On backends that support distance calculation on geodetic coordinates, the
proper backend function is automatically chosen depending on the SRID value of
the geometries (e.g. ST_Distance_Sphere
on PostGIS).
When distances are calculated with geodetic (angular) coordinates, as is the
case with the default WGS84 (4326) SRID, you can set the spheroid
keyword
argument to decide if the calculation should be based on a simple sphere (less
accurate, less resourceintensive) or on a spheroid (more accurate, more
resourceintensive).
In the following example, the distance from the city of Hobart to every other
PointField
in the AustraliaCity
queryset is calculated:
>>> from django.contrib.gis.db.models.functions import Distance
>>> pnt = AustraliaCity.objects.get(name='Hobart').point
>>> for city in AustraliaCity.objects.annotate(distance=Distance('point', pnt)):
... print(city.name, city.distance)
Wollongong 990071.220408 m
Shellharbour 972804.613941 m
Thirroul 1002334.36351 m
...
Note
Because the distance
attribute is a
Distance
object, you can easily express
the value in the units of your choice. For example, city.distance.mi
is
the distance value in miles and city.distance.km
is the distance value
in kilometers. See Measurement Objects for usage details and the list of
Supported units.
Envelope
¶
Availability: MySQL, PostGIS, SpatiaLite
Accepts a single geographic field or expression and returns the geometry representing the bounding box of the geometry.
ForceRHR
¶
Availability: PostGIS
Accepts a single geographic field or expression and returns a modified version of the polygon/multipolygon in which all of the vertices follow the righthand rule.
GeoHash
¶
Availability: PostGIS
Accepts a single geographic field or expression and returns a GeoHash representation of the geometry.
Intersection
¶
Availability: PostGIS, Oracle, SpatiaLite
Accepts two geographic fields or expressions and returns the geometric intersection between them.
Length
¶
Availability: MySQL, Oracle, PostGIS, SpatiaLite
Accepts a single geographic linestring or multilinestring field or expression
and returns its length as an Distance
measure. On MySQL, a raw float value is returned, as it’s not possible to
automatically determine the unit of the field.
On PostGIS and SpatiaLite, when the coordinates are geodetic (angular), you can
specify if the calculation should be based on a simple sphere (less
accurate, less resourceintensive) or on a spheroid (more accurate, more
resourceintensive) with the spheroid
keyword argument.
MemSize
¶
Availability: PostGIS
Accepts a single geographic field or expression and returns the memory size (number of bytes) that the geometry field takes.
NumGeometries
¶
Availability: MySQL, PostGIS, Oracle, SpatiaLite
Accepts a single geographic field or expression and returns the number of
geometries if the geometry field is a collection (e.g., a GEOMETRYCOLLECTION
or MULTI*
field); otherwise returns None
.
NumPoints
¶
Availability: MySQL, PostGIS, Oracle, SpatiaLite
Accepts a single geographic field or expression and returns the number of points
in the first linestring in the geometry field; otherwise returns None
.
Perimeter
¶
Availability: PostGIS, Oracle, SpatiaLite (≥ 4.0)
Accepts a single geographic field or expression and returns the perimeter of the
geometry field as a Distance
object. On
MySQL, a raw float value is returned, as it’s not possible to automatically
determine the unit of the field.
PointOnSurface
¶
Availability: PostGIS, Oracle, SpatiaLite
Accepts a single geographic field or expression and returns a Point
geometry
guaranteed to lie on the surface of the field; otherwise returns None
.
Reverse
¶
Availability: PostGIS, Oracle, SpatiaLite (≥ 4.0)
Accepts a single geographic field or expression and returns a geometry with reversed coordinates.
Scale
¶
Availability: PostGIS, SpatiaLite
Accepts a single geographic field or expression and returns a geometry with
scaled coordinates by multiplying them with the x
, y
, and optionally
z
parameters.
SnapToGrid
¶
Availability: PostGIS, SpatiaLite (≥ 3.1)
Accepts a single geographic field or expression and returns a geometry with all points snapped to the given grid. How the geometry is snapped to the grid depends on how many numeric (either float, integer, or long) arguments are given.
Number of Arguments  Description 

1  A single size to snap both the X and Y grids to. 
2  X and Y sizes to snap the grid to. 
4  X, Y sizes and the corresponding X, Y origins. 
SymDifference
¶
Availability: PostGIS, Oracle, SpatiaLite
Accepts two geographic fields or expressions and returns the geometric symmetric difference (union without the intersection) between the given parameters.
Transform
¶
Availability: PostGIS, Oracle, SpatiaLite
Accepts a geographic field or expression and a SRID integer code, and returns
the transformed geometry to the spatial reference system specified by the
srid
parameter.
Note
What spatial reference system an integer SRID corresponds to may depend on the spatial database used. In other words, the SRID numbers used for Oracle are not necessarily the same as those used by PostGIS.
Translate
¶
Availability: PostGIS, SpatiaLite
Accepts a single geographic field or expression and returns a geometry with
its coordinates offset by the x
, y
, and optionally z
numeric
parameters.