{"title":"Geographic Database Functions","version":"4.2","locale":"en","docname":"ref/contrib/gis/functions","url":"/en/4.2/ref/contrib/gis/functions/","canonical":"https://djangodocs.dev/en/4.2/ref/contrib/gis/functions/","summary":"The functions documented on this page allow users to access geographic database functions to be used in annotations, aggregations, or filters in Django. Example:…","html":"

Geographic Database FunctionsLink to this heading#

\n

The functions documented on this page allow users to access geographic database\nfunctions to be used in annotations, aggregations, or filters in Django.

\n

Example:

\n
Python console
>>> from django.contrib.gis.db.models.functions import Length\n>>> Track.objects.annotate(length=Length("line")).filter(length__gt=100)\n
\n

Not all backends support all functions, so refer to the documentation of each\nfunction to see if your database backend supports the function you want to use.\nIf you call a geographic function on a backend that doesn’t support it, you’ll\nget a NotImplementedError exception.

\n

Function’s summary:

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Measurement

Relationships

Operations

Editors

Input format

Output format

Miscellaneous

Area

Azimuth

Difference

ForcePolygonCW

AsGeoJSON

IsEmpty

Distance

BoundingCircle

Intersection

MakeValid

AsGML

IsValid

GeometryDistance

Centroid

SymDifference

Reverse

AsKML

MemSize

Length

Envelope

Union

Scale

AsSVG

NumGeometries

Perimeter

LineLocatePoint\nPointOnSurface

SnapToGrid\nTransform\nTranslate

FromWKB\nFromWKT

AsWKB\nAsWKT\nGeoHash

NumPoints

\n
\n
\n

AreaLink to this heading#

\n
\n
\nclass Area(expression, **extra)Link to this definition#
\n
\n\n

Availability: MariaDB, MySQL,\nOracle, PostGIS, SpatiaLite

\n

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

\n

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

\n
\n
\n

AsGeoJSONLink to this heading#

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

Availability: MariaDB, MySQL,\nOracle, PostGIS, SpatiaLite

\n

Accepts a single geographic field or expression and returns a GeoJSON representation of the geometry. Note that the result\nis not a complete GeoJSON structure but only the geometry key content of a\nGeoJSON structure. See also GeoJSON Serializer.

\n

Example:

\n
Python console
>>> City.objects.annotate(json=AsGeoJSON("point")).get(name="Chicago").json\n{"type":"Point","coordinates":[-87.65018,41.85039]}\n
\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Keyword Argument

Description

bbox

Set this to True if you want the bounding box\nto be included in the returned GeoJSON. Ignored on\nOracle.

crs

Set this to True if you want the coordinate\nreference system to be included in the returned\nGeoJSON. Ignored on MySQL and Oracle.

precision

It may be used to specify the number of significant\ndigits for the coordinates in the GeoJSON\nrepresentation – the default value is 8. Ignored on\nOracle.

\n
\n
\n
\n

AsGMLLink to this heading#

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

Availability: Oracle, PostGIS,\nSpatiaLite

\n

Accepts a single geographic field or expression and returns a Geographic Markup\nLanguage (GML) representation of the geometry.

\n

Example:

\n
Python console
>>> qs = Zipcode.objects.annotate(gml=AsGML("poly"))\n>>> print(qs[0].gml)\n<gml:Polygon srsName="EPSG:4326"><gml:OuterBoundaryIs>-147.78711,70.245363 ...\n-147.78711,70.245363</gml:OuterBoundaryIs></gml:Polygon>\n
\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Keyword Argument

Description

precision

Specifies the number of significant digits for the\ncoordinates in the GML representation – the default\nvalue is 8. Ignored on Oracle.

version

Specifies the GML version to use: 2 (default) or 3.

\n
\n
\n
\n

AsKMLLink to this heading#

\n
\n
\nclass AsKML(expression, precision=8, **extra)Link to this definition#
\n
\n\n

Availability: PostGIS, SpatiaLite

\n

Accepts a single geographic field or expression and returns a Keyhole Markup\nLanguage (KML) representation of the geometry.

\n

Example:

\n
Python console
>>> qs = Zipcode.objects.annotate(kml=AsKML("poly"))\n>>> print(qs[0].kml)\n<Polygon><outerBoundaryIs><LinearRing><coordinates>-103.04135,36.217596,0 ...\n-103.04135,36.217596,0</coordinates></LinearRing></outerBoundaryIs></Polygon>\n
\n
\n\n\n\n\n\n\n\n\n\n\n

Keyword Argument

Description

precision

This keyword may be used to specify the number of\nsignificant digits for the coordinates in the KML\nrepresentation – the default value is 8.

\n
\n
\n
\n

AsSVGLink to this heading#

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

Availability: PostGIS, SpatiaLite

\n

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

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Keyword Argument

Description

relative

If set to True, the path data will be implemented\nin terms of relative moves. Defaults to False,\nmeaning that absolute moves are used instead.

precision

This keyword may be used to specify the number of\nsignificant digits for the coordinates in the SVG\nrepresentation – the default value is 8.

\n
\n
\n
\n

AsWKBLink to this heading#

\n
\n
\nclass AsWKB(expression, **extra)Link to this definition#
\n
\n\n

Availability: MariaDB, MySQL,\nOracle, PostGIS, SpatiaLite

\n

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

\n

Example:

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

AsWKTLink to this heading#

\n
\n
\nclass AsWKT(expression, **extra)Link to this definition#
\n
\n\n

Availability: MariaDB, MySQL,\nOracle, PostGIS, SpatiaLite

\n

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

\n

Example:

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

AzimuthLink to this heading#

\n
\n
\nclass Azimuth(point_a, point_b, **extra)Link to this definition#
\n
\n\n

Availability: PostGIS,\nSpatiaLite (LWGEOM/RTTOPO)

\n

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

\n
\n
\n

BoundingCircleLink to this heading#

\n
\n
\nclass BoundingCircle(expression, num_seg=48, **extra)Link to this definition#
\n
\n\n

Availability: PostGIS,\nOracle

\n

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

\n

The num_seg parameter is used only on PostGIS.

\n
\n
\n

CentroidLink to this heading#

\n
\n
\nclass Centroid(expression, **extra)Link to this definition#
\n
\n\n

Availability: MariaDB, MySQL,\nPostGIS, Oracle, SpatiaLite

\n

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

\n
\n
\n

DifferenceLink to this heading#

\n
\n
\nclass Difference(expr1, expr2, **extra)Link to this definition#
\n
\n\n

Availability: MariaDB, MySQL,\nPostGIS, Oracle, SpatiaLite

\n

Accepts two geographic fields or expressions and returns the geometric\ndifference, that is the part of geometry A that does not intersect with\ngeometry B.

\n
\n
\n

DistanceLink to this heading#

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

Availability: MariaDB, MySQL,\nPostGIS, Oracle, SpatiaLite

\n

Accepts two geographic fields or expressions and returns the distance between\nthem, as a Distance object. On MySQL, a raw\nfloat value is returned when the coordinates are geodetic.

\n

On backends that support distance calculation on geodetic coordinates, the\nproper backend function is automatically chosen depending on the SRID value of\nthe geometries (e.g. ST_DistanceSphere on PostGIS).

\n

When distances are calculated with geodetic (angular) coordinates, as is the\ncase with the default WGS84 (4326) SRID, you can set the spheroid keyword\nargument to decide if the calculation should be based on a simple sphere (less\naccurate, less resource-intensive) or on a spheroid (more accurate, more\nresource-intensive).

\n

In the following example, the distance from the city of Hobart to every other\nPointField in the AustraliaCity\nqueryset is calculated:

\n
Python console
>>> from django.contrib.gis.db.models.functions import Distance\n>>> pnt = AustraliaCity.objects.get(name="Hobart").point\n>>> for city in AustraliaCity.objects.annotate(distance=Distance("point", pnt)):\n...     print(city.name, city.distance)\n...\nWollongong 990071.220408 m\nShellharbour 972804.613941 m\nThirroul 1002334.36351 m\n...\n
\n\n
\n
\n

EnvelopeLink to this heading#

\n
\n
\nclass Envelope(expression, **extra)Link to this definition#
\n
\n\n

Availability: MariaDB, MySQL,\nOracle,\nPostGIS, SpatiaLite

\n

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

\n
\n
\n

ForcePolygonCWLink to this heading#

\n
\n
\nclass ForcePolygonCW(expression, **extra)Link to this definition#
\n
\n\n

Availability: PostGIS,\nSpatiaLite

\n

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

\n
\n
\n

FromWKBLink to this heading#

\n\n
\n
\nclass FromWKB(expression, **extra)Link to this definition#
\n
\n\n

Availability: MariaDB, MySQL,\nOracle, PostGIS, SpatiaLite

\n

Creates geometry from Well-known binary (WKB) representation.

\n
\n
\n

FromWKTLink to this heading#

\n\n
\n
\nclass FromWKT(expression, **extra)Link to this definition#
\n
\n\n

Availability: MariaDB, MySQL,\nOracle, PostGIS, SpatiaLite

\n

Creates geometry from Well-known text (WKT) representation.

\n
\n
\n

GeoHashLink to this heading#

\n
\n
\nclass GeoHash(expression, precision=None, **extra)Link to this definition#
\n
\n\n

Availability: MySQL,\nPostGIS, SpatiaLite\n(LWGEOM/RTTOPO)

\n

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

\n

The precision keyword argument controls the number of characters in the\nresult.

\n
\n
\n

GeometryDistanceLink to this heading#

\n
\n
\nclass GeometryDistance(expr1, expr2, **extra)Link to this definition#
\n
\n\n

Availability: PostGIS

\n

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

\n
\n
\n

IntersectionLink to this heading#

\n
\n
\nclass Intersection(expr1, expr2, **extra)Link to this definition#
\n
\n\n

Availability: MariaDB, MySQL,\nPostGIS, Oracle, SpatiaLite

\n

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

\n
\n
\n

IsEmptyLink to this heading#

\n\n
\n
\nclass IsEmpty(expr)Link to this definition#
\n
\n\n

Availability: PostGIS

\n

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

\n
\n
\n

IsValidLink to this heading#

\n
\n
\nclass IsValid(expr)Link to this definition#
\n
\n\n

Availability: MySQL,\nPostGIS, Oracle, SpatiaLite

\n

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

\n
\n
\n

LengthLink to this heading#

\n
\n
\nclass Length(expression, spheroid=True, **extra)Link to this definition#
\n
\n\n

Availability: MariaDB, MySQL,\nOracle, PostGIS, SpatiaLite

\n

Accepts a single geographic linestring or multilinestring field or expression\nand returns its length as a Distance\nmeasure.

\n

On PostGIS and SpatiaLite, when the coordinates are geodetic (angular), you can\nspecify if the calculation should be based on a simple sphere (less\naccurate, less resource-intensive) or on a spheroid (more accurate, more\nresource-intensive) with the spheroid keyword argument.

\n

MySQL doesn’t support length calculations on geographic SRSes.

\n
\n
\n

LineLocatePointLink to this heading#

\n
\n
\nclass LineLocatePoint(linestring, point, **extra)Link to this definition#
\n
\n\n

Availability: PostGIS,\nSpatiaLite

\n

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

\n
\n
\n

MakeValidLink to this heading#

\n
\n
\nclass MakeValid(expr)Link to this definition#
\n
\n\n

Availability: PostGIS,\nSpatiaLite (LWGEOM/RTTOPO)

\n

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

\n
\n
\n

MemSizeLink to this heading#

\n
\n
\nclass MemSize(expression, **extra)Link to this definition#
\n
\n\n

Availability: PostGIS

\n

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

\n
\n
\n

NumGeometriesLink to this heading#

\n
\n
\nclass NumGeometries(expression, **extra)Link to this definition#
\n
\n\n

Availability: MariaDB, MySQL,\nPostGIS, Oracle,\nSpatiaLite

\n

Accepts a single geographic field or expression and returns the number of\ngeometries if the geometry field is a collection (e.g., a GEOMETRYCOLLECTION\nor MULTI* field). Returns 1 for single geometries.

\n

On MySQL, returns None for single geometries.

\n
\n
\n

NumPointsLink to this heading#

\n
\n
\nclass NumPoints(expression, **extra)Link to this definition#
\n
\n\n

Availability: MariaDB, MySQL,\nPostGIS, Oracle, SpatiaLite

\n

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

\n

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

\n
\n
\n

PerimeterLink to this heading#

\n
\n
\nclass Perimeter(expression, **extra)Link to this definition#
\n
\n\n

Availability: PostGIS,\nOracle, SpatiaLite

\n

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

\n
\n
\n

PointOnSurfaceLink to this heading#

\n
\n
\nclass PointOnSurface(expression, **extra)Link to this definition#
\n
\n\n

Availability: PostGIS,\nMariaDB, Oracle, SpatiaLite

\n

Accepts a single geographic field or expression and returns a Point geometry\nguaranteed to lie on the surface of the field; otherwise returns None.

\n
\n
\n

ReverseLink to this heading#

\n
\n
\nclass Reverse(expression, **extra)Link to this definition#
\n
\n\n

Availability: PostGIS, Oracle,\nSpatiaLite

\n

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

\n
\n
\n

ScaleLink to this heading#

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

Availability: PostGIS, SpatiaLite

\n

Accepts a single geographic field or expression and returns a geometry with\nscaled coordinates by multiplying them with the x, y, and optionally\nz parameters.

\n
\n
\n

SnapToGridLink to this heading#

\n
\n
\nclass SnapToGrid(expression, *args, **extra)Link to this definition#
\n
\n\n

Availability: PostGIS,\nSpatiaLite

\n

Accepts a single geographic field or expression and returns a geometry with all\npoints snapped to the given grid. How the geometry is snapped to the grid\ndepends on how many numeric (either float, integer, or long) arguments are\ngiven.

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

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.

\n
\n
\n
\n

SymDifferenceLink to this heading#

\n
\n
\nclass SymDifference(expr1, expr2, **extra)Link to this definition#
\n
\n\n

Availability: MariaDB, MySQL,\nPostGIS, Oracle,\nSpatiaLite

\n

Accepts two geographic fields or expressions and returns the geometric\nsymmetric difference (union without the intersection) between the given\nparameters.

\n
\n
\n

TransformLink to this heading#

\n
\n
\nclass Transform(expression, srid, **extra)Link to this definition#
\n
\n\n

Availability: PostGIS,\nOracle, SpatiaLite

\n

Accepts a geographic field or expression and a SRID integer code, and returns\nthe transformed geometry to the spatial reference system specified by the\nsrid parameter.

\n\n
\n
\n

TranslateLink to this heading#

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

Availability: PostGIS,\nSpatiaLite

\n

Accepts a single geographic field or expression and returns a geometry with\nits coordinates offset by the x, y, and optionally z numeric\nparameters.

\n
\n
\n

UnionLink to this heading#

\n
\n
\nclass Union(expr1, expr2, **extra)Link to this definition#
\n
\n\n

Availability: MariaDB, MySQL,\nPostGIS, Oracle, SpatiaLite

\n

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

\n
","rootId":"module-django.contrib.gis.db.models.functions","toc":[{"title":"Area","anchor":"area","children":[]},{"title":"AsGeoJSON","anchor":"asgeojson","children":[]},{"title":"AsGML","anchor":"asgml","children":[]},{"title":"AsKML","anchor":"askml","children":[]},{"title":"AsSVG","anchor":"assvg","children":[]},{"title":"AsWKB","anchor":"aswkb","children":[]},{"title":"AsWKT","anchor":"aswkt","children":[]},{"title":"Azimuth","anchor":"azimuth","children":[]},{"title":"BoundingCircle","anchor":"boundingcircle","children":[]},{"title":"Centroid","anchor":"centroid","children":[]},{"title":"Difference","anchor":"difference","children":[]},{"title":"Distance","anchor":"distance","children":[]},{"title":"Envelope","anchor":"envelope","children":[]},{"title":"ForcePolygonCW","anchor":"forcepolygoncw","children":[]},{"title":"FromWKB","anchor":"fromwkb","children":[]},{"title":"FromWKT","anchor":"fromwkt","children":[]},{"title":"GeoHash","anchor":"geohash","children":[]},{"title":"GeometryDistance","anchor":"geometrydistance","children":[]},{"title":"Intersection","anchor":"intersection","children":[]},{"title":"IsEmpty","anchor":"isempty","children":[]},{"title":"IsValid","anchor":"isvalid","children":[]},{"title":"Length","anchor":"length","children":[]},{"title":"LineLocatePoint","anchor":"linelocatepoint","children":[]},{"title":"MakeValid","anchor":"makevalid","children":[]},{"title":"MemSize","anchor":"memsize","children":[]},{"title":"NumGeometries","anchor":"numgeometries","children":[]},{"title":"NumPoints","anchor":"numpoints","children":[]},{"title":"Perimeter","anchor":"perimeter","children":[]},{"title":"PointOnSurface","anchor":"pointonsurface","children":[]},{"title":"Reverse","anchor":"reverse","children":[]},{"title":"Scale","anchor":"scale","children":[]},{"title":"SnapToGrid","anchor":"snaptogrid","children":[]},{"title":"SymDifference","anchor":"symdifference","children":[]},{"title":"Transform","anchor":"transform","children":[]},{"title":"Translate","anchor":"translate","children":[]},{"title":"Union","anchor":"union","children":[]}],"breadcrumbs":[{"docname":"ref/index","title":"API Reference","url":"/en/4.2/ref/"},{"docname":"ref/contrib/index","title":"contrib packages","url":"/en/4.2/ref/contrib/"},{"docname":"ref/contrib/gis/index","title":"GeoDjango","url":"/en/4.2/ref/contrib/gis/"}],"prev":{"docname":"ref/contrib/gis/geoquerysets","title":"GIS QuerySet API Reference","url":"/en/4.2/ref/contrib/gis/geoquerysets/"},"next":{"docname":"ref/contrib/gis/measure","title":"Measurement Objects","url":"/en/4.2/ref/contrib/gis/measure/"},"formats":{"html":"/en/4.2/ref/contrib/gis/functions/","markdown":"/en/4.2/ref/contrib/gis/functions.md","json":"/en/4.2/ref/contrib/gis/functions.json"},"source":"https://github.com/django/django/blob/stable/4.2.x/docs/ref/contrib/gis/functions.txt","official":"https://docs.djangoproject.com/en/4.2/ref/contrib/gis/functions/","inVersions":["dev","6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0","1.11","1.10","1.9"],"inLocales":["en","zh-hans","fr","ja","id","it","pt-br","ko","es","el","pl"]}