Geographic Database FunctionsLink to this heading#

AreaLink to this heading#

class Area(expression, **extra)Link to this definition#

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns the area of the field as an Area measure.

MySQL and SpatiaLite without LWGEOM/RTTOPO don’t support area calculations on geographic SRSes.

DistanceLink to this heading#

class Distance(expr1, expr2, spheroid=None, **extra)Link to this definition#

Availability: MariaDB, MySQL, 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 when the coordinates are geodetic.

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_DistanceSphere 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 resource-intensive) or on a spheroid (more accurate, more resource-intensive).

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

GeometryDistanceLink to this heading#

class GeometryDistance(expr1, expr2, **extra)Link to this definition#

Availability: PostGIS

Accepts two geographic fields or expressions and returns the distance between them. When used in an order_by() clause, it provides index-assisted nearest-neighbor result sets.

LengthLink to this heading#

class Length(expression, spheroid=True, **extra)Link to this definition#

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepts a single geographic linestring or multilinestring field or expression and returns its length as a Distance measure.

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 resource-intensive) or on a spheroid (more accurate, more resource-intensive) with the spheroid keyword argument.

MySQL doesn’t support length calculations on geographic SRSes.

PerimeterLink to this heading#

class Perimeter(expression, **extra)Link to this definition#

Availability: PostGIS, Oracle, SpatiaLite

Accepts a single geographic field or expression and returns the perimeter of the geometry field as a Distance object.

AzimuthLink to this heading#

class Azimuth(point_a, point_b, **extra)Link to this definition#

Availability: PostGIS, SpatiaLite (LWGEOM/RTTOPO)

Returns the azimuth in radians of the segment defined by the given point geometries, or None if the two points are coincident. The azimuth is angle referenced from north and is positive clockwise: north = 0; east = π/2; south = π; west = 3π/2.

BoundingCircleLink to this heading#

class BoundingCircle(expression, num_seg=48, **extra)Link to this definition#

Availability: PostGIS, Oracle, SpatiaLite 5.1+

Accepts a single geographic field or expression and returns the smallest circle polygon that can fully contain the geometry.

The num_seg parameter is used only on PostGIS.

CentroidLink to this heading#

class Centroid(expression, **extra)Link to this definition#

Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepts a single geographic field or expression and returns the centroid value of the geometry.

ClosestPointLink to this heading#

class ClosestPoint(expr1, expr2, **extra)Link to this definition#

Availability: PostGIS, SpatiaLite

Accepts two geographic fields or expressions and returns the 2-dimensional point on geometry A that is closest to geometry B.

EnvelopeLink to this heading#

class Envelope(expression, **extra)Link to this definition#

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns the geometry representing the bounding box of the geometry.

LineLocatePointLink to this heading#

class LineLocatePoint(linestring, point, **extra)Link to this definition#

Availability: PostGIS, SpatiaLite

Returns a float between 0 and 1 representing the location of the closest point on linestring to the given point, as a fraction of the 2D line length.

PointOnSurfaceLink to this heading#

class PointOnSurface(expression, **extra)Link to this definition#

Availability: PostGIS, MariaDB, 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.

DifferenceLink to this heading#

class Difference(expr1, expr2, **extra)Link to this definition#

Availability: MariaDB, MySQL, 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.

IntersectionLink to this heading#

class Intersection(expr1, expr2, **extra)Link to this definition#

Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepts two geographic fields or expressions and returns the geometric intersection between them.

SymDifferenceLink to this heading#

class SymDifference(expr1, expr2, **extra)Link to this definition#

Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepts two geographic fields or expressions and returns the geometric symmetric difference (union without the intersection) between the given parameters.

UnionLink to this heading#

class Union(expr1, expr2, **extra)Link to this definition#

Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepts two geographic fields or expressions and returns the union of both geometries.

ForcePolygonCWLink to this heading#

class ForcePolygonCW(expression, **extra)Link to this definition#

Availability: PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns a modified version of the polygon/multipolygon in which all exterior rings are oriented clockwise and all interior rings are oriented counterclockwise. Non-polygonal geometries are returned unchanged.

MakeValidLink to this heading#

class MakeValid(expr)Link to this definition#

Availability: PostGIS, SpatiaLite (LWGEOM/RTTOPO)

Accepts a geographic field or expression and attempts to convert the value into a valid geometry without losing any of the input vertices. Geometries that are already valid are returned without changes. Simple polygons might become a multipolygon and the result might be of lower dimension than the input.

ReverseLink to this heading#

class Reverse(expression, **extra)Link to this definition#

Availability: PostGIS, Oracle, SpatiaLite

Accepts a single geographic field or expression and returns a geometry with reversed coordinates.

RotateLink to this heading#

class Rotate(expression, angle, origin=None, **extra)Link to this definition#

Availability: PostGIS

Rotates a geometry by a specified angle around the origin. Optionally, the rotation can be performed around a point, defined by the origin parameter.

ScaleLink to this heading#

class Scale(expression, x, y, z=0.0, **extra)Link to this definition#

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.

SnapToGridLink to this heading#

class SnapToGrid(expression, *args, **extra)Link to this definition#

Availability: PostGIS, SpatiaLite

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.

TransformLink to this heading#

class Transform(expression, srid, **extra)Link to this definition#

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.

TranslateLink to this heading#

class Translate(expression, x, y, z=0.0, **extra)Link to this definition#

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.

FromWKBLink to this heading#

class FromWKB(expression, srid=0, **extra)Link to this definition#

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Creates geometry from Well-known binary (WKB) representation. The optional srid argument allows to specify the SRID of the resulting geometry. srid is ignored on Oracle.

FromWKTLink to this heading#

class FromWKT(expression, srid=0, **extra)Link to this definition#

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Creates geometry from Well-known text (WKT) representation. The optional srid argument allows to specify the SRID of the resulting geometry. srid is ignored on Oracle.

AsGeoJSONLink to this heading#

class AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)Link to this definition#

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

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]}

AsGMLLink to this heading#

class AsGML(expression, version=2, precision=8, **extra)Link to this definition#

Availability: Oracle, PostGIS, SpatiaLite

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>

AsKMLLink to this heading#

class AsKML(expression, precision=8, **extra)Link to this definition#

Availability: PostGIS, SpatiaLite

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>

AsSVGLink to this heading#

class AsSVG(expression, relative=False, precision=8, **extra)Link to this definition#

Availability: PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns a Scalable Vector Graphics (SVG) representation of the geometry.

AsWKBLink to this heading#

class AsWKB(expression, **extra)Link to this definition#

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns a Well-known binary (WKB) representation of the geometry.

Example:

>>> bytes(City.objects.annotate(wkb=AsWKB("point")).get(name="Chelyabinsk").wkb)
b'\x01\x01\x00\x00\x00]3\xf9f\x9b\x91K@\x00X\x1d9\xd2\xb9N@'

AsWKTLink to this heading#

class AsWKT(expression, **extra)Link to this definition#

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns a Well-known text (WKT) representation of the geometry.

Example:

>>> City.objects.annotate(wkt=AsWKT("point")).get(name="Chelyabinsk").wkt
'POINT (55.137555 61.451728)'

GeoHashLink to this heading#

class GeoHash(expression, precision=None, **extra)Link to this definition#

Availability: MariaDB, MySQL, PostGIS, SpatiaLite (LWGEOM/RTTOPO)

Accepts a single geographic field or expression and returns a GeoHash representation of the geometry.

The precision keyword argument controls the number of characters in the result.

IsEmptyLink to this heading#

class IsEmpty(expr)Link to this definition#

Availability: PostGIS, SpatiaLite

Accepts a geographic field or expression and tests if the value is an empty geometry. Returns True if its value is empty and False otherwise.

IsValidLink to this heading#

class IsValid(expr)Link to this definition#

Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepts a geographic field or expression and tests if the value is well formed. Returns True if its value is a valid geometry and False otherwise.

GeometryTypeLink to this heading#

class GeometryType(expr)Link to this definition#

Availability: PostGIS, Oracle 23c+, MariaDB, MySQL, SpatiaLite

Accepts a geographic field or expression and returns its geometry type.

MemSizeLink to this heading#

class MemSize(expression, **extra)Link to this definition#

Availability: PostGIS

Accepts a single geographic field or expression and returns the memory size (number of bytes) that the geometry field takes.

NumDimensionsLink to this heading#

class NumDimensions(expression, **extra)Link to this definition#

Availability: PostGIS, SpatiaLite

Accepts a single geometry field or expression and returns the number of dimensions used by the geometry.

NumGeometriesLink to this heading#

class NumGeometries(expression, **extra)Link to this definition#

Availability: MariaDB, 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). Returns 1 for single geometries.

On MySQL, returns None for single geometries.

NumPointsLink to this heading#

class NumPoints(expression, **extra)Link to this definition#

Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepts a single geographic field or expression and returns the number of points in a geometry.

On MySQL, returns None for any non-LINESTRING geometry.