Skip to main content

Near distance band

Find entities between two distances in one near query. georel=near;minDistance==500;maxDistance==10000 matches everything at least 500 m and at most 10 km from the reference geometry. Off by default.

At a glance​

Turning it on​

[extensions.near_distance_band]
mode = "enabled"

Using it​

GET /ngsi-ld/v1/entities?type=Station&georel=near;minDistance==500;maxDistance==10000&geometry=Point&coordinates=[-3.7038,40.4168]

Both distances keep their usual meaning and apply together. maxDistance==d holds when the shortest distance between the entity's geometry and the reference geometry is at most d metres, and minDistance==d when it is at least d. What near measures explains how the distance is measured. The order of the two doesn't matter.

You can use a band anywhere you write a geoquery:

  • Query Entities, by GET and POST
  • temporal queries, by GET and POST
  • a subscription geoQ, on create and on update
  • registration discovery

A subscription stored with a band while the extension was on keeps matching after you turn it off. Only new writes are refused.

What gets refused​

These are refused whether the extension is on or off, because no reading of the geoquery grammar allows them:

  • 400 BadRequestData for the same distance twice, such as near;maxDistance==5;maxDistance==9

    Give each distance once.

  • 400 BadRequestData for a distance on any relation other than near, such as within;maxDistance==5

    Only near takes a distance.

  • 400 BadRequestData for whitespace around a segment, or an empty segment, such as near;;maxDistance==5 or a trailing ;

    Write the expression without gaps.

Context sources​

A query with a band is forwarded to the matching registrations as written, whether or not the source advertises nearDistanceBand. A source that doesn't support the band refuses the forwarded request, and its part of the answer is missing.

Why it is an extension​

A near takes one distance in the specification, either maxDistance or minDistance. A near with both is outside the geoquery grammar, and a syntactically invalid geoquery is answered with BadRequestData. A conformant broker refuses the pair.

Last updated on