ST_DWithin Distance Checker

How the ST_DWithin Distance Checker works, and what it assumes

ST_DWithin(A, B, d) is true when some point of A lies within distance d of some point of B, that is, when ST_Distance(A, B) is less than or equal to d. The limit is inclusive. It is the standard proximity test: every restaurant within 500 m, every property within the notification distance of a planned works site.

In a database it is preferred over ST_Distance(a, b) < d because it can use a spatial index to rule out distant rows before measuring anything; the answer is identical. Here, where only one pair is involved, the page shows both: the verdict and the actual distance, with how far inside or beyond the limit it falls.

Units work as on the ST_Distance page. Coordinate units use the numbers as they are, which means degrees for longitude and latitude; Metres measure on the WGS 84 ellipsoid. In metres mode, if the distance lies within the measurement's possible error of the limit, the page says the answer is too close to call instead of presenting a coin toss as a fact. An empty geometry is never within any distance.

Where this comes up in GIS work

• Testing a proximity rule, such as no licensed premises within 400 m of a school.
• Checking the radius of a store-locator or a find-nearby query before writing it.
• Deciding whether an asset falls inside a notification distance of planned works.

A worked example

The example pair from the ST_Distance page, 1,196.2 m apart, against two limits:

ST_DWithin(A, B, 1500) = true    (303.8 m inside the limit)
ST_DWithin(A, B, 1000) = false   (196.2 m beyond the limit)

In coordinate units the same test would compare 0.0151 degrees with 1500 degrees and return true for any two places on earth, which is why the page warns when degrees are being used as a distance.

Using the ST_DWithin Distance Checker

1. Paste the first geometry into Geometry A, or select Load example.
2. Paste the second geometry into Geometry B.
3. Enter the distance to test and choose Metres or Coordinate units.
4. Select Check ST_DWithin, or press Ctrl + Enter (Cmd + Enter on a Mac).
5. Read the verdict, the actual distance and how far inside or beyond the limit it is.

When the output looks wrong

Everything is within the distance

On longitude and latitude with Coordinate units, the distance is in degrees, so 500 means 500 degrees, which covers the planet. Choose Metres to test a distance on the ground.

The answer is too close to call

The measured distance is within the measurement's possible error of the limit, which happens only for geometries spread over very large areas. Measure smaller pieces, or confirm with PostGIS geography.

ST_DWithin is true but ST_Distance equals the limit exactly

ST_DWithin includes the limit itself: a distance equal to the limit counts as within, as in PostGIS.

Questions about the ST_DWithin Distance Checker