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

Geographic Database FunctionsLink to this heading#

\n\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
Code
>>> 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\n\n\n\n\n\n\n\n

Measurement

Relationships

Operations

Editors

Output format

Miscellaneous

Area

BoundingCircle

Difference

ForceRHR

AsGeoJSON

IsValid

Distance

Centroid

Intersection

MakeValid

AsGML

MemSize

Length

Envelope

SymDifference

Reverse

AsKML

NumGeometries

Perimeter

PointOnSurface

Union

Scale

AsSVG

NumPoints

SnapToGrid

GeoHash

Transform

Translate

\n
\n
\n

AreaLink to this heading#

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

Availability: MySQL, Oracle, PostGIS, SpatiaLite

\n

Accepts a single geographic field or expression and returns the area of the\nfield as an Area measure. On MySQL, a raw\nfloat value is returned, as it’s not possible to automatically determine the\nunit of the field.

\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: PostGIS, SpatiaLite

\n

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

\n

Example:

\n
Code
>>> 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.

crs

Set this to True if you want the coordinate\nreference system to be included in the returned\nGeoJSON.

precision

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

\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: PostGIS, SpatiaLite

\n

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

\n

Example:

\n
Code
>>> 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.

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

BoundingCircleLink to this heading#

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

Availability: PostGIS

\n

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

\n
\n
\n

CentroidLink to this heading#

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

Availability: MySQL, PostGIS, 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: MySQL (≥ 5.6.1), PostGIS, 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
\n

DistanceLink to this heading#

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

Availability: MySQL (≥ 5.6.1), PostGIS, 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, as it’s not possible to automatically determine the\nunit of the field.

\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_Distance_Sphere 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
Code
>>> 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)\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: MySQL, PostGIS, SpatiaLite

\n

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

\n
\n
\n

ForceRHRLink to this heading#

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

Availability: PostGIS

\n

Accepts a single geographic field or expression and returns a modified version\nof the polygon/multipolygon in which all of the vertices follow the\nright-hand rule.

\n
\n
\n

GeoHashLink to this heading#

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

Availability: PostGIS, SpatiaLite (≥ 4.0, LWGEOM)

\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
\n

IntersectionLink to this heading#

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

Availability: MySQL (≥ 5.6.1), PostGIS, Oracle, SpatiaLite

\n

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

\n\n
\n
\n

IsValidLink to this heading#

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

Availability: PostGIS

\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: MySQL, Oracle, PostGIS, SpatiaLite

\n

Accepts a single geographic linestring or multilinestring field or expression\nand returns its length as an Distance\nmeasure. On MySQL, a raw float value is returned, as it’s not possible to\nautomatically determine the unit of the field.

\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
\n
\n

MakeValidLink to this heading#

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

Availability: PostGIS

\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: MySQL, PostGIS, Oracle, SpatiaLite

\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); otherwise returns None.

\n
\n
\n

NumPointsLink to this heading#

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

Availability: MySQL, PostGIS, Oracle, SpatiaLite

\n

Accepts a single geographic field or expression and returns the number of points\nin the first linestring in the geometry field; otherwise returns None.

\n
\n
\n

PerimeterLink to this heading#

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

Availability: PostGIS, Oracle, SpatiaLite (≥ 4.0)

\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, 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, SpatiaLite (≥ 4.0)

\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, SpatiaLite (≥ 3.1)

\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: MySQL (≥ 5.6.1), PostGIS, Oracle, SpatiaLite

\n

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

\n\n
\n
\n

TransformLink to this heading#

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

Availability: PostGIS, Oracle, 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, SpatiaLite

\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: MySQL (≥ 5.6.1), PostGIS, 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":"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":"ForceRHR","anchor":"forcerhr","children":[]},{"title":"GeoHash","anchor":"geohash","children":[]},{"title":"Intersection","anchor":"intersection","children":[]},{"title":"IsValid","anchor":"isvalid","children":[]},{"title":"Length","anchor":"length","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":"/el/1.10/ref/"},{"docname":"ref/contrib/index","title":"contrib packages","url":"/el/1.10/ref/contrib/"},{"docname":"ref/contrib/gis/index","title":"GeoDjango","url":"/el/1.10/ref/contrib/gis/"}],"prev":{"docname":"ref/contrib/gis/geoquerysets","title":"GeoQuerySet API Reference","url":"/el/1.10/ref/contrib/gis/geoquerysets/"},"next":{"docname":"ref/contrib/gis/measure","title":"Measurement Objects","url":"/el/1.10/ref/contrib/gis/measure/"},"formats":{"html":"/el/1.10/ref/contrib/gis/functions/","markdown":"/el/1.10/ref/contrib/gis/functions.md","json":"/el/1.10/ref/contrib/gis/functions.json"},"source":"https://github.com/django/django/blob/stable/1.10.x/docs/ref/contrib/gis/functions.txt","official":"https://docs.djangoproject.com/el/1.10/ref/contrib/gis/functions/","inVersions":["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"],"inLocales":["en","fr","ja","id","pt-br","es","el","pl"]}